feat(cli/output): robust ANSI detection, plain fallback, and dynamic box width for blueprint output

.github/workflows/python-pytest.yml

@@ -36,3 +36,4 @@ jobs:
         run: pytest
         env:
           PYTHONPATH: ${{ github.workspace }}/src
+          DJANGO_ALLOW_ASYNC_UNSAFE: "true"

.github/workflows/ux_compliance.yml

@@ -0,0 +1,32 @@
+name: Blueprint UX Compliance
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  ux-compliance:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+      - name: Install uv
+        run: pip install uv
+      - name: Install dependencies
+        run: uv pip install -r requirements.txt
+      - name: Install ruff
+        run: pip install ruff
+      - name: Lint with ruff
+        run: ruff check .
+      - name: Run blueprint tests
+        run: uv run pytest -v tests/blueprints
+      - name: Run coverage
+        run: uv run pytest --cov=src --cov-report=term-missing tests/blueprints
+      - name: Run UX compliance utility
+        run: python scripts/check_ux_compliance.py

.gitignore

@@ -21,6 +21,7 @@ sdist/
 var/
 wheels/
 share/python-wheels/
+db.sqlite3-*
 *.egg-info/
 .installed.cfg
 *.egg
@@ -191,3 +192,8 @@ openapi.yaml
 *.db
 *.db-shm
 logs/*
+
+openai-agents-python/*
+docker-compose.override.yml
+
+bin/*

.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: local
+    hooks:
+      - id: lint-blueprints
+        name: Lint Blueprints for Spinner/Result UX
+        entry: python scripts/lint_blueprints.py
+        language: system
+        files: ^src/swarm/blueprints/blueprint_.*\.py$

.windsurfrules

@@ -0,0 +1,5 @@
+`uv run pytest` to test.
+`uv add` and `uv sync --all-extras` to add software.
+git commit messages are to be conventional.
+functional swarm-cli and swarm-api cmds are the end game.
+blueprints demonstrate the framework capabilities.

Dockerfile

@@ -16,29 +16,24 @@ RUN apt-get update && apt-get install -y \
 
 WORKDIR /app
 
-# Copy all project files into the container
+# Copy all project files first (consider .dockerignore for efficiency)
 COPY . .
 
-# Upgrade pip to the latest version for compatibility
+# Upgrade pip
 RUN pip install --upgrade pip setuptools wheel
 
-# Install BLIS with generic architecture support
-ENV BLIS_ARCH="generic"
-#RUN pip install --no-cache-dir --no-binary=blis blis==1.2.0
-# RUN pip install --no-cache-dir --no-dependencies nemoguardrails
+# Install BLIS (if still needed, uncomment)
+# ENV BLIS_ARCH="generic"
+# RUN pip install --no-cache-dir --no-binary=blis blis==1.2.0
 
-# Install the project along with its dependencies using Hatchling (as set in pyproject.toml)
+# Install the project
 RUN pip install .
 
 # Expose the specified port
 EXPOSE ${PORT}
 
-# Runtime logic:
-# - If SWAPFILE_PATH is defined, configure swap
-# - Set default SQLite DB path if not provided
-# - If FACTORY_RESET_DATABASE is True, delete the database file
-# - Check if database exists and has tables; apply migrations accordingly
-# - Start the Django server
+# --- Default Command ---
+# This runs if no entrypoint overrides it. Includes DB setup.
 CMD if [ -n "$SWAPFILE_PATH" ]; then \
       mkdir -p "$(dirname "$SWAPFILE_PATH")" && \
       fallocate -l 768M "$SWAPFILE_PATH" && \
@@ -65,4 +60,6 @@ CMD if [ -n "$SWAPFILE_PATH" ]; then \
       echo "No database found; creating and applying migrations" && \
       python manage.py migrate; \
     fi && \
-    python manage.py runserver 0.0.0.0:$PORT
+    echo "--- Starting Django Server (Default CMD) ---" && \
+    python manage.py runserver 0.0.0.0:$PORT
+

HANDOFF_NOTES.md

@@ -0,0 +1,70 @@
+# Session Handoff Report: Post-Refactor Cleanup & Next Steps
+
+**Date:** 2025-03-29
+
+**Current Status:**
+
+*   **Core Refactoring Complete:** All major blueprints (`burnt_noodles`, `rue_code`, `nebula_shellz`, `digitalbutlers`, `dilbot_universe`, `gaggle`, `family_ties`, `mission_improbable`, `whiskeytango_foxtrot`, `divine_ops`, `omniplex`, `unapologetic_poets`, `chatbot`, `echocraft`, `suggestion`, `monkai_magic`) have been refactored to inherit from `BlueprintBase`.
+*   **Design Patterns:**
+    *   Agent-as-tool delegation is the primary pattern for coordination.
+    *   Direct `@function_tool` usage is employed for local CLI wrappers (`burnt_noodles`, `monkai_magic`).
+    *   MCP servers provide capabilities to specialist agents (`digitalbutlers`, `divine_ops`, `wtf`, `mission_improbable`, `omniplex`, `unapologetic_poets`).
+    *   Dynamic configuration via SQLite demonstrated (`dilbot_universe`, `mission_improbable`, `unapologetic_poets`).
+    *   Structured output via `output_type` demonstrated (`suggestion`).
+*   **BlueprintBase Enhancements:**
+    *   Added MCP server `description` field support in config (`get_mcp_server_description` helper).
+    *   Added check for missing `env_vars` specified in blueprint metadata.
+    *   Corrected default markdown logic for CLI mode (`use_markdown` defaults to True).
+    *   Added (then reverted due to errors) MCP startup timeout logic. **The timeout logic caused `TypeError: '_GeneratorContextManager' object does not support the asynchronous context manager protocol` and was removed.** This needs further investigation, possibly using `asyncio.wait_for` instead of `anyio.fail_after` around the `stack.enter_async_context` call.
+*   **Configuration:** `swarm_config.json` updated with new `git` and `google-cse` servers and example `description` / `startup_timeout` fields. Syntax error fixed.
+*   **Testing:** Placeholder test files created for all refactored blueprints. Most tests are currently skipped (`reason="...not yet implemented"`). Existing config tests pass.
+*   - Renamed unapologetic_press blueprint to unapologetic_poets (directory, class, and all references).
+    - File is now blueprint_unapologetic_poets.py.
+    - All code, test, and documentation references updated accordingly.
+*   - All DivineOpsBlueprint and divine_code functionality has been merged into ZeusBlueprint. All references, tests, and documentation should now use ZeusBlueprint exclusively. Any mention of DivineOps or divine_code is for historical context only.
+
+**Immediate Issues:**
+
+*   **MCP Startup Timeout:** The `anyio.fail_after` implementation caused TypeErrors. The timeout logic in `_start_mcp_server_instance` has been **reverted**. MCP server startup failures might still hang indefinitely. **Investigate alternative timeout implementations (e.g., `asyncio.wait_for`)**.
+*   **MCP Failures:** Some MCP servers failed to start in the last run (`slack`, `mondayDotCom`, `basic-memory`, `mcp-npx-fetch`), triggering the blueprint failure logic correctly. Root cause unknown (could be network, dependencies, config, etc.).
+
+**Next Tactical Steps:**
+
+1.  **Fix MCP Startup Timeout:** Re-implement a working timeout mechanism for `_start_mcp_server_instance`. `asyncio.wait_for(stack.enter_async_context(server_instance), timeout=startup_timeout)` might be a better approach. Test thoroughly.
+2.  **Refactor Remaining Blueprints:**
+    *   `chucks_angels` (Needs UVX/NeMo investigation or simplification).
+    *   `django_chat` (Decide whether to keep Django dependency or refactor).
+    *   `flock` (Implement based on original intent).
+    *   `messenger` (Implement based on original intent).
+3.  **Implement Guardrails:**
+    *   Research `openai-agents`'s intended guardrail mechanism (likely via config).
+    *   **Target Blueprints:** `MonkaiMagic`, `WhiskeyTangoFoxtrot` (due to shell/fs/web access).
+    *   Define basic guardrail configs (e.g., prevent dangerous shell commands, filter topics).
+    *   Modify `create_starting_agent` in target blueprints to potentially load and pass guardrail configs to relevant `Agent` instances.
+4.  **Enhance Agent Synergy / Dynamic Prompts:**
+    *   **Omniplex:** Modify `OmniplexCoordinator` instructions to use MCP descriptions (fetched via `self.get_mcp_server_description`) to explain available tools. Implement logic to choose *one* search provider if multiple (brave, google, ddg) are available and started.
+    *   **Other Coordinators (e.g., Zeus, Valory):** Update instructions to dynamically include descriptions of the agent tools and the MCP tools *their* delegate agents have access to, using `self.get_mcp_server_description`.
+5.  **Parallel Tool Calls Demo:**
+    *   Design and implement a simple blueprint where the coordinator needs independent info from two different tools/agents simultaneously (e.g., read local file + web search).
+    *   Verify that the `Runner` executes these concurrently if the LLM returns multiple `tool_calls`.
+6.  **Update Blueprints README:** Regenerate or manually edit `blueprints/README.md` table to accurately reflect the status, features, and MCP usage of all blueprints post-refactoring. Ensure descriptions match the updated code.
+7.  **Implement Skipped Tests:** Gradually unskip and implement tests in `tests/blueprints/`, focusing on:
+    *   Agent creation and tool assignment.
+    *   Basic delegation flows (mocking `Runner.run` or agent `process` methods).
+    *   Direct testing of `@function_tool` functions.
+
+**Strategic Considerations:**
+
+*   **Guardrails Integration:** How deeply should guardrails be integrated? Per-agent? Global? Config-driven?
+*   **Error Handling:** Standardize error reporting from tools and MCP interactions back to the coordinator.
+*   **Testing Strategy:** Develop robust strategies for mocking MCP interactions and complex multi-agent flows.
+*   **UI Elements:** Revisit custom spinners/prompts if essential, potentially via external wrappers or modifications to `BlueprintBase.main`.
+
+**Tips & Hints:**
+
+*   **Timeout:** Focus on `asyncio.wait_for` around `stack.enter_async_context(server_instance)` in `_start_mcp_server_instance`.
+*   **Dynamic Prompts:** Use f-strings and loops within `create_starting_agent` to build instructions dynamically using `self.get_mcp_server_description(server_name)` for available servers/tools.
+*   **Parallel Calls:** Requires an LLM that supports generating multiple `tool_calls` and an agent logic that makes independent requests suitable for parallel execution.
+*   **Testing:** Start with unit tests for tools and basic agent creation tests (mocking dependencies). Integration tests require more effort.
+
+Good luck!

ISSUES.md

@@ -0,0 +1,28 @@
+# Open Swarm: Known Issues and TODOs
+
+_Last updated: 2025-04-21_
+
+## Skipped/Flaky/Soft Tests
+- `tests/test_blueprint_loading.py`: All tests skipped due to dynamic INSTALLED_APPS complexity. **Action:** Refactor to enable test coverage or document why this is not possible.
+- `tests/blueprints/test_chatbot.py`: Skips if dependencies are missing. **Action:** Ensure dependencies are installed or mock them for testing.
+- `tests/blueprints/test_codey.py`: Skips if CLI utility not found. **Action:** Ensure codey blueprint is enabled or provide a mock.
+
+## Error Handling and Logging
+- Many tools and modules (audit_viz.py, blueprint_qa.py, message serialization, etc.) log errors/warnings but do not raise or fail. **Action:** Patch to raise exceptions or exit nonzero on critical errors; ensure user-facing errors are actionable.
+
+## TODO/FIXME/DEPRECATED/Warning Comments
+- Numerous TODO, FIXME, and DEPRECATED comments found in core modules (e.g., ChatMessage, tool calls, etc.). **Action:** Systematically address or triage; if not immediately fixable, keep tracked here.
+
+## Deprecated Fields
+- `ChatMessage.function_call` is marked as deprecated but still present in code. **Action:** Remove or fully document deprecation timeline.
+
+## Logging and Error Surfacing
+- Some flows only log errors and do not fail tests or CLI. **Action:** Harden error handling across all CLI, API, and blueprint flows.
+
+## General Recommendations
+- Sync this file with GitHub Issues for better user visibility and tracking.
+- Update documentation to reflect known issues and troubleshooting steps.
+
+---
+
+_This file is auto-generated and should be updated as issues are fixed or discovered._

Makefile

@@ -0,0 +1,9 @@
+# Makefile for Open Swarm: developer/CI helpers
+
+.PHONY: pretest-clean test
+
+pretest-clean:
+	bash scripts/pretest_cleanup.sh
+
+test: pretest-clean
+	uv run pytest