foundry-mcp 0.7.0__py3-none-any.whl → 0.8.10__py3-none-any.whl

foundry_mcp/core/responses.py

@@ -144,6 +144,7 @@ class ErrorCode(str, Enum):
     BACKUP_CORRUPTED = "BACKUP_CORRUPTED"
     ROLLBACK_FAILED = "ROLLBACK_FAILED"
     COMPARISON_FAILED = "COMPARISON_FAILED"
+    OPERATION_FAILED = "OPERATION_FAILED"
 
     # AI/LLM Provider errors
     AI_NO_PROVIDER = "AI_NO_PROVIDER"
@@ -1331,6 +1332,13 @@ def ai_cache_stale_error(
 # ---------------------------------------------------------------------------
 
 
+try:
+    from pydantic import BaseModel, Field
+    PYDANTIC_AVAILABLE = True
+except ImportError:
+    PYDANTIC_AVAILABLE = False
+
+
 def sanitize_error_message(
     exc: Exception,
     context: str = "",
@@ -1382,3 +1390,235 @@ def sanitize_error_message(
     # Generic fallback - don't expose exception message
     suffix = f" ({type_name})" if include_type else ""
     return f"An internal error occurred{suffix}"
+
+
+# ---------------------------------------------------------------------------
+# Batch Operation Response Schemas (Pydantic)
+# ---------------------------------------------------------------------------
+# These schemas provide type-safe definitions for batch operation responses.
+# They ensure contract stability and enable validation of batch operation data.
+
+
+if PYDANTIC_AVAILABLE:
+
+    class DependencyNode(BaseModel):
+        """A node in the dependency graph representing a task."""
+
+        id: str = Field(..., description="Task identifier")
+        title: str = Field(default="", description="Task title")
+        status: str = Field(default="", description="Task status")
+        file_path: Optional[str] = Field(
+            default=None, description="File path associated with the task"
+        )
+        is_target: bool = Field(
+            default=False, description="Whether this is a target task in the batch"
+        )
+
+    class DependencyEdge(BaseModel):
+        """An edge in the dependency graph representing a dependency relationship."""
+
+        from_id: str = Field(..., alias="from", description="Source task ID")
+        to_id: str = Field(..., alias="to", description="Target task ID")
+        edge_type: str = Field(
+            default="blocks", alias="type", description="Type of dependency (blocks)"
+        )
+
+        model_config = {"populate_by_name": True}
+
+    class DependencyGraph(BaseModel):
+        """Dependency graph structure for batch tasks.
+
+        Contains nodes (tasks) and edges (dependency relationships) to visualize
+        task dependencies for parallel execution planning.
+        """
+
+        nodes: list[DependencyNode] = Field(
+            default_factory=list, description="Task nodes in the graph"
+        )
+        edges: list[DependencyEdge] = Field(
+            default_factory=list, description="Dependency edges between tasks"
+        )
+
+    class BatchTaskDependencies(BaseModel):
+        """Dependency status for a task in a batch."""
+
+        task_id: str = Field(..., description="Task identifier")
+        can_start: bool = Field(
+            default=True, description="Whether the task can be started"
+        )
+        blocked_by: list[str] = Field(
+            default_factory=list, description="IDs of tasks blocking this one"
+        )
+        soft_depends: list[str] = Field(
+            default_factory=list, description="IDs of soft dependencies"
+        )
+        blocks: list[str] = Field(
+            default_factory=list, description="IDs of tasks this one blocks"
+        )
+
+    class BatchTaskContext(BaseModel):
+        """Context for a single task in a batch prepare response.
+
+        Contains all information needed to execute a task in parallel with others.
+        """
+
+        task_id: str = Field(..., description="Unique task identifier")
+        title: str = Field(default="", description="Task title")
+        task_type: str = Field(
+            default="task", alias="type", description="Task type (task, subtask, verify)"
+        )
+        status: str = Field(default="pending", description="Current task status")
+        metadata: Dict[str, Any] = Field(
+            default_factory=dict,
+            description="Task metadata including file_path, description, etc.",
+        )
+        dependencies: Optional[BatchTaskDependencies] = Field(
+            default=None, description="Dependency status for the task"
+        )
+        phase: Optional[Dict[str, Any]] = Field(
+            default=None, description="Phase context (id, title, progress)"
+        )
+        parent: Optional[Dict[str, Any]] = Field(
+            default=None, description="Parent task context (id, title, position_label)"
+        )
+
+        model_config = {"populate_by_name": True}
+
+    class StaleTaskInfo(BaseModel):
+        """Information about a stale in_progress task."""
+
+        task_id: str = Field(..., description="Task identifier")
+        title: str = Field(default="", description="Task title")
+
+    class BatchPrepareResponse(BaseModel):
+        """Response schema for prepare_batch_context operation.
+
+        Contains independent tasks that can be executed in parallel along with
+        context, dependency information, and warnings.
+        """
+
+        tasks: list[BatchTaskContext] = Field(
+            default_factory=list, description="Tasks ready for parallel execution"
+        )
+        task_count: int = Field(default=0, description="Number of tasks in the batch")
+        spec_complete: bool = Field(
+            default=False, description="Whether the spec has no remaining tasks"
+        )
+        all_blocked: bool = Field(
+            default=False, description="Whether all remaining tasks are blocked"
+        )
+        warnings: list[str] = Field(
+            default_factory=list, description="Non-fatal warnings about the batch"
+        )
+        stale_tasks: list[StaleTaskInfo] = Field(
+            default_factory=list, description="In-progress tasks exceeding time threshold"
+        )
+        dependency_graph: DependencyGraph = Field(
+            default_factory=DependencyGraph,
+            description="Dependency graph for batch tasks",
+        )
+        token_estimate: Optional[int] = Field(
+            default=None, description="Estimated token count for the batch context"
+        )
+
+    class BatchStartResponse(BaseModel):
+        """Response schema for start_batch operation.
+
+        Confirms which tasks were atomically started and when.
+        """
+
+        started: list[str] = Field(
+            default_factory=list, description="IDs of tasks successfully started"
+        )
+        started_count: int = Field(
+            default=0, description="Number of tasks started"
+        )
+        started_at: Optional[str] = Field(
+            default=None, description="ISO timestamp when tasks were started"
+        )
+        errors: Optional[list[str]] = Field(
+            default=None, description="Validation errors if operation failed"
+        )
+
+    class BatchTaskCompletion(BaseModel):
+        """Input schema for a single task completion in complete_batch.
+
+        Used to specify outcome for each task being completed.
+        """
+
+        task_id: str = Field(..., description="Task identifier to complete")
+        success: bool = Field(
+            ..., description="True if task succeeded, False if failed"
+        )
+        completion_note: str = Field(
+            default="", description="Note describing what was accomplished or why it failed"
+        )
+
+    class BatchTaskResult(BaseModel):
+        """Result for a single task in the complete_batch response."""
+
+        status: str = Field(
+            ..., description="Result status: completed, failed, skipped, error"
+        )
+        completed_at: Optional[str] = Field(
+            default=None, description="ISO timestamp when completed (if successful)"
+        )
+        failed_at: Optional[str] = Field(
+            default=None, description="ISO timestamp when failed (if unsuccessful)"
+        )
+        retry_count: Optional[int] = Field(
+            default=None, description="Updated retry count (if failed)"
+        )
+        error: Optional[str] = Field(
+            default=None, description="Error message (if status is error or skipped)"
+        )
+
+    class BatchCompleteResponse(BaseModel):
+        """Response schema for complete_batch operation.
+
+        Contains per-task results and summary counts for the batch completion.
+        """
+
+        results: Dict[str, BatchTaskResult] = Field(
+            default_factory=dict,
+            description="Per-task results keyed by task_id",
+        )
+        completed_count: int = Field(
+            default=0, description="Number of tasks successfully completed"
+        )
+        failed_count: int = Field(
+            default=0, description="Number of tasks that failed"
+        )
+        total_processed: int = Field(
+            default=0, description="Total number of completions processed"
+        )
+
+    # Export Pydantic models
+    __all_pydantic__ = [
+        "DependencyNode",
+        "DependencyEdge",
+        "DependencyGraph",
+        "BatchTaskDependencies",
+        "BatchTaskContext",
+        "StaleTaskInfo",
+        "BatchPrepareResponse",
+        "BatchStartResponse",
+        "BatchTaskCompletion",
+        "BatchTaskResult",
+        "BatchCompleteResponse",
+    ]
+
+else:
+    # Pydantic not available - provide None placeholders
+    DependencyNode = None  # type: ignore[misc,assignment]
+    DependencyEdge = None  # type: ignore[misc,assignment]
+    DependencyGraph = None  # type: ignore[misc,assignment]
+    BatchTaskDependencies = None  # type: ignore[misc,assignment]
+    BatchTaskContext = None  # type: ignore[misc,assignment]
+    StaleTaskInfo = None  # type: ignore[misc,assignment]
+    BatchPrepareResponse = None  # type: ignore[misc,assignment]
+    BatchStartResponse = None  # type: ignore[misc,assignment]
+    BatchTaskCompletion = None  # type: ignore[misc,assignment]
+    BatchTaskResult = None  # type: ignore[misc,assignment]
+    BatchCompleteResponse = None  # type: ignore[misc,assignment]
+    __all_pydantic__ = []

foundry_mcp/core/spec.py

@@ -931,6 +931,7 @@ def _validate_spec_structure(spec_data: Dict[str, Any]) -> bool:
             "in_progress",
             "completed",
             "blocked",
+            "failed",
         ]:
             return False
 

foundry_mcp/core/task.py

@@ -19,7 +19,7 @@ from foundry_mcp.core.spec import (
 from foundry_mcp.core.responses import success_response, error_response
 
 # Valid task types for add_task
-TASK_TYPES = ("task", "subtask", "verify")
+TASK_TYPES = ("task", "subtask", "verify", "research")
 
 
 def is_unblocked(spec_data: Dict[str, Any], task_id: str, task_data: Dict[str, Any]) -> bool:
@@ -31,6 +31,11 @@ def is_unblocked(spec_data: Dict[str, Any], task_id: str, task_data: Dict[str, A
     1. Any of its direct task dependencies are not completed, OR
     2. Its parent phase is blocked by an incomplete phase
 
+    Research nodes have special blocking behavior based on blocking_mode:
+    - "none": Research doesn't block dependents
+    - "soft": Research is informational, doesn't block (default)
+    - "hard": Research must complete before dependents can start
+
     Args:
         spec_data: JSON spec file data
         task_id: Task identifier
@@ -45,7 +50,18 @@ def is_unblocked(spec_data: Dict[str, Any], task_id: str, task_data: Dict[str, A
     blocked_by = task_data.get("dependencies", {}).get("blocked_by", [])
     for blocker_id in blocked_by:
         blocker = hierarchy.get(blocker_id)
-        if not blocker or blocker.get("status") != "completed":
+        if not blocker:
+            continue
+
+        # Special handling for research nodes based on blocking_mode
+        if blocker.get("type") == "research":
+            blocking_mode = blocker.get("metadata", {}).get("blocking_mode", "soft")
+            if blocking_mode in ("none", "soft"):
+                # Research with "none" or "soft" blocking mode doesn't block
+                continue
+            # "hard" mode falls through to standard completion check
+
+        if blocker.get("status") != "completed":
             return False
 
     # Check phase-level dependencies
@@ -533,6 +549,82 @@ def get_task_journal_summary(
     }
 
 
+def _compute_auto_mode_hints(
+    spec_data: Dict[str, Any],
+    task_id: str,
+    task_data: Dict[str, Any],
+) -> Dict[str, Any]:
+    """
+    Compute hints for autonomous mode execution.
+
+    These hints help an autonomous agent decide whether to proceed
+    without user input or pause for confirmation.
+
+    Args:
+        spec_data: Loaded spec data
+        task_id: Current task ID
+        task_data: Task node data
+
+    Returns:
+        Dictionary with autonomous mode hints:
+        - estimated_complexity: "low", "medium", or "high"
+        - has_sibling_verify: bool (phase has verify tasks)
+        - may_require_user_input: bool (task category suggests user input needed)
+    """
+    hierarchy = spec_data.get("hierarchy", {})
+    metadata = task_data.get("metadata", {}) or {}
+
+    # Compute estimated_complexity
+    complexity = metadata.get("complexity", "").lower()
+    estimated_hours = metadata.get("estimated_hours")
+
+    if complexity in ("complex", "high"):
+        estimated_complexity = "high"
+    elif complexity in ("medium", "moderate"):
+        estimated_complexity = "medium"
+    elif complexity in ("simple", "low"):
+        estimated_complexity = "low"
+    elif estimated_hours is not None:
+        # Derive from hours if explicit complexity not set
+        if estimated_hours > 2:
+            estimated_complexity = "high"
+        elif estimated_hours > 0.5:
+            estimated_complexity = "medium"
+        else:
+            estimated_complexity = "low"
+    else:
+        # Default to medium if no hints
+        estimated_complexity = "medium"
+
+    # Check has_sibling_verify - look for verify tasks in same phase
+    parent_id = task_data.get("parent")
+    has_sibling_verify = False
+    if parent_id:
+        parent = hierarchy.get(parent_id, {})
+        children = parent.get("children", [])
+        for sibling_id in children:
+            if sibling_id != task_id:
+                sibling = hierarchy.get(sibling_id, {})
+                if sibling.get("type") == "verify":
+                    has_sibling_verify = True
+                    break
+
+    # Check may_require_user_input based on task_category
+    task_category = metadata.get("task_category", "").lower()
+    may_require_user_input = task_category in (
+        "decision",
+        "investigation",
+        "planning",
+        "design",
+    )
+
+    return {
+        "estimated_complexity": estimated_complexity,
+        "has_sibling_verify": has_sibling_verify,
+        "may_require_user_input": may_require_user_input,
+    }
+
+
 def prepare_task(
     spec_id: str,
     specs_dir: Path,
@@ -599,12 +691,16 @@ def prepare_task(
         "task_journal": get_task_journal_summary(spec_data, task_id),
     }
 
+    # Compute autonomous mode hints
+    auto_mode_hints = _compute_auto_mode_hints(spec_data, task_id, task_data)
+
     return asdict(success_response(
         task_id=task_id,
         task_data=task_data,
         dependencies=deps,
         spec_complete=False,
-        context=context
+        context=context,
+        auto_mode_hints=auto_mode_hints,
     ))
 
 
@@ -619,28 +715,35 @@ def _generate_task_id(parent_id: str, existing_children: List[str], task_type: s
     For verify IDs:
     - Same pattern but with "verify-" prefix
 
+    For research IDs:
+    - Same pattern but with "research-" prefix
+
     Args:
         parent_id: Parent node ID
         existing_children: List of existing child IDs
-        task_type: Type of task (task, subtask, verify)
+        task_type: Type of task (task, subtask, verify, research)
 
     Returns:
         New task ID string
     """
-    prefix = "verify" if task_type == "verify" else "task"
+    # Map task_type to ID prefix
+    prefix_map = {"verify": "verify", "research": "research"}
+    prefix = prefix_map.get(task_type, "task")
 
     # Extract numeric parts from parent
     if parent_id.startswith("phase-"):
         # Parent is phase-N, new task is task-N-1, task-N-2, etc.
         phase_num = parent_id.replace("phase-", "")
         base = f"{prefix}-{phase_num}"
-    elif parent_id.startswith("task-") or parent_id.startswith("verify-"):
-        # Parent is task-N-M or verify-N-M, new task appends next number
-        # Remove the prefix (task- or verify-) to get the numeric path
+    elif parent_id.startswith(("task-", "verify-", "research-")):
+        # Parent is task-N-M, verify-N-M, or research-N-M; new task appends next number
+        # Remove the prefix to get the numeric path
         if parent_id.startswith("task-"):
             base = f"{prefix}-{parent_id[5:]}"  # len("task-") = 5
-        else:
+        elif parent_id.startswith("verify-"):
             base = f"{prefix}-{parent_id[7:]}"  # len("verify-") = 7
+        else:  # research-
+            base = f"{prefix}-{parent_id[9:]}"  # len("research-") = 9
     else:
         # Unknown parent type, generate based on existing children count
         base = f"{prefix}-1"
@@ -696,11 +799,15 @@ def add_task(
     position: Optional[int] = None,
     file_path: Optional[str] = None,
     specs_dir: Optional[Path] = None,
+    # Research-specific parameters
+    research_type: Optional[str] = None,
+    blocking_mode: Optional[str] = None,
+    query: Optional[str] = None,
 ) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
     """
     Add a new task to a specification's hierarchy.
 
-    Creates a new task, subtask, or verify node under the specified parent.
+    Creates a new task, subtask, verify, or research node under the specified parent.
     Automatically generates the task ID and updates ancestor task counts.
 
     Args:
@@ -708,11 +815,14 @@ def add_task(
         parent_id: Parent node ID (phase or task).
         title: Task title.
         description: Optional task description.
-        task_type: Type of task (task, subtask, verify). Default: task.
+        task_type: Type of task (task, subtask, verify, research). Default: task.
         estimated_hours: Optional estimated hours.
         position: Optional position in parent's children list (0-based).
         file_path: Optional file path associated with this task.
         specs_dir: Path to specs directory (auto-detected if not provided).
+        research_type: For research nodes - workflow type (chat, consensus, etc).
+        blocking_mode: For research nodes - blocking behavior (none, soft, hard).
+        query: For research nodes - the research question/topic.
 
     Returns:
         Tuple of (result_dict, error_message).
@@ -723,6 +833,15 @@ def add_task(
     if task_type not in TASK_TYPES:
         return None, f"Invalid task_type '{task_type}'. Must be one of: {', '.join(TASK_TYPES)}"
 
+    # Validate research-specific parameters
+    if task_type == "research":
+        from foundry_mcp.core.validation import VALID_RESEARCH_TYPES, RESEARCH_BLOCKING_MODES
+
+        if research_type and research_type not in VALID_RESEARCH_TYPES:
+            return None, f"Invalid research_type '{research_type}'. Must be one of: {', '.join(sorted(VALID_RESEARCH_TYPES))}"
+        if blocking_mode and blocking_mode not in RESEARCH_BLOCKING_MODES:
+            return None, f"Invalid blocking_mode '{blocking_mode}'. Must be one of: {', '.join(sorted(RESEARCH_BLOCKING_MODES))}"
+
     # Validate title
     if not title or not title.strip():
         return None, "Title is required"
@@ -774,6 +893,15 @@ def add_task(
     if file_path:
         metadata["file_path"] = file_path.strip()
 
+    # Add research-specific metadata
+    if task_type == "research":
+        metadata["research_type"] = research_type or "consensus"  # Default to consensus
+        metadata["blocking_mode"] = blocking_mode or "soft"  # Default to soft blocking
+        if query:
+            metadata["query"] = query.strip()
+        metadata["research_history"] = []  # Empty history initially
+        metadata["findings"] = {}  # Empty findings initially
+
     # Create the task node
     task_node = {
         "type": task_type,
@@ -981,7 +1109,8 @@ def remove_task(
     # Validate task type (can only remove task, subtask, verify)
     task_type = task.get("type")
     if task_type not in ("task", "subtask", "verify"):
-        return None, f"Cannot remove node type '{task_type}'. Only task, subtask, or verify nodes can be removed."
+        hint = " Use `authoring action=\"phase-remove\"` instead." if task_type == "phase" else ""
+        return None, f"Cannot remove node type '{task_type}'. Only task, subtask, or verify nodes can be removed.{hint}"
 
     # Check for children
     children = task.get("children", [])

foundry_mcp/core/validation.py

@@ -110,7 +110,7 @@ class SpecStats:
 # Constants
 
 STATUS_FIELDS = {"pending", "in_progress", "completed", "blocked"}
-VALID_NODE_TYPES = {"spec", "phase", "group", "task", "subtask", "verify"}
+VALID_NODE_TYPES = {"spec", "phase", "group", "task", "subtask", "verify", "research"}
 VALID_STATUSES = {"pending", "in_progress", "completed", "blocked"}
 VALID_TASK_CATEGORIES = {
     "investigation",
@@ -127,6 +127,11 @@ VERIFICATION_TYPE_MAPPING = {
     "auto": "run-tests",
 }
 
+# Research node constants
+VALID_RESEARCH_TYPES = {"chat", "consensus", "thinkdeep", "ideate", "deep-research"}
+VALID_RESEARCH_RESULTS = {"completed", "inconclusive", "blocked", "cancelled"}
+RESEARCH_BLOCKING_MODES = {"none", "soft", "hard"}
+
 # Common field name typos/alternatives
 FIELD_NAME_SUGGESTIONS = {
     "category": "task_category",

foundry_mcp/server.py

@@ -17,7 +17,6 @@ from mcp.server.fastmcp import FastMCP
 
 from foundry_mcp.config import ServerConfig, get_config
 from foundry_mcp.core.observability import audit_log, get_observability_manager
-from foundry_mcp.core.feature_flags import get_flag_service
 from foundry_mcp.resources.specs import register_spec_resources
 from foundry_mcp.prompts.workflows import register_workflow_prompts
 from foundry_mcp.tools.unified import register_unified_tools
@@ -99,18 +98,6 @@ def _init_metrics_persistence(config: ServerConfig) -> None:
         logger.warning("Failed to initialize metrics persistence: %s", exc)
 
 
-def _apply_feature_flag_overrides_from_env() -> None:
-    """Apply comma-separated feature flag overrides from `FEATURE_FLAGS`."""
-
-    raw = os.environ.get("FEATURE_FLAGS")
-    if not raw:
-        return
-
-    flag_service = get_flag_service()
-    for name in [part.strip() for part in raw.split(",") if part.strip()]:
-        flag_service.set_override("anonymous", name, True)
-
-
 def create_server(config: Optional[ServerConfig] = None) -> FastMCP:
     """Create and configure the FastMCP server instance."""
 
@@ -119,7 +106,6 @@ def create_server(config: Optional[ServerConfig] = None) -> FastMCP:
 
     config.setup_logging()
 
-    _apply_feature_flag_overrides_from_env()
     _init_observability(config)
     _init_error_collection(config)
     _init_metrics_persistence(config)
@@ -137,48 +123,10 @@ def create_server(config: Optional[ServerConfig] = None) -> FastMCP:
     return mcp
 
 
-def _patch_fastmcp_json_serialization() -> None:
-    """Patch FastMCP to use minified JSON for tool responses.
-
-    FastMCP serializes dict responses with indent=2 by default.
-    This patch makes responses minified (no indentation) for smaller payloads.
-    """
-    try:
-        import pydantic_core
-        from itertools import chain
-        from mcp.types import TextContent, ContentBlock
-        from mcp.server.fastmcp.utilities import func_metadata
-        from mcp.server.fastmcp.utilities.types import Image, Audio
-
-        def _minified_convert_to_content(result):
-            if result is None:
-                return []
-            if isinstance(result, ContentBlock):
-                return [result]
-            if isinstance(result, Image):
-                return [result.to_image_content()]
-            if isinstance(result, Audio):
-                return [result.to_audio_content()]
-            if isinstance(result, (list, tuple)):
-                return list(chain.from_iterable(
-                    _minified_convert_to_content(item) for item in result
-                ))
-            if not isinstance(result, str):
-                # Minified: no indent
-                result = pydantic_core.to_json(result, fallback=str).decode()
-            return [TextContent(type="text", text=result)]
-
-        func_metadata._convert_to_content = _minified_convert_to_content
-        logger.debug("Patched FastMCP for minified JSON responses")
-    except Exception as e:
-        logger.warning("Failed to patch FastMCP JSON serialization: %s", e)
-
-
 def main() -> None:
     """Main entry point for the foundry-mcp server."""
 
     try:
-        _patch_fastmcp_json_serialization()
         config = get_config()
         server = create_server(config)