feat: implement autonomous swarm orchestration pipeline and agent hiring flows

.gitignore

@@ -86,5 +86,10 @@ node_modules/
 .worktrees/
 .codegraph/
 
-w o r k t r e e s /  
- 
+# Playwright and workspaces
+.playwright-mcp/
\ No newline at end of file
+backend/.playwright-mcp/
+workspaces/
+backend/workspaces/
+*.png
+*.tsbuildinfo
\ No newline at end of file

backend/.env.example

@@ -2,7 +2,9 @@
 # Copy this file to .env and adjust values
 
 # Core
+# Database (SQLite for dev, PostgreSQL for production)
 DATABASE_URL=sqlite+aiosqlite:///./paperclip.db
+# DATABASE_URL=postgresql+asyncpg://paperclip:paperclip_secret@localhost:5433/paperclip
 SECRET_KEY=dev-secret-key-change-in-production
 HOST=127.0.0.1
 PORT=3100
@@ -22,3 +24,10 @@ OPENAI_API_KEY=
 
 # Logging
 LOG_LEVEL=INFO
+
+# Redis (required for Celery task queue)
+REDIS_URL=redis://localhost:6379/0
+
+# Celery (agent task queue — tasks survive server restarts)
+CELERY_BROKER_URL=redis://localhost:6379/1
+CELERY_RESULT_BACKEND=redis://localhost:6379/2

backend/agent/tools/delegate_tool.py

@@ -650,6 +650,7 @@ def _resolve_workspace_hint(parent_agent) -> Optional[str]:
     guessing `/workspace/...` for local repo tasks.
     """
     candidates = [
+        os.getenv("AGENT_WORKSPACE"),
         os.getenv("TERMINAL_CWD"),
         getattr(
             getattr(parent_agent, "_subdirectory_hints", None), "working_dir", None
@@ -1486,6 +1487,17 @@ def _run_single_child(
             list(file_state.known_reads(parent_task_id)) if parent_task_id else []
         )
 
+        # Register task overrides for the child so that its terminal execution starts in:
+        # parent_workspace/subagents/child_task_id/
+        parent_workspace = os.environ.get("AGENT_WORKSPACE")
+        if parent_workspace:
+            subagent_dir = os.path.abspath(os.path.join(parent_workspace, "subagents", child_task_id))
+            os.makedirs(subagent_dir, exist_ok=True)
+            from tools.terminal_tool import register_task_env_overrides
+            register_task_env_overrides(child_task_id, {
+                "cwd": subagent_dir
+            })
+
         # Run child with a hard timeout to prevent indefinite blocking
         # when the child's API call or tool-level HTTP request hangs.
         child_timeout = _get_child_timeout()
@@ -1854,6 +1866,10 @@ def _run_single_child(
         if _subagent_id:
             _unregister_subagent(_subagent_id)
 
+        # Clear terminal env overrides
+        from tools.terminal_tool import clear_task_env_overrides
+        clear_task_env_overrides(child_task_id)
+
         if child_pool is not None and leased_cred_id is not None:
             try:
                 child_pool.release_lease(leased_cred_id)

backend/agent/tools/mcp_client.py

@@ -32,13 +32,12 @@ class MCPSubprocessClient:
         logger.info(f"🚀 Starting MCP server '{self.name}': {cmd} {' '.join(self.args)}")
         
         # Start subprocess using standard library subprocess.Popen (SelectorEventLoop compatible)
-        is_windows = sys.platform == "win32"
         self.process = subprocess.Popen(
             [cmd] + self.args,
             stdin=subprocess.PIPE,
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
-            shell=is_windows,
+            shell=False,
             bufsize=0,
         )
         

backend/api/main_router.py

@@ -63,6 +63,8 @@ from .routes.environment_probe import router as environment_probe_router
 from .routes.document_revisions import router as document_revisions_router
 from .routes.marketplace import router as marketplace_router
 from .routes.cubesandbox import router as cubesandbox_router
+from .routes.pipelines import router as pipelines_router
+from .routes.agent_hires import router as agent_hires_router
 
 main_router = APIRouter()
 
@@ -141,6 +143,8 @@ api_sub_router.include_router(environment_probe_router)
 api_sub_router.include_router(document_revisions_router)
 api_sub_router.include_router(marketplace_router)
 api_sub_router.include_router(cubesandbox_router)
+api_sub_router.include_router(pipelines_router)
+api_sub_router.include_router(agent_hires_router)
 
 # Register /api sub-router to the main router
 main_router.include_router(api_sub_router)

backend/api/routes/agent_hires.py

+"""
+Agent Hires route — Handles manual agent creation and hiring.
+"""
+
+from typing import Optional, List, Dict, Any
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field, ConfigDict
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+import uuid
+from datetime import datetime
+
+from database import get_db_session
+from middleware.auth import get_current_user
+from schemas.auth import AuthUserResponse
+from models import Agent, CompanyMembership
+from services.activity_logger import log_activity
+
+router = APIRouter(prefix="/agent-hires", tags=["agents"])
+
+
+class AgentHireRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=255)
+    role: str = Field(..., min_length=1, max_length=255)
+    title: Optional[str] = None
+    reports_to: Optional[str] = Field(None, alias="reportsTo")
+    desired_skills: Optional[List[str]] = Field(None, alias="desiredSkills")
+    adapter_type: str = Field(..., alias="adapterType")
+    default_environment_id: Optional[str] = Field(None, alias="defaultEnvironmentId")
+    adapter_config: Dict[str, Any] = Field(default_factory=dict, alias="adapterConfig")
+    runtime_config: Dict[str, Any] = Field(default_factory=dict, alias="runtimeConfig")
+    budget_monthly_cents: int = Field(0, alias="budgetMonthlyCents")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+@router.post("", status_code=status.HTTP_201_CREATED)
+async def hire_agent(
+    payload: AgentHireRequest,
+    company_id: str = Query(..., description="Company ID"),
+    db: AsyncSession = Depends(get_db_session),
+    current_user: AuthUserResponse = Depends(get_current_user)
+):
+    """Hire / create a new agent in a company."""
+    # Verify company access
+    result = await db.execute(
+        select(CompanyMembership).where(
+            CompanyMembership.company_id == company_id,
+            CompanyMembership.principal_type == "user",
+            CompanyMembership.principal_id == current_user.id,
+            CompanyMembership.status == "active"
+        )
+    )
+    membership = result.scalar_one_or_none()
+
+    if not membership:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="No access to company")
+
+    agent_id = uuid.uuid4().hex
+    db_agent = Agent(
+        id=agent_id,
+        company_id=company_id,
+        name=payload.name,
+        role=payload.role,
+        title=payload.title,
+        status="active",
+        reports_to=payload.reports_to,
+        capabilities=",".join(payload.desired_skills) if payload.desired_skills else None,
+        adapter_type=payload.adapter_type,
+        adapter_config=payload.adapter_config,
+        runtime_config=payload.runtime_config,
+        default_environment_id=payload.default_environment_id,
+        budget_monthly_cents=payload.budget_monthly_cents,
+        permissions={},
+        created_at=datetime.utcnow(),
+        updated_at=datetime.utcnow()
+    )
+    db.add(db_agent)
+    await db.flush()
+    await db.refresh(db_agent)
+
+    # Log activity
+    await log_activity(
+        db=db,
+        company_id=company_id,
+        actor_type="user",
+        actor_id=current_user.id,
+        action="agent.created",
+        resource_type="agent",
+        resource_id=db_agent.id,
+        changes={"name": payload.name, "adapter_type": payload.adapter_type, "hired": True}
+    )
+
+    await db.commit()
+
+    # Convert agent model to dict/json matching the required frontend schema
+    return {
+        "agent": {
+            "id": db_agent.id,
+            "companyId": db_agent.company_id,
+            "name": db_agent.name,
+            "role": db_agent.role,
+            "title": db_agent.title,
+            "icon": db_agent.icon or "",
+            "status": db_agent.status,
+            "reportsTo": db_agent.reports_to,
+            "capabilities": db_agent.capabilities.split(",") if db_agent.capabilities else [],
+            "adapterType": db_agent.adapter_type,
+            "adapterConfig": db_agent.adapter_config,
+            "runtimeConfig": db_agent.runtime_config,
+            "budgetMonthlyCents": db_agent.budget_monthly_cents,
+            "createdAt": db_agent.created_at.isoformat(),
+            "updatedAt": db_agent.updated_at.isoformat()
+        },
+        "approval": None
+    }

backend/api/routes/agents.py

@@ -19,6 +19,7 @@ from models import Agent, CompanyMembership, HeartbeatRun
 from services.activity_logger import log_activity
 from services.workspace_manager import WorkspaceManager
 from services.agent_log_writer import AgentLogWriter
+from services.iteration_budget import request_interrupt
 
 router = APIRouter(prefix="/agents", tags=["agents"])
 
@@ -209,7 +210,7 @@ async def run_agent_in_background(
             shared_dir = Path("workspaces") / company_id / "shared"
             shared_dir.mkdir(parents=True, exist_ok=True)
             
-            if agent_id == "agent_pm":
+            if agent_id.startswith("agent_pm"):
                 await log_writer._write_log("info", "PM Agent waken up. Goal: 'Build a premium dark-mode landing page for clothing brand.'")
                 await asyncio.sleep(1.5)
                 await log_writer._write_log("info", "Analyzing clothing brand identity & design tokens...")
@@ -231,7 +232,7 @@ async def run_agent_in_background(
                 await log_writer._write_log("info", "Successfully created project spec.md in workspaces")
                 await asyncio.sleep(1.0)
                 
-            elif agent_id == "agent_coder":
+            elif agent_id.startswith("agent_coder"):
                 await log_writer._write_log("info", "Coder Agent waken up. Goal: Implement the spec.md layout.")
                 await asyncio.sleep(1.5)
                 await log_writer._write_log("info", "Reading spec.md from shared directory...")
@@ -264,7 +265,7 @@ async def run_agent_in_background(
                 await log_writer._write_log("info", "Successfully generated landing page assets.")
                 await asyncio.sleep(1.0)
                 
-            elif agent_id == "agent_qa":
+            elif agent_id.startswith("agent_qa"):
                 await log_writer._write_log("info", "QA Agent waken up. Task: Verify landing page layout and assets.")
                 await asyncio.sleep(1.5)
                 await log_writer._write_log("info", "Launching Playwright headless browser...")
@@ -341,8 +342,7 @@ async def run_agent_in_background(
         ai_agent = AIAgent(
             model_name=model_name,
             company_id=company_id,
-            tool_start_callback=log_writer.on_tool_start,
-            tool_complete_callback=log_writer.on_tool_complete,
+            tool_progress_callback=log_writer.on_subagent_progress,
             step_callback=log_writer.on_step,
             status_callback=log_writer.on_status,
             api_key=settings.openai_api_key,
@@ -529,3 +529,44 @@ async def invoke_agent(
     )
 
 
+@router.post("/{agent_id}/interrupt")
+async def interrupt_agent(
+    agent_id: str,
+    company_id: str = Query(..., description="Company ID"),
+    run_id: str = Query(..., description="Run ID to interrupt"),
+    db: AsyncSession = Depends(get_db_session),
+    current_user: AuthUserResponse = Depends(get_current_user)
+):
+    """Interrupt a running agent execution."""
+    # Verify company access
+    result = await db.execute(
+        select(CompanyMembership).where(
+            CompanyMembership.company_id == company_id,
+            CompanyMembership.principal_type == "user",
+            CompanyMembership.principal_id == current_user.id,
+            CompanyMembership.status == "active"
+        )
+    )
+    membership = result.scalar_one_or_none()
+
+    if not membership:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="No access to company")
+
+    found = request_interrupt(run_id)
+    if not found:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Run not found or already completed")
+
+    # Log the interrupt
+    await log_activity(
+        db=db,
+        company_id=company_id,
+        actor_type="user",
+        actor_id=current_user.id,
+        action="agent.interrupted",
+        resource_type="agent",
+        resource_id=agent_id,
+        changes={"run_id": run_id}
+    )
+    await db.commit()
+
+    return {"status": "interrupted", "run_id": run_id, "agent_id": agent_id}

backend/api/routes/pipelines.py

+"""
+Pipeline routes — Orchestrate full A→Z autonomous project builds.
+
+One endpoint to rule them all:
+  POST /api/pipelines/run → Deploys template + Runs PM → Coder → QA → Returns CEO report
+"""
+
+import logging
+from typing import Optional, List
+from fastapi import APIRouter, Depends, HTTPException, Query, BackgroundTasks
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+
+from database import get_db_session
+from middleware.auth import get_current_user
+from schemas.auth import AuthUserResponse
+from models import Agent, CompanyMembership
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/pipelines", tags=["pipelines"])
+
+# In-memory pipeline status store (swap for Redis in production)
+_pipeline_results: dict[str, dict] = {}
+
+
+class PipelineRunRequest(BaseModel):
+    company_id: str
+    project_brief: str
+    template_id: Optional[str] = None  # Optional: deploy template first
+    agent_ids: Optional[List[str]] = None  # Optional: specific agents to use
+
+
+class PipelineStatusResponse(BaseModel):
+    pipeline_id: str
+    status: str
+
+
+@router.post("/run")
+async def run_pipeline(
+    payload: PipelineRunRequest,
+    background_tasks: BackgroundTasks,
+    db: AsyncSession = Depends(get_db_session),
+    current_user: AuthUserResponse = Depends(get_current_user),
+):
+    """
+    🚀 Run full A→Z pipeline.
+    
+    1. (Optional) Deploy a marketplace template to create agents
+    2. Execute agents sequentially: PM → Coder → QA
+    3. Each agent reads previous agent's output from shared workspace
+    4. Returns pipeline_id for status tracking via WebSocket or polling
+    
+    WebSocket events pushed during execution:
+    - pipeline.started
+    - pipeline.step (per agent)
+    - pipeline.completed
+    """
+    # Verify company access
+    result = await db.execute(
+        select(CompanyMembership).where(
+            CompanyMembership.company_id == payload.company_id,
+            CompanyMembership.principal_type == "user",
+            CompanyMembership.principal_id == current_user.id,
+            CompanyMembership.status == "active",
+        )
+    )
+    if not result.scalar_one_or_none():
+        raise HTTPException(status_code=403, detail="No access to company")
+
+    # Optional: deploy template first
+    if payload.template_id:
+        from api.routes.marketplace import _load_templates
+        templates = _load_templates()
+        template = next((t for t in templates if t["id"] == payload.template_id), None)
+        if not template:
+            raise HTTPException(status_code=404, detail="Template not found")
+
+        import uuid
+        for agent_def in template["agents"]:
+            agent_id = f"{agent_def['agentId']}_{uuid.uuid4().hex[:8]}"
+            agent = Agent(
+                id=agent_id,
+                company_id=payload.company_id,
+                name=agent_def["name"],
+                role=agent_def["role"],
+                title=agent_def["title"],
+                icon=agent_def.get("icon", ""),
+                capabilities=",".join(agent_def.get("skills", [])),
+                adapter_type="openai",
+                adapter_config={"model": "gpt-4o-mini"},
+                status="active",
+            )
+            db.add(agent)
+        await db.commit()
+
+    # Verify we have agents
+    result = await db.execute(
+        select(Agent).where(
+            Agent.company_id == payload.company_id,
+            Agent.status == "active",
+        )
+    )
+    agents = result.scalars().all()
+    if not agents:
+        raise HTTPException(status_code=400, detail="No active agents. Deploy a template first.")
+
+    # Create orchestrator and run in background
+    from services.project_orchestrator import ProjectOrchestrator
+
+    orchestrator = ProjectOrchestrator(
+        company_id=payload.company_id,
+        project_brief=payload.project_brief,
+        agent_ids=payload.agent_ids,
+    )
+
+    pipeline_id = orchestrator.pipeline_id
+    _pipeline_results[pipeline_id] = {"status": "running", "pipeline_id": pipeline_id}
+
+    async def _execute_pipeline():
+        try:
+            result = await orchestrator.run()
+            _pipeline_results[pipeline_id] = result
+        except Exception as e:
+            logger.error(f"Pipeline {pipeline_id} crashed: {e}", exc_info=True)
+            _pipeline_results[pipeline_id] = {
+                "status": "failed",
+                "pipeline_id": pipeline_id,
+                "error": str(e),
+            }
+
+    background_tasks.add_task(_execute_pipeline)
+
+    return {
+        "pipeline_id": pipeline_id,
+        "status": "running",
+        "message": "Pipeline started. Connect to WebSocket for real-time updates.",
+        "websocket_url": f"/api/events/ws?company_id={payload.company_id}",
+        "poll_url": f"/api/pipelines/{pipeline_id}/status",
+    }
+
+
+@router.get("/{pipeline_id}/status")
+async def get_pipeline_status(
+    pipeline_id: str,
+    current_user: AuthUserResponse = Depends(get_current_user),
+):
+    """Get current pipeline status and result."""
+    result = _pipeline_results.get(pipeline_id)
+    if not result:
+        raise HTTPException(status_code=404, detail="Pipeline not found")
+    return result

backend/api/routes/run_logs.py

@@ -58,7 +58,17 @@ async def list_run_logs(
         return {"total": 0, "offset": pagination.offset, "limit": pagination.limit, "items": []}
 
     total = rows[0].total
-    logs = [ExecutionRunLogResponse.model_validate(row._mapping["ExecutionRunLog"]) for row in rows]
+    logs = [
+        ExecutionRunLogResponse.model_validate({
+            "id": log.id,
+            "run_id": log.run_id,
+            "log_type": log.log_type,
+            "message": log.message,
+            "metadata": log.log_metadata,
+            "created_at": log.created_at,
+            "updated_at": log.updated_at
+        }) for log in [row._mapping["ExecutionRunLog"] for row in rows]
+    ]
 
     return {
         "total": total,
@@ -95,7 +105,15 @@ async def get_run_log(
     if not run:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Run not found")
 
-    return log
+    return {
+        "id": log.id,
+        "run_id": log.run_id,
+        "log_type": log.log_type,
+        "message": log.message,
+        "metadata": log.log_metadata,
+        "created_at": log.created_at,
+        "updated_at": log.updated_at
+    }
 
 
 @router.post("", response_model=ExecutionRunLogResponse, status_code=status.HTTP_201_CREATED)
@@ -280,7 +298,15 @@ async def get_run_detail(
         "created_at": run.created_at,
         "updated_at": run.updated_at,
         "logs": [
-            ExecutionRunLogResponse.model_validate(log) for log in logs
+            ExecutionRunLogResponse.model_validate({
+                "id": log.id,
+                "run_id": log.run_id,
+                "log_type": log.log_type,
+                "message": log.message,
+                "metadata": log.log_metadata,
+                "created_at": log.created_at,
+                "updated_at": log.updated_at
+            }) for log in logs
         ],
     }
 
@@ -345,6 +371,10 @@ async def stream_run_logs(
                         "metadata": log.log_metadata,
                         "created_at": log.created_at.isoformat(),
                     }
+                    if log.log_metadata and isinstance(log.log_metadata, dict):
+                        for k in ["subagent_id", "depth", "goal", "agent_name"]:
+                            if k in log.log_metadata:
+                                data[k] = log.log_metadata[k]
                     yield f"data: {json.dumps(data, default=str)}\n\n"
                     last_seen_id = log.id
 
@@ -756,3 +786,149 @@ async def get_execution_status(
         "totalAgents": total_agents,
     }
 
+
+@runs_router.get("/{run_id}/tree")
+async def get_run_tree(
+    company_id: str,
+    run_id: str,
+    scope: CompanyScope = Depends(require_company_scope),
+    db: AsyncSession = Depends(get_db_session),
+):
+    """
+    Returns the hierarchical execution tree of the swarm under this run.
+    """
+    result = await db.execute(
+        select(HeartbeatRun).where(
+            HeartbeatRun.id == run_id,
+            HeartbeatRun.company_id == company_id,
+        )
+    )
+    run = result.scalar_one_or_none()
+    if not run:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Run not found")
+
+    logs_result = await db.execute(
+        select(ExecutionRunLog)
+        .where(ExecutionRunLog.run_id == run_id)
+        .order_by(ExecutionRunLog.created_at.asc())
+    )
+    logs = logs_result.scalars().all()
+
+    subagents_dict = {}
+    
+    for log in logs:
+        meta = log.log_metadata
+        if not meta or not isinstance(meta, dict) or "subagent_id" not in meta:
+            continue
+            
+        sid = meta["subagent_id"]
+        pid = meta.get("parent_subagent_id")
+        goal = meta.get("goal")
+        name = meta.get("agent_name", "Worker Agent")
+        status = meta.get("status", "running")
+        
+        if sid not in subagents_dict:
+            subagents_dict[sid] = {
+                "subagent_id": sid,
+                "parent_id": pid,
+                "agent_name": name,
+                "goal": goal,
+                "status": status,
+                "tool_count": 0,
+                "started_at": log.created_at.isoformat(),
+                "subagents": []
+            }
+            
+        node = subagents_dict[sid]
+        if status != "running":
+            node["status"] = status
+            
+        is_tool = meta.get("event") == "tool_start" or "Tool started:" in (log.message or "")
+        if is_tool:
+            node["tool_count"] += 1
+
+    roots = []
+    for sid, node in subagents_dict.items():
+        pid = node["parent_id"]
+        if pid and pid in subagents_dict:
+            subagents_dict[pid]["subagents"].append(node)
+        else:
+            roots.append(node)
+
+    return {
+        "run_id": run.id,
+        "status": run.status,
+        "agent_id": run.agent_id,
+        "agent_name": "CEO Director" if run.agent_id == "agent_pm" else "Director Agent",
+        "started_at": run.started_at.isoformat() if run.started_at else None,
+        "subagents": roots
+    }
+
+
+@runs_router.get("/{run_id}/logs")
+async def get_run_logs_filtered(
+    company_id: str,
+    run_id: str,
+    subagent_id: Optional[str] = Query(None, description="Filter by subagent ID"),
+    max_depth: Optional[int] = Query(None, description="Max depth of subagents to return"),
+    scope: CompanyScope = Depends(require_company_scope),
+    db: AsyncSession = Depends(get_db_session),
+):
+    """
+    Returns logs for a run, with optional filtering for subagents and depth.
+    """
+    if not isinstance(subagent_id, str):
+        subagent_id = None
+    if not isinstance(max_depth, int):
+        max_depth = None
+
+    run_result = await db.execute(
+        select(HeartbeatRun).where(
+            HeartbeatRun.id == run_id,
+            HeartbeatRun.company_id == company_id,
+        )
+    )
+    run = run_result.scalar_one_or_none()
+    if not run:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Run not found")
+
+    stmt = select(ExecutionRunLog).where(ExecutionRunLog.run_id == run_id).order_by(ExecutionRunLog.created_at.asc())
+    result = await db.execute(stmt)
+    logs = result.scalars().all()
+    
+    filtered_logs = []
+    for log in logs:
+        meta = log.log_metadata
+        if subagent_id:
+            if subagent_id.lower() in {"parent", "main"}:
+                if meta and isinstance(meta, dict) and "subagent_id" in meta:
+                    continue
+            else:
+                if not meta or not isinstance(meta, dict) or meta.get("subagent_id") != subagent_id:
+                    continue
+        if max_depth is not None:
+            depth = 0
+            if meta and isinstance(meta, dict) and "depth" in meta:
+                try:
+                    depth = int(meta["depth"])
+                except (ValueError, TypeError):
+                    pass
+            if depth > max_depth:
+                continue
+        filtered_logs.append(log)
+                
+    result_logs = []
+    for log in filtered_logs:
+        log_dict = {
+            "id": log.id,
+            "run_id": log.run_id,
+            "log_type": log.log_type,
+            "message": log.message,
+            "metadata": log.log_metadata,
+            "created_at": log.created_at,
+            "updated_at": log.updated_at
+        }
+        result_logs.append(ExecutionRunLogResponse.model_validate(log_dict))
+        
+    return result_logs
+

backend/celery_app.py

+"""
+Celery application for background task processing.
+Replaces FastAPI BackgroundTasks for reliability — tasks survive server restarts.
+"""
+
+import os
+from celery import Celery
+from dotenv import load_dotenv
+
+load_dotenv()
+
+BROKER_URL = os.getenv("CELERY_BROKER_URL", "redis://localhost:6379/1")
+RESULT_BACKEND = os.getenv("CELERY_RESULT_BACKEND", "redis://localhost:6379/2")
+
+celery_app = Celery(
+    "ai_company",
+    broker=BROKER_URL,
+    backend=RESULT_BACKEND,
+)
+
+celery_app.conf.update(
+    task_serializer="json",
+    accept_content=["json"],
+    result_serializer="json",
+    timezone="UTC",
+    enable_utc=True,
+    task_track_started=True,
+    task_acks_late=True,
+    worker_prefetch_multiplier=1,
+    # Retry config
+    task_default_retry_delay=30,
+    task_max_retries=3,
+)
+
+# Auto-discover tasks in tasks/ directory
+celery_app.autodiscover_tasks(["tasks"])

backend/common/websocket_manager.py

+"""
+WebSocket connection manager for real-time event broadcasting.
+Replaces the stub WebSocket endpoint with actual event push.
+"""
+
+import asyncio
+import json
+import logging
+from typing import Dict, Set
+from fastapi import WebSocket
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectionManager:
+    """Manages WebSocket connections grouped by company_id."""
+
+    def __init__(self):
+        self._connections: Dict[str, Set[WebSocket]] = {}
+        self._lock = asyncio.Lock()
+
+    async def connect(self, websocket: WebSocket, company_id: str):
+        await websocket.accept()
+        async with self._lock:
+            if company_id not in self._connections:
+                self._connections[company_id] = set()
+            self._connections[company_id].add(websocket)
+        logger.info(f"WebSocket connected: company={company_id}, total={self.total_connections}")
+
+    async def disconnect(self, websocket: WebSocket, company_id: str):
+        async with self._lock:
+            if company_id in self._connections:
+                self._connections[company_id].discard(websocket)
+                if not self._connections[company_id]:
+                    del self._connections[company_id]
+        logger.info(f"WebSocket disconnected: company={company_id}")
+
+    async def broadcast(self, company_id: str, event_type: str, data: dict):
+        """Send an event to all connections for a company."""
+        message = json.dumps({"type": event_type, "data": data})
+        async with self._lock:
+            connections = list(self._connections.get(company_id, set()))
+
+        stale = []
+        for ws in connections:
+            try:
+                await ws.send_text(message)
+            except Exception:
+                stale.append(ws)
+
+        # Clean up stale connections
+        if stale:
+            async with self._lock:
+                for ws in stale:
+                    if company_id in self._connections:
+                        self._connections[company_id].discard(ws)
+
+    async def broadcast_all(self, event_type: str, data: dict):
+        """Send an event to ALL connected clients regardless of company."""
+        message = json.dumps({"type": event_type, "data": data})
+        async with self._lock:
+            all_connections = [
+                ws for conns in self._connections.values() for ws in conns
+            ]
+
+        for ws in all_connections:
+            try:
+                await ws.send_text(message)
+            except Exception:
+                pass
+
+    @property
+    def total_connections(self) -> int:
+        return sum(len(conns) for conns in self._connections.values())
+
+
+# Singleton instance
+ws_manager = ConnectionManager()

backend/models/database.py

@@ -19,7 +19,7 @@ from config import settings
 # For in-memory: sqlite+aiosqlite:///:memory:
 DATABASE_URL = settings.database_url
 
-# Async engine for aiosqlite
+# Async engine - supports both SQLite and PostgreSQL
 if DATABASE_URL.startswith("sqlite+"):
     async_engine = create_async_engine(
         DATABASE_URL,
@@ -29,6 +29,15 @@ if DATABASE_URL.startswith("sqlite+"):
             "check_same_thread": False
         } if ":memory:" not in DATABASE_URL else {},
     )
+elif DATABASE_URL.startswith("postgresql+asyncpg"):
+    async_engine = create_async_engine(
+        DATABASE_URL,
+        echo=settings.debug,
+        pool_size=20,
+        max_overflow=10,
+        pool_pre_ping=True,
+        pool_recycle=3600,
+    )
 else:
     async_engine = create_async_engine(DATABASE_URL, echo=settings.debug)
 

backend/requirements.txt

@@ -15,6 +15,11 @@ openai>=1.30.0
 langchain-core>=0.2.0
 pyyaml>=6.0
 fire>=0.5.0
+# Database drivers
+asyncpg>=0.29.0
+psycopg2-binary>=2.9.9
+# Task queue
+celery[redis]>=5.3.0
 # Testing
 pytest==8.1.1
 pytest-asyncio==0.23.5

backend/scratch/demo_both_agent_creation_flows.py

+import asyncio
+import sys
+import uuid
+import json
+from pathlib import Path
+from datetime import datetime
+
+# Add backend to sys.path
+backend_dir = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(backend_dir))
+
+from database import get_db_context
+from models import Agent, Company, CompanyMembership, AuthUser
+from sqlalchemy import select
+
+async def setup_test_db():
+    """Ensure database has the required seed data: User, Company, and CEO Agent."""
+    print("Setting up database for E2E Agent creation demo...")
+    async with get_db_context() as session:
+        # 1. Ensure user exists
+        user_result = await session.execute(select(AuthUser).where(AuthUser.id == "local-board"))
+        user = user_result.scalar_one_or_none()
+        if not user:
+            user = AuthUser(id="local-board", name="Local Board Admin", email="admin@paperclip.ai")
+            session.add(user)
+
+        # 2. Ensure company exists
+        company_result = await session.execute(select(Company).where(Company.id == "company_123"))
+        company = company_result.scalar_one_or_none()
+        if not company:
+            company = Company(id="company_123", name="Canifa Swarm Inc.", issue_prefix="CAN", status="active")
+            session.add(company)
+
+        # 3. Ensure membership exists
+        membership_result = await session.execute(
+            select(CompanyMembership).where(
+                CompanyMembership.company_id == "company_123",
+                CompanyMembership.principal_id == "local-board"
+            )
+        )
+        membership = membership_result.scalar_one_or_none()
+        if not membership:
+            membership = CompanyMembership(
+                id="membership_123",
+                company_id="company_123",
+                principal_type="user",
+                principal_id="local-board",
+                status="active",
+                membership_role="instance_admin"
+            )
+            session.add(membership)
+
+        # 4. Ensure CEO Agent exists (Flow A & B need a CEO to report to)
+        ceo_result = await session.execute(select(Agent).where(Agent.id == "agent_ceo"))
+        ceo = ceo_result.scalar_one_or_none()
+        if not ceo:
+            print("Creating CEO Agent (agent_ceo)...")
+            ceo = Agent(
+                id="agent_ceo",
+                company_id="company_123",
+                name="CEO Director",
+                role="ceo",
+                title="Chief Executive Officer",
+                status="active",
+                capabilities="org-planning, delegating, project-orchestration",
+                adapter_type="custom",
+                adapter_config={"model": "gpt-4o"},
+                runtime_config={},
+                permissions={"canCreateAgents": True}
+            )
+            session.add(ceo)
+        else:
+            print("CEO Agent already exists.")
+
+        await session.commit()
+    print("Database seeding complete.")
+
+async def simulate_flow_a_ai_creation():
+    """
+    FLOW A: AI (CEO Agent) generated agent creation.
+    We simulate the CEO Agent receiving an issue to spawn a Designer Agent.
+    The CEO Agent processes the task and executes a Python function or calls the creation logic.
+    """
+    print("\n--- RUNNING FLOW A: AI (CEO Agent) Generated Agent ---")
+    
+    # 1. Simulate the User prompt / Issue
+    user_prompt = "Create a designer agent named UI Designer to design a dark mode theme with HSL variables."
+    print(f"User Request to CEO Agent: '{user_prompt}'")
+    
+    # 2. Simulate the CEO Agent planning the creation:
+    # CEO parses the prompt and decides to create an agent with:
+    # Name: HSL UI Designer, Role: designer, Title: UI/UX Design Specialist, Skills: figma, design-system, css
+    print("CEO Agent plans the agent structure...")
+    new_agent_name = "HSL UI Designer"
+    new_agent_role = "designer"
+    new_agent_title = "UI/UX Design Specialist"
+    new_agent_skills = "figma,design-system,css"
+    
+    print(f"CEO Agent executing creation tool for: {new_agent_name} ({new_agent_title}) reporting to agent_ceo")
+    
+    # 3. CEO Agent executes the DB write to hire/create the agent
+    async with get_db_context() as db:
+        new_id = f"agent_designer_{uuid.uuid4().hex[:8]}"
+        designer_agent = Agent(
+            id=new_id,
+            company_id="company_123",
+            name=new_agent_name,
+            role=new_agent_role,
+            title=new_agent_title,
+            status="active",
+            reports_to="agent_ceo",
+            capabilities=new_agent_skills,
+            adapter_type="openai",
+            adapter_config={"model": "gpt-4o-mini"},
+            runtime_config={},
+            permissions={}
+        )
+        db.add(designer_agent)
+        await db.commit()
+        print(f"SUCCESS: CEO Agent successfully created Designer Agent '{new_agent_name}' (ID: {new_id}) reporting to agent_ceo!")
+
+async def run_flow_b_manual_creation():
+    """
+    FLOW B: Manual user configuration via /api/agent-hires route.
+    The user manually builds the payload on the UI and submits it.
+    """
+    print("\n--- RUNNING FLOW B: Manual User Configuration via Endpoint ---")
+    
+    # Simulate API route call directly using the new handler
+    from api.routes.agent_hires import hire_agent, AgentHireRequest
+    
+    # 1. Construct the manual payload from the user configuration form
+    # The user specifies that the Coder Agent should report to the CEO (agent_ceo)
+    payload = AgentHireRequest(
+        name="Senior Frontend Coder",
+        role="coder",
+        title="Senior Frontend Developer",
+        reportsTo="agent_ceo",
+        desiredSkills=["html-css", "javascript", "responsive-design"],
+        adapterType="openai",
+        defaultEnvironmentId=None,
+        adapterConfig={"model": "gpt-4o-mini"},
+        runtime_config={"heartbeatEnabled": True},
+        budgetMonthlyCents=0
+    )
+    
+    print(f"Submitting POST request to /api/agent-hires for manual Coder Agent: '{payload.name}'...")
+    
+    # 2. Invoke the FastAPI route controller
+    async with get_db_context() as db:
+        response = await hire_agent(
+            payload=payload,
+            company_id="company_123",
+            db=db,
+            current_user=AuthUser(id="local-board")  # Mock current user matching db record
+        )
+        
+    print("SUCCESS: Endpoint returned 201 Created!")
+    print(f"Response Payload:\n{json.dumps(response, indent=2)}")
+
+async def verify_and_print_hierarchy():
+    """Query the DB and output the final organization tree to verify relationships."""
+    print("\n--- VERIFYING ORG CHART HIERARCHY ---")
+    async with get_db_context() as db:
+        agents = (await db.execute(select(Agent).where(Agent.company_id == "company_123"))).scalars().all()
+        
+        # Build hierarchy tree map
+        nodes = {a.id: {"name": a.name, "role": a.role, "title": a.title, "reports_to": a.reports_to, "children": []} for a in agents}
+        roots = []
+        for agent_id, info in nodes.items():
+            parent_id = info["reports_to"]
+            if parent_id and parent_id in nodes:
+                nodes[parent_id]["children"].append(info)
+            else:
+                roots.append(info)
+                
+        def print_tree(node, indent=0):
+            prefix = "  " * indent + "|-- " if indent > 0 else ""
+            print(f"{prefix}{node['name']} ({node['title']}) [{node['role'].upper()}]")
+            for child in node["children"]:
+                print_tree(child, indent + 1)
+                
+        print("Final Org Chart:")
+        for root in roots:
+            print_tree(root)
+
+async def main():
+    await setup_test_db()
+    await simulate_flow_a_ai_creation()
+    await run_flow_b_manual_creation()
+    await verify_and_print_hierarchy()
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/scratch/inspect_db.py

@@ -2,15 +2,14 @@ import sqlite3
 import json
 
 def inspect():
-    conn = sqlite3.connect('backend/paperclip.db')
+    conn = sqlite3.connect('paperclip.db')
     cursor = conn.cursor()
     
     # List tables
     cursor.execute("SELECT name FROM sqlite_master WHERE type='table';")
     tables = [t[0] for t in cursor.fetchall()]
-    print("Tables:", tables)
     
-    for table in ['companies', 'adapters', 'company_skills']:
+    for table in ['issues', 'goals', 'projects']:
         if table in tables:
             print(f"\n--- Table: {table} ---")
             cursor.execute(f"PRAGMA table_info({table});")
@@ -20,7 +19,7 @@ def inspect():
             cursor.execute(f"SELECT * FROM {table};")
             rows = cursor.fetchall()
             print(f"Row count: {len(rows)}")
-            for r in rows:
+            for r in rows[:5]:
                 print(dict(zip(cols, r)))
                 
     conn.close()

backend/scratch/inspect_run_logs.py

+import sqlite3
+import json
+
+def inspect():
+    conn = sqlite3.connect('paperclip.db')
+    cursor = conn.cursor()
+    
+    # Query run logs, get the 100 most recent log entries ordered by created_at ASC
+    cursor.execute("""
+        SELECT * FROM (
+            SELECT run_id, log_type, message, created_at 
+            FROM execution_run_logs 
+            ORDER BY created_at DESC 
+            LIMIT 100
+        ) ORDER BY created_at ASC;
+    """)
+    rows = cursor.fetchall()
+    print(f"Total Log entries shown: {len(rows)}")
+    
+    current_run = None
+    for r in rows:
+        run_id, log_type, message, created_at = r
+        if run_id != current_run:
+            print(f"\n==========================================")
+            print(f"RUN ID: {run_id}")
+            print(f"==========================================")
+            current_run = run_id
+            
+        print(f"[{created_at}] [{log_type.upper()}] {message}")
+        
+    conn.close()
+
+if __name__ == "__main__":
+    inspect()

backend/scratch/query_agents.py

+import asyncio
+import sys
+from pathlib import Path
+
+# Add backend directory to sys.path
+backend_dir = Path(__file__).resolve().parent.parent
+sys.path.append(str(backend_dir))
+
+from database import get_db_context
+from models import Agent, Company
+
+async def main():
+    async with get_db_context() as db:
+        from sqlalchemy import select
+        # Companies
+        companies = (await db.execute(select(Company))).scalars().all()
+        print(f"=== COMPANIES ({len(companies)}) ===")
+        for c in companies:
+            print(f"- ID: {c.id} | Name: {c.name} | Prefix: {c.issue_prefix}")
+            
+        # Agents
+        agents = (await db.execute(select(Agent))).scalars().all()
+        print(f"\n=== AGENTS ({len(agents)}) ===")
+        for a in agents:
+            print(f"- ID: {a.id} | Name: {a.name} | Role: {a.role} | Title: {a.title} | ReportsTo: {a.reports_to} | CompanyID: {a.company_id}")
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/scratch/run_real_landing_page_build.py

+import requests
+import time
+import json
+import os
+import shutil
+from pathlib import Path
+
+BASE_URL = "http://127.0.0.1:3100"
+COMPANY_ID = "company_123"
+
+def stream_logs(run_id):
+    url = f"{BASE_URL}/api/companies/{COMPANY_ID}/runs/{run_id}/stream"
+    print(f"\n[STREAM] Streaming logs for Run {run_id}...")
+    try:
+        # Use a longer timeout because real agent runs make actual API calls
+        response = requests.get(url, stream=True, timeout=120)
+        for line in response.iter_lines():
+            if line:
+                line_str = line.decode("utf-8")
+                if line_str.startswith("data: "):
+                    data = json.loads(line_str[6:])
+                    if data.get("event") == "done":
+                        print(f"\n[STREAM] --- RUN FINISHED with status: {data.get('status')} ---")
+                        break
+                    
+                    log_type = data.get("log_type", "info").upper()
+                    message = data.get("message")
+                    # If it's a tool call, print it in a highlighted way
+                    if log_type == "TOOL_START":
+                        print(f"🛠️  [TOOL START] calling {message} with args: {data.get('metadata')}")
+                    elif log_type == "TOOL_COMPLETE":
+                        print(f"✅ [TOOL COMPLETE] {message}")
+                    else:
+                        print(f"[{log_type}] {message}")
+    except Exception as e:
+        print(f"Error streaming logs: {e}")
+
+def run_agent_and_wait(agent_id, label, user_message):
+    print(f"\n" + "="*60)
+    print(f"🚀 WAKING UP {label} ({agent_id}) FOR REAL RUN")
+    print(f"Goal: {user_message}")
+    print("="*60)
+    
+    wakeup_url = f"{BASE_URL}/api/agents/{agent_id}/wakeup?company_id={COMPANY_ID}"
+    payload = {
+        "user_message": user_message,
+        "source": "on_demand"
+    }
+    
+    res = requests.post(wakeup_url, json=payload)
+    if res.status_code not in (200, 201):
+        print(f"ERROR waking up {agent_id}: status={res.status_code}, response={res.text}")
+        return None
+        
+    run_data = res.json()
+    run_id = run_data["id"]
+    print(f"Run created successfully: ID = {run_id}")
+    
+    # Stream the logs (blocks until completed)
+    stream_logs(run_id)
+    
+    # Check final status
+    status_url = f"{BASE_URL}/api/companies/{COMPANY_ID}/runs/{run_id}"
+    res = requests.get(status_url)
+    if res.status_code == 200:
+        final_data = res.json()
+        print(f"Final Run Status: {final_data['status']}")
+    else:
+        print(f"Failed to fetch run details: {res.status_code}")
+        
+    return run_id
+
+def main():
+    print("==============================================================")
+    print("STARTING REAL E2E AGENT RUN FROM A TO Z (NO MOCK SIMULATION)")
+    print("==============================================================")
+    
+    # 1. Clean up shared workspace to start fresh
+    shared_dir = Path("workspaces") / COMPANY_ID / "shared"
+    if shared_dir.exists():
+        print(f"Cleaning up old files in {shared_dir.absolute()}...")
+        shutil.rmtree(shared_dir)
+    shared_dir.mkdir(parents=True, exist_ok=True)
+    
+    # 2. Wake up PM to create spec
+    run_pm_id = run_agent_and_wait(
+        "agent_pm", 
+        "PM Agent", 
+        "Hãy tạo một bản đặc tả thiết kế spec.md cho trang landing page của thương hiệu quần áo Canifa. Giao diện tối (Dark Mode), sử dụng Bento Grid để trưng bày sản phẩm premium, font chữ Outfit và bảng màu HSL tinh tế."
+    )
+    if not run_pm_id:
+        return
+        
+    # 3. Wake up Coder to write HTML and CSS
+    run_coder_id = run_agent_and_wait(
+        "agent_coder", 
+        "Coder Agent", 
+        "Hãy dựa vào bản đặc tả spec.md trong shared workspace để lập trình và viết mã nguồn cho trang landing page. Tạo các file index.html và styles.css. Hãy chắc chắn sử dụng layout Bento Grid đẹp mắt, responsive tốt trên mobile, và thêm các hiệu ứng mượt mà như glassmorphism."
+    )
+    if not run_coder_id:
+        return
+        
+    # 4. Wake up QA to verify files and write report
+    run_qa_id = run_agent_and_wait(
+        "agent_qa", 
+        "QA Agent", 
+        "Hãy kiểm tra giao diện và mã nguồn của landing page trong shared workspace để đảm bảo không có lỗi hiển thị hay cấu trúc. Viết báo cáo qa_report.txt."
+    )
+    if not run_qa_id:
+        return
+        
+    # 5. Verify and display the generated files
+    print(f"\n" + "="*60)
+    print(f"VERIFYING GENERATED FILES IN SHARED WORKSPACE...")
+    print(f"Shared directory: {shared_dir.absolute()}")
+    print("="*60)
+    
+    expected_files = ["spec.md", "index.html", "styles.css", "qa_report.txt"]
+    for fname in expected_files:
+        fpath = shared_dir / fname
+        if fpath.exists():
+            print(f"\n[FOUND] {fname} ({fpath.stat().st_size} bytes)")
+            print("-" * 40)
+            with open(fpath, "r", encoding="utf-8") as f:
+                content = f.read()
+                # Print first 500 characters
+                if len(content) > 500:
+                    print(content[:500] + "\n... (truncated)")
+                else:
+                    print(content)
+            print("-" * 40)
+        else:
+            print(f"\n[MISSING] {fname}")
+
+if __name__ == "__main__":
+    main()

backend/scratch/run_sync_agents_e2e.py

+import asyncio
+import os
+import sys
+import shutil
+from pathlib import Path
+
+# Add backend directory to sys.path
+sys.path.append(os.path.abspath('.'))
+sys.path.append(os.path.abspath('agent'))
+
+from agent.run_agent import AIAgent
+from tools.get_tools import register_company_tools
+from model_tools import get_tool_definitions
+
+async def run_agent(agent_id, name, prompt, workspace_path):
+    print(f"\n" + "="*60)
+    print(f"🚀 RUNNING AGENT: {name} ({agent_id})")
+    print(f"Prompt: {prompt}")
+    print("="*60)
+    
+    # Force the workspace directory for the agent VM
+    os.environ["AGENT_WORKSPACE"] = str(workspace_path)
+    
+    agent = AIAgent(
+        model_name="claude-sonnet-4-6",
+        api_key="wrapper-test-key",
+        base_url="https://claude-api-wrapper.cuccu-legal-api.workers.dev",
+        api_mode="anthropic_messages",
+        company_id="company_123",
+    )
+    
+    # Register and reload tools
+    register_company_tools("company_123")
+    agent.tools = get_tool_definitions(quiet_mode=agent.quiet_mode)
+    agent.valid_tool_names = {tool["function"]["name"] for tool in agent.tools}
+    
+    # Define simple step callback to print progress
+    def step_callback(step_num, prev_tools):
+        print(f"🔄 [Step {step_num}] Running...")
+        if prev_tools:
+            for pt in prev_tools:
+                print(f"   🛠️ Used tool: {pt.get('name')} -> arguments: {pt.get('arguments')}")
+                
+    agent.step_callback = step_callback
+    
+    res = await agent.run_conversation(
+        user_message=prompt,
+        system_message=f"You are the {name} AI Agent. Use your workspace tools to read and write files in the directory. Always use tools to execute file operations.",
+    )
+    
+    print(f"🤖 {name} Response:\n{res.get('response')}")
+    print(f"Iterations: {res.get('iterations')}")
+    return res
+
+async def main():
+    workspace_path = Path("workspaces") / "company_123" / "shared"
+    if workspace_path.exists():
+        print(f"Cleaning workspace: {workspace_path.absolute()}")
+        shutil.rmtree(workspace_path)
+    workspace_path.mkdir(parents=True, exist_ok=True)
+    
+    # 1. PM Agent writes the spec.md
+    pm_prompt = (
+        "Hãy tạo một đặc tả thiết kế spec.md cho trang landing page của Canifa. "
+        "Giao diện tối (Dark Mode), sử dụng Bento Grid để trưng bày sản phẩm premium, "
+        "font chữ Outfit, và bảng màu HSL tinh tế. Ghi trực tiếp vào file spec.md."
+    )
+    await run_agent("agent_pm", "Product Manager", pm_prompt, workspace_path)
+    
+    # 2. Coder Agent reads spec.md and writes index.html and styles.css
+    coder_prompt = (
+        "Đọc file spec.md để hiểu yêu cầu thiết kế. Hãy lập trình và viết mã nguồn cho trang landing page "
+        "gồm file index.html và styles.css. Đảm bảo sử dụng Bento Grid đẹp mắt, responsive tốt trên mobile, "
+        "và có các hiệu ứng mượt mà như glassmorphism."
+    )
+    await run_agent("agent_coder", "Developer", coder_prompt, workspace_path)
+    
+    # 3. QA Agent reads index.html and styles.css and writes qa_report.txt
+    qa_prompt = (
+        "Kiểm tra các file index.html và styles.css xem cấu trúc đã đúng chuẩn bento grid chưa, "
+        "có responsive trên mobile không và giao diện màu sắc có đúng spec.md không. "
+        "Tạo một file báo cáo kết quả kiểm thử qa_report.txt."
+    )
+    await run_agent("agent_qa", "QA Engineer", qa_prompt, workspace_path)
+    
+    # Display results
+    print("\n" + "="*60)
+    print("VERIFYING GENERATED ASSETS IN SHARED WORKSPACE:")
+    print("="*60)
+    for fname in ["spec.md", "index.html", "styles.css", "qa_report.txt"]:
+        fpath = workspace_path / fname
+        if fpath.exists():
+            print(f"\n[FOUND] {fname} ({fpath.stat().st_size} bytes)")
+            print("-" * 40)
+            with open(fpath, "r", encoding="utf-8") as f:
+                print(f.read())
+            print("-" * 40)
+        else:
+            print(f"\n[MISSING] {fname}")
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/scratch/seed_db.py

+import sys
+import os
+import asyncio
+from pathlib import Path
+
+# Add backend to sys.path
+backend_dir = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(backend_dir))
+
+from database import get_db_context
+from models import AuthUser, Company, CompanyMembership
+from sqlalchemy import select
+
+async def main():
+    print("Seeding database...")
+    async with get_db_context() as session:
+        # 1. Check/Seed local-board user
+        user_result = await session.execute(select(AuthUser).where(AuthUser.id == "local-board"))
+        user = user_result.scalar_one_or_none()
+        if not user:
+            print("Creating local-board user...")
+            user = AuthUser(
+                id="local-board",
+                name="Local Board Admin",
+                email="admin@paperclip.ai",
+                email_verified=True,
+            )
+            session.add(user)
+        else:
+            print("local-board user already exists.")
+
+        # 2. Check/Seed company_123
+        company_result = await session.execute(select(Company).where(Company.id == "company_123"))
+        company = company_result.scalar_one_or_none()
+        if not company:
+            print("Creating company_123 company...")
+            company = Company(
+                id="company_123",
+                name="Canifa Company",
+                issue_prefix="CAN",
+                status="active"
+            )
+            session.add(company)
+        else:
+            print("company_123 company already exists.")
+
+        await session.flush()
+
+        # 3. Check/Seed company membership
+        membership_result = await session.execute(
+            select(CompanyMembership).where(
+                CompanyMembership.company_id == "company_123",
+                CompanyMembership.principal_id == "local-board"
+            )
+        )
+        membership = membership_result.scalar_one_or_none()
+        if not membership:
+            print("Creating company membership...")
+            membership = CompanyMembership(
+                id="membership_123",
+                company_id="company_123",
+                principal_type="user",
+                principal_id="local-board",
+                status="active",
+                membership_role="instance_admin"
+            )
+            session.add(membership)
+        else:
+            print("Company membership already exists.")
+
+        await session.commit()
+    print("Seeding complete.")
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/scratch/test_agent_anthropic.py

+import asyncio
+import os
+import sys
+
+# Add backend directory to sys.path so we can import database, agent, etc.
+sys.path.append(os.path.abspath('.'))
+sys.path.append(os.path.abspath('agent'))
+
+from agent.run_agent import AIAgent
+from tools.get_tools import register_company_tools
+from model_tools import get_tool_definitions
+
+async def main():
+    agent = AIAgent(
+        model_name="claude-sonnet-4-6",
+        api_key="wrapper-test-key",
+        base_url="https://claude-api-wrapper.cuccu-legal-api.workers.dev",
+        api_mode="anthropic_messages",
+        company_id="company_123",
+    )
+    
+    # 1. Register company tools
+    print("Registering company tools...")
+    register_company_tools("company_123")
+    
+    # 2. Re-load agent tools list manually so the agent sees them
+    agent.tools = get_tool_definitions(quiet_mode=agent.quiet_mode)
+    agent.valid_tool_names = {tool["function"]["name"] for tool in agent.tools}
+    
+    print("Registered tools:", list(agent.valid_tool_names) if agent.valid_tool_names else "None")
+    
+    # Let's run a simple message that requires writing a file
+    print("\nRunning conversation...")
+    try:
+        res = await agent.run_conversation(
+            user_message="Hãy chào tôi bằng tiếng Việt và tạo một file test_hello.txt trong thư mục hiện tại chứa nội dung 'Hello Canifa' bằng cách dùng tool write_file.",
+            system_message="You are a helpful assistant. Always use tools to execute user requests.",
+        )
+        print("\nSUCCESS!")
+        print("Response:", res.get("response"))
+        print("Iterations used:", res.get("iterations"))
+    except Exception as e:
+        print("\nERROR:", e)
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/scratch/test_anthropic_direct.py

+import requests
+import json
+
+api_key = "wrapper-test-key"
+headers = {
+    "Authorization": f"Bearer {api_key}",
+    "x-api-key": api_key,
+    "Content-Type": "application/json",
+    "anthropic-version": "2023-06-01"
+}
+
+# Test /v1/messages
+url = "https://claude-api-wrapper.cuccu-legal-api.workers.dev/v1/messages"
+payload = {
+    "model": "claude-sonnet-4-6",
+    "max_tokens": 1000,
+    "messages": [
+        {"role": "user", "content": "What is the weather in Paris?"}
+    ],
+    "tools": [
+        {
+            "name": "get_weather",
+            "description": "Get the current weather in a location",
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "location": {"type": "string", "description": "The city or location"}
+                },
+                "required": ["location"]
+            }
+        }
+    ]
+}
+
+print("Testing /v1/messages...")
+try:
+    res = requests.post(url, headers=headers, json=payload)
+    print("STATUS:", res.status_code)
+    print("RESPONSE:", res.text)
+except Exception as e:
+    print("ERROR:", e)
+
+# Test /messages
+url2 = "https://claude-api-wrapper.cuccu-legal-api.workers.dev/messages"
+print("\nTesting /messages...")
+try:
+    res = requests.post(url2, headers=headers, json=payload)
+    print("STATUS:", res.status_code)
+    print("RESPONSE:", res.text)
+except Exception as e:
+    print("ERROR:", e)

backend/scratch/test_headers.py

+import requests
+
+api_key = "wrapper-test-key"
+url = "https://claude-api-wrapper.cuccu-legal-api.workers.dev/v1/messages"
+
+payload = {
+    "model": "claude-sonnet-4-6",
+    "max_tokens": 10,
+    "messages": [{"role": "user", "content": "Hi"}]
+}
+
+# Test with x-api-key only
+print("Testing with x-api-key only...")
+try:
+    res = requests.post(url, headers={"x-api-key": api_key, "Content-Type": "application/json", "anthropic-version": "2023-06-01"}, json=payload)
+    print("STATUS:", res.status_code)
+    print("RESPONSE:", res.text)
+except Exception as e:
+    print("ERROR:", e)
+
+# Test with Authorization Bearer only
+print("\nTesting with Authorization Bearer only...")
+try:
+    res = requests.post(url, headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json", "anthropic-version": "2023-06-01"}, json=payload)
+    print("STATUS:", res.status_code)
+    print("RESPONSE:", res.text)
+except Exception as e:
+    print("ERROR:", e)

backend/scratch/test_register_tools.py

+import os
+import sys
+import logging
+
+logging.basicConfig(level=logging.INFO)
+sys.path.append(os.path.abspath('.'))
+sys.path.append(os.path.abspath('agent'))
+
+from tools.get_tools import register_company_tools
+from agent.run_agent import AIAgent
+
+print("Registering company tools...")
+try:
+    register_company_tools("company_123")
+    print("Registration completed successfully!")
+except Exception as e:
+    print("ERROR:", e)
+
+# Now check the Hermes ToolRegistry contents
+try:
+    from agent.tools.registry import registry
+    print("Hermes registry tools:", list(registry._registry.keys()))
+except Exception as e:
+    print("ERROR listing registry:", e)

backend/scratch/test_sonnet_tool.py

+import requests
+import json
+
+api_key = "wrapper-test-key"
+base_url = "https://claude-api-wrapper.cuccu-legal-api.workers.dev/v1/chat/completions"
+
+headers = {
+    "Authorization": f"Bearer {api_key}",
+    "Content-Type": "application/json"
+}
+
+payload_tools = {
+    "model": "claude-sonnet-4-6",
+    "max_tokens": 1000,
+    "messages": [
+        {"role": "user", "content": "What is the weather in Paris?"}
+    ],
+    "tools": [
+        {
+            "type": "function",
+            "function": {
+                "name": "get_weather",
+                "description": "Get the current weather in a location",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "location": {"type": "string", "description": "The city or location"}
+                    },
+                    "required": ["location"]
+                }
+            }
+        }
+    ],
+    "tool_choice": {"type": "function", "function": {"name": "get_weather"}},
+    "stream": False
+}
+
+try:
+    response = requests.post(base_url, headers=headers, json=payload_tools)
+    print("STATUS:", response.status_code)
+    print("RESPONSE JSON:")
+    print(json.dumps(response.json(), indent=2))
+except Exception as e:
+    print("ERROR:", e)

backend/scratch/test_swarm_orchestration.py

+"""
+Verification script for Swarm & Subagent Orchestration logic.
+Simulates subagent progress events, records them to DB, and verifies tree reconstruction.
+"""
+
+import asyncio
+import sys
+import os
+import uuid
+from datetime import datetime
+
+# Set backend path
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from models.database import get_db_context, init_db
+from models import HeartbeatRun, ExecutionRunLog
+from services.agent_log_writer import AgentLogWriter
+from api.routes.run_logs import get_run_tree, get_run_logs_filtered
+
+async def run_test():
+    print("Initializing test database...")
+    await init_db()
+
+    # Generate dummy IDs
+    company_id = "test-comp-" + uuid.uuid4().hex[:6]
+    run_id = "run-test-" + uuid.uuid4().hex[:6]
+    agent_id = "agent_pm"
+    model_name = "test-model"
+
+    print(f"Creating mock company run: company_id={company_id}, run_id={run_id}")
+    async with get_db_context() as db:
+        run = HeartbeatRun(
+            id=run_id,
+            company_id=company_id,
+            agent_id=agent_id,
+            status="running",
+            started_at=datetime.utcnow(),
+            created_at=datetime.utcnow(),
+            updated_at=datetime.utcnow()
+        )
+        db.add(run)
+        await db.commit()
+
+    print("Instantiating AgentLogWriter...")
+    log_writer = AgentLogWriter(run_id=run_id, company_id=company_id)
+
+    # Verify captured loop
+    assert log_writer.loop is not None, "Log writer must capture the running event loop"
+
+    print("Firing subagent progress callbacks...")
+    # 1. Main CEO Agent logs thinking
+    log_writer.on_subagent_progress("delegate.task_thinking", preview="CEO Planning the project steps")
+    
+    # 2. PM Agent subagent starts
+    pm_sid = "sa-0-pm"
+    log_writer.on_subagent_progress(
+        "subagent.start",
+        goal="Analyze requirements and build spec.md",
+        subagent_id=pm_sid,
+        parent_id=None,
+        depth=1,
+        status="running"
+    )
+    
+    # PM Agent writes file
+    log_writer.on_subagent_progress(
+        "tool.started",
+        tool_name="write_file",
+        preview="spec.md",
+        args={"path": "spec.md", "content": "Theme: Dark Mode"},
+        subagent_id=pm_sid,
+        parent_id=None,
+        depth=1,
+        goal="Analyze requirements and build spec.md"
+    )
+    log_writer.on_subagent_progress(
+        "tool.completed",
+        tool_name="write_file",
+        preview="Successfully wrote 24 characters to spec.md",
+        subagent_id=pm_sid,
+        parent_id=None,
+        depth=1,
+        goal="Analyze requirements and build spec.md"
+    )
+    
+    # PM Agent completes
+    log_writer.on_subagent_progress(
+        "subagent.complete",
+        preview="Created spec.md successfully",
+        subagent_id=pm_sid,
+        parent_id=None,
+        depth=1,
+        goal="Analyze requirements and build spec.md",
+        status="completed"
+    )
+
+    # 3. Coder Agent starts (spawns under PM Agent to simulate nested depth=2)
+    coder_sid = "sa-1-coder"
+    log_writer.on_subagent_progress(
+        "subagent.start",
+        goal="Implement index.html and layouts",
+        subagent_id=coder_sid,
+        parent_id=pm_sid,
+        depth=2,
+        status="running"
+    )
+    
+    # Coder Agent executes command
+    log_writer.on_subagent_progress(
+        "tool.started",
+        tool_name="terminal",
+        preview="npm run dev",
+        args={"command": "npm run dev"},
+        subagent_id=coder_sid,
+        parent_id=pm_sid,
+        depth=2,
+        goal="Implement index.html and layouts"
+    )
+    log_writer.on_subagent_progress(
+        "tool.completed",
+        tool_name="terminal",
+        preview="Vite server running on port 5173",
+        subagent_id=coder_sid,
+        parent_id=pm_sid,
+        depth=2,
+        goal="Implement index.html and layouts"
+    )
+    
+    # Coder Agent completes
+    log_writer.on_subagent_progress(
+        "subagent.complete",
+        preview="Coded index.html successfully",
+        subagent_id=coder_sid,
+        parent_id=pm_sid,
+        depth=2,
+        goal="Implement index.html and layouts",
+        status="completed"
+    )
+
+    # Let async writes settle
+    print("Waiting for database writes to settle...")
+    await asyncio.sleep(1.0)
+
+    # Verify database logs
+    print("Verifying log entries in DB...")
+    async with get_db_context() as db:
+        from sqlalchemy import select
+        result = await db.execute(
+            select(ExecutionRunLog).where(ExecutionRunLog.run_id == run_id)
+        )
+        logs = result.scalars().all()
+        print(f"Total logs written to DB: {len(logs)}")
+        assert len(logs) > 0, "No logs were written to the database"
+
+        subagent_logs = [l for l in logs if l.log_metadata and "subagent_id" in l.log_metadata]
+        print(f"Total subagent logs: {len(subagent_logs)}")
+        assert len(subagent_logs) == 8, f"Expected 8 subagent logs, got {len(subagent_logs)}"
+
+        # Check metadata attributes
+        for log in subagent_logs:
+            meta = log.log_metadata
+            print(f"Log type: {log.log_type} | Msg: {log.message[:40]} | Meta: {meta}")
+            assert "subagent_id" in meta
+            assert "depth" in meta
+            assert "goal" in meta
+            assert "agent_name" in meta
+            assert "status" in meta
+
+            # Test agent name derivation
+            if meta["subagent_id"] == pm_sid:
+                assert meta["agent_name"] == "PM Agent", f"Expected PM Agent, got {meta['agent_name']}"
+            elif meta["subagent_id"] == coder_sid:
+                assert meta["agent_name"] == "Coder Agent", f"Expected Coder Agent, got {meta['agent_name']}"
+
+    # Verify Swarm Tree API
+    print("Verifying Swarm Tree endpoint...")
+    class MockScope:
+        pass
+    
+    # Call endpoint function directly
+    class MockDbSession:
+        def __init__(self, db):
+            self.db = db
+        async def execute(self, stmt):
+            return await self.db.execute(stmt)
+
+    async with get_db_context() as db:
+        tree = await get_run_tree(
+            company_id=company_id,
+            run_id=run_id,
+            scope=MockScope(),
+            db=db
+        )
+        
+        import json
+        print("Generated Swarm Tree:")
+        print(json.dumps(tree, indent=2))
+        
+        # Verify structure
+        assert tree["run_id"] == run_id
+        assert len(tree["subagents"]) == 1  # only pm_sid is root (coder is nested under pm)
+        pm_node = tree["subagents"][0]
+        assert pm_node["subagent_id"] == pm_sid
+        assert pm_node["agent_name"] == "PM Agent"
+        assert len(pm_node["subagents"]) == 1
+        
+        coder_node = pm_node["subagents"][0]
+        assert coder_node["subagent_id"] == coder_sid
+        assert coder_node["agent_name"] == "Coder Agent"
+        assert coder_node["parent_id"] == pm_sid
+
+    # Verify Logs filtering API
+    print("Verifying Logs Filtering endpoint...")
+    async with get_db_context() as db:
+        # Filter for PM agent only
+        pm_logs = await get_run_logs_filtered(
+            company_id=company_id,
+            run_id=run_id,
+            subagent_id=pm_sid,
+            scope=MockScope(),
+            db=db
+        )
+        print(f"PM subagent logs count: {len(pm_logs)}")
+        assert len(pm_logs) == 4, f"Expected 4 PM logs, got {len(pm_logs)}"
+        for l in pm_logs:
+            assert l.log_metadata["subagent_id"] == pm_sid
+
+        # Filter for Coder agent only
+        coder_logs = await get_run_logs_filtered(
+            company_id=company_id,
+            run_id=run_id,
+            subagent_id=coder_sid,
+            scope=MockScope(),
+            db=db
+        )
+        print(f"Coder subagent logs count: {len(coder_logs)}")
+        assert len(coder_logs) == 4, f"Expected 4 Coder logs, got {len(coder_logs)}"
+        for l in coder_logs:
+            assert l.log_metadata["subagent_id"] == coder_sid
+
+        # Filter for max depth = 1 (excludes coder at depth 2)
+        depth_1_logs = await get_run_logs_filtered(
+            company_id=company_id,
+            run_id=run_id,
+            max_depth=1,
+            scope=MockScope(),
+            db=db
+        )
+        print(f"Logs at max_depth=1: {len(depth_1_logs)}")
+        # 1 CEO log (depth=0) + 4 PM logs (depth=1) = 5 logs
+        assert len(depth_1_logs) == 5, f"Expected 5 logs, got {len(depth_1_logs)}"
+
+    print("ALL SWARM ORCHESTRATION TESTS PASSED SUCCESSFULLY!")
+
+if __name__ == "__main__":
+    asyncio.run(run_test())

backend/scratch/test_wrapper_tool.py

+import requests
+import json
+
+api_key = "wrapper-test-key"
+base_url = "https://claude-api-wrapper.cuccu-legal-api.workers.dev/v1/chat/completions"
+
+headers = {
+    "Authorization": f"Bearer {api_key}",
+    "Content-Type": "application/json"
+}
+
+payload_tools = {
+    "model": "claude-sonnet-4-6",
+    "max_tokens": 1000,
+    "messages": [
+        {"role": "user", "content": "What is the weather in Paris? Call the get_weather tool."}
+    ],
+    "tools": [
+        {
+            "type": "function",
+            "function": {
+                "name": "get_weather",
+                "description": "Get the current weather in a location",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "location": {"type": "string", "description": "The city or location"}
+                    },
+                    "required": ["location"]
+                }
+            }
+        }
+    ],
+    "stream": False
+}
+
+try:
+    response = requests.post(base_url, headers=headers, json=payload_tools)
+    print("STATUS:", response.status_code)
+    print("RESPONSE JSON:")
+    print(json.dumps(response.json(), indent=2))
+except Exception as e:
+    print("ERROR:", e)

backend/server.py

@@ -17,7 +17,7 @@ from api.main_router import main_router as api_router
 from common.cache import redis_cache
 from common.event_bus import event_bus
 from common.middleware import middleware_manager
-from config import PORT, REDIS_CACHE_TURN_ON
+from config import PORT, REDIS_CACHE_TURN_ON, settings
 
 if platform.system() == "Windows":
     logger = logging.getLogger(__name__)
@@ -222,13 +222,22 @@ app.add_middleware(CompanyPathRewriteMiddleware)
 
 @app.websocket("/api/events/ws")
 async def websocket_events_endpoint(websocket: WebSocket):
-    await websocket.accept()
+    """Real-time event broadcasting via WebSocket.
+    
+    Connect with: ws://host/api/events/ws?company_id=xxx
+    Events pushed: agent.status, agent.log, agent.completed, agent.failed
+    """
+    from common.websocket_manager import ws_manager
+    company_id = websocket.query_params.get("company_id", "__global__")
+    await ws_manager.connect(websocket, company_id)
     try:
         while True:
-            # Keep client connected and drop messages
+            # Keep connection alive; client can send pings or subscribe messages
             data = await websocket.receive_text()
+            # Echo back as heartbeat acknowledgement
+            await websocket.send_text('{"type":"pong"}')
     except WebSocketDisconnect:
-        pass
+        await ws_manager.disconnect(websocket, company_id)
 
 
 @app.get("/")
@@ -333,10 +342,12 @@ async def serve_home_static(file_path: str):
 # =====================================================================
 # MIDDLEWARE (after static mount)
 # =====================================================================
+# Auth & rate-limiting are ON by default. Override via DEPLOYMENT_MODE.
+_trusted_mode = getattr(settings, 'deployment_mode', 'production') == 'local_trusted'
 middleware_manager.setup(
     app,
-    enable_auth=False,
-    enable_rate_limit=False,
+    enable_auth=not _trusted_mode,
+    enable_rate_limit=not _trusted_mode,
     enable_cors=True,
     cors_origins=["*"],
 )

backend/services/agent_log_writer.py

@@ -5,6 +5,8 @@ Agent log writer — writes ExecutionRunLog rows from agent callbacks.
 import uuid
 import json
 import logging
+import asyncio
+import threading
 from datetime import datetime
 from typing import Any, Dict, Optional
 
@@ -24,9 +26,14 @@ class AgentLogWriter:
     def __init__(self, run_id: str, company_id: str):
         self.run_id = run_id
         self.company_id = company_id
+        try:
+            self.loop = asyncio.get_running_loop()
+        except RuntimeError:
+            self.loop = None
 
     async def _write_log(self, log_type: str, message: str, metadata: Optional[Dict[str, Any]] = None):
-        """Persist a single log row. Errors are swallowed so agent execution is never blocked."""
+        """Persist a single log row and broadcast via WebSocket.
+        Errors are swallowed so agent execution is never blocked."""
         try:
             async with get_db_context() as db:
                 log = ExecutionRunLog(
@@ -42,7 +49,135 @@ class AgentLogWriter:
         except Exception:
             logger.warning("Failed to write agent log for run %s", self.run_id, exc_info=True)
 
-    # -- Callbacks for AIAgent --
+        # Push real-time event via WebSocket (best-effort, never blocks agent)
+        try:
+            from common.websocket_manager import ws_manager
+            await ws_manager.broadcast(self.company_id, "agent.log", {
+                "run_id": self.run_id,
+                "log_type": log_type,
+                "message": message,
+                "metadata": metadata,
+            })
+        except Exception:
+            pass
+
+    def write_log_sync(self, log_type: str, message: str, metadata: Optional[Dict[str, Any]] = None):
+        """Bridge a synchronous callback to the asynchronous database writer."""
+        coro = self._write_log(log_type, message, metadata)
+        if self.loop and self.loop.is_running():
+            try:
+                # Check if we are running in the loop's thread
+                try:
+                    current_loop = asyncio.get_running_loop()
+                except RuntimeError:
+                    current_loop = None
+
+                if current_loop == self.loop:
+                    self.loop.create_task(coro)
+                else:
+                    asyncio.run_coroutine_threadsafe(coro, self.loop)
+            except Exception as e:
+                logger.warning("Failed to schedule log write asynchronously: %s", e)
+        else:
+            # Fallback: run in a temporary event loop in this thread
+            try:
+                loop = asyncio.new_event_loop()
+                loop.run_until_complete(coro)
+                loop.close()
+            except Exception as e:
+                logger.warning("Failed to run log write in fallback loop: %s", e)
+
+    # -- Unified Progress Callback for AIAgent --
+
+    def on_subagent_progress(
+        self,
+        event_type: str,
+        tool_name: Optional[str] = None,
+        preview: Optional[str] = None,
+        args: Any = None,
+        **kwargs
+    ):
+        """Unified callback handler for parent and subagent progress events."""
+        # Determine if this is a subagent event
+        subagent_id = kwargs.get("subagent_id")
+        depth = kwargs.get("depth")
+        goal = kwargs.get("goal")
+        parent_id = kwargs.get("parent_id")
+
+        metadata = {}
+        if subagent_id:
+            metadata.update({
+                "subagent_id": subagent_id,
+                "parent_subagent_id": parent_id,
+                "depth": depth if depth is not None else 1,
+                "goal": goal,
+                "agent_name": self._get_agent_name(goal or "", subagent_id),
+                "status": kwargs.get("status", "running")
+            })
+
+        # Process specific event types
+        if event_type == "subagent.start":
+            message = f"Subagent started: {goal}"
+            metadata["status"] = "running"
+            self.write_log_sync("info", message, metadata)
+            return
+
+        if event_type == "subagent.complete":
+            status = kwargs.get("status", "completed")
+            message = f"Subagent completed ({status}): {preview or ''}"
+            metadata["status"] = status
+            self.write_log_sync("info", message, metadata)
+            return
+
+        if event_type == "subagent.spawn_requested":
+            message = f"Subagent spawn requested: {preview or goal}"
+            self.write_log_sync("info", message, metadata)
+            return
+
+        is_tool_start = event_type in {"tool.started", "delegate.tool_started"}
+        is_tool_complete = event_type in {"tool.completed", "delegate.tool_completed"}
+        is_thinking = event_type in {"_thinking", "reasoning.available", "delegate.task_thinking"}
+
+        if is_tool_start:
+            message = f"Tool started: {tool_name}"
+            metadata.update({
+                "event": "tool_start",
+                "tool_name": tool_name,
+                "args": json.dumps(args, default=str, ensure_ascii=False) if args else ""
+            })
+            self.write_log_sync("info", message, metadata)
+
+        elif is_tool_complete:
+            message = f"Tool completed: {tool_name}"
+            result_str = str(preview)[:2000] if preview else ""
+            metadata.update({
+                "event": "tool_complete",
+                "tool_name": tool_name,
+                "result_preview": result_str
+            })
+            self.write_log_sync("info", message, metadata)
+
+        elif is_thinking:
+            message = preview[:4000] if preview else (tool_name[:4000] if tool_name else "")
+            if message:
+                metadata.update({
+                    "event": "thinking"
+                })
+                self.write_log_sync("info", message, metadata)
+
+    def _get_agent_name(self, goal: str, subagent_id: str) -> str:
+        goal_lower = goal.lower()
+        if "spec" in goal_lower or "pm" in goal_lower or "plan" in goal_lower:
+            return "PM Agent"
+        elif "css" in goal_lower or "design" in goal_lower or "style" in goal_lower:
+            return "Designer Agent"
+        elif "qa" in goal_lower or "test" in goal_lower or "verify" in goal_lower:
+            return "QA Agent"
+        elif "code" in goal_lower or "html" in goal_lower or "implement" in goal_lower or "program" in goal_lower:
+            return "Coder Agent"
+        return "Worker Agent"
+
+    # -- Callbacks for AIAgent (Legacy compat for mocks) --
 
     async def on_tool_start(self, tool_name: str, args: Any = None):
         args_str = json.dumps(args, default=str, ensure_ascii=False) if args else ""

backend/services/iteration_budget.py

+"""
+Iteration budget and interrupt system for agent execution.
+
+Provides per-role iteration budgets and a module-level interrupt registry
+so the API can signal a running agent to stop mid-execution.
+"""
+
+import threading
+import logging
+from typing import Dict
+
+logger = logging.getLogger(__name__)
+
+# ── Per-role budget defaults ──────────────────────────────────────────
+ROLE_BUDGETS: Dict[str, int] = {
+    "pm": 20,
+    "coder": 50,
+    "qa": 30,
+    "devops": 25,
+    "default": 40,
+}
+
+
+def budget_for_role(role: str) -> int:
+    """Return the iteration cap for a given agent role."""
+    return ROLE_BUDGETS.get(role.lower(), ROLE_BUDGETS["default"])
+
+
+class IterationBudget:
+    """Thread-safe iteration budget with interrupt support.
+
+    Wraps a simple counter with:
+    - consume/remaining tracking
+    - external interrupt flag
+    - one grace call after exhaustion for cleanup
+    """
+
+    def __init__(self, max_iterations: int):
+        self.max_iterations = max_iterations
+        self._used = 0
+        self._interrupt_requested = False
+        self._grace_used = False
+        self._lock = threading.Lock()
+
+    def consume(self) -> int:
+        """Consume one iteration. Returns remaining count."""
+        with self._lock:
+            self._used += 1
+            return max(0, self.max_iterations - self._used)
+
+    @property
+    def remaining(self) -> int:
+        with self._lock:
+            return max(0, self.max_iterations - self._used)
+
+    @property
+    def is_exhausted(self) -> bool:
+        with self._lock:
+            return self._used >= self.max_iterations
+
+    @property
+    def interrupt_requested(self) -> bool:
+        with self._lock:
+            return self._interrupt_requested
+
+    @interrupt_requested.setter
+    def interrupt_requested(self, value: bool):
+        with self._lock:
+            self._interrupt_requested = value
+
+    @property
+    def should_stop(self) -> bool:
+        """True if budget exhausted OR externally interrupted."""
+        with self._lock:
+            if self._interrupt_requested:
+                return True
+            if self._used >= self.max_iterations:
+                # Allow one grace call for cleanup
+                if not self._grace_used:
+                    self._grace_used = True
+                    return False
+                return True
+            return False
+
+    @property
+    def used(self) -> int:
+        with self._lock:
+            return self._used
+
+
+# ── Module-level interrupt registry ───────────────────────────────────
+# Maps run_id -> IterationBudget so the API can reach into a running agent.
+_registry: Dict[str, IterationBudget] = {}
+_registry_lock = threading.Lock()
+
+
+def register_budget(run_id: str, budget: IterationBudget) -> None:
+    """Register a budget instance for a running agent."""
+    with _registry_lock:
+        _registry[run_id] = budget
+
+
+def unregister_budget(run_id: str) -> None:
+    """Remove a budget from the registry after the run completes."""
+    with _registry_lock:
+        _registry.pop(run_id, None)
+
+
+def request_interrupt(run_id: str) -> bool:
+    """Signal a running agent to stop. Returns True if the run was found."""
+    with _registry_lock:
+        budget = _registry.get(run_id)
+    if budget is None:
+        return False
+    budget.interrupt_requested = True
+    logger.info("Interrupt requested for run %s", run_id)
+    return True
+
+
+def is_interrupted(run_id: str) -> bool:
+    """Check whether an interrupt has been requested for a run."""
+    with _registry_lock:
+        budget = _registry.get(run_id)
+    if budget is None:
+        return False
+    return budget.interrupt_requested
+
+
+def clear_interrupt(run_id: str) -> None:
+    """Clear the interrupt flag for a run."""
+    with _registry_lock:
+        budget = _registry.get(run_id)
+    if budget is not None:
+        budget.interrupt_requested = False

backend/tasks/__init__.py

+"""Celery background tasks."""

backend/tasks/agent_tasks.py

+"""
+Agent execution tasks — runs agent pipelines in Celery workers.
+This replaces FastAPI BackgroundTasks so agent runs survive server restarts.
+"""
+
+import logging
+import os
+import asyncio
+from celery import shared_task
+
+logger = logging.getLogger(__name__)
+
+
+def _run_async(coro):
+    """Helper to run async code inside a sync Celery task."""
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        return loop.run_until_complete(coro)
+    finally:
+        loop.close()
+
+
+@shared_task(
+    bind=True,
+    name="tasks.run_agent",
+    max_retries=3,
+    default_retry_delay=30,
+    acks_late=True,
+)
+def run_agent_task(self, run_id: str, agent_id: str, company_id: str, model_name: str, prompt: str):
+    """
+    Execute an AI agent run as a Celery task.
+    Retries up to 3 times with 30s/60s/120s exponential backoff on failure.
+    """
+    logger.info(f"[Celery] Starting agent task: run_id={run_id}, agent_id={agent_id}")
+
+    async def _execute():
+        # Import here to avoid circular imports at module load time
+        from models.database import get_db_context
+        from services.agent_log_writer import AgentLogWriter
+        from services.workspace_manager import WorkspaceManager
+        from agent.run_agent import AIAgent
+
+        workspace = None
+        try:
+            # 1. Create isolated workspace
+            workspace = WorkspaceManager.create(company_id, run_id)
+            os.environ["AGENT_WORKSPACE"] = str(workspace)
+
+            # 2. Update run status to 'running'
+            async with get_db_context() as db:
+                from sqlalchemy import update
+                from models.heartbeat_runs import HeartbeatRun
+                await db.execute(
+                    update(HeartbeatRun)
+                    .where(HeartbeatRun.id == run_id)
+                    .values(status="running")
+                )
+                await db.commit()
+
+            # 3. Create log writer and agent
+            log_writer = AgentLogWriter(run_id=run_id, company_id=company_id)
+            ai_agent = AIAgent(
+                model_name=model_name,
+                company_id=company_id,
+                tool_progress_callback=log_writer.on_subagent_progress,
+                step_callback=log_writer.on_step,
+                status_callback=log_writer.on_status,
+            )
+
+            # 4. Run conversation
+            result = await ai_agent.run_conversation(prompt)
+
+            # 5. Mark as completed
+            async with get_db_context() as db:
+                from sqlalchemy import update
+                from models.heartbeat_runs import HeartbeatRun
+                await db.execute(
+                    update(HeartbeatRun)
+                    .where(HeartbeatRun.id == run_id)
+                    .values(status="completed")
+                )
+                await db.commit()
+
+            logger.info(f"[Celery] Agent task completed: run_id={run_id}")
+            return {"status": "completed", "run_id": run_id}
+
+        except Exception as exc:
+            # Mark as failed in DB
+            try:
+                async with get_db_context() as db:
+                    from sqlalchemy import update
+                    from models.heartbeat_runs import HeartbeatRun
+                    await db.execute(
+                        update(HeartbeatRun)
+                        .where(HeartbeatRun.id == run_id)
+                        .values(status="failed", error_message=str(exc)[:500])
+                    )
+                    await db.commit()
+            except Exception:
+                logger.error(f"Failed to update run status for {run_id}")
+
+            logger.error(f"[Celery] Agent task failed: {exc}", exc_info=True)
+            # Retry with exponential backoff: 30s, 60s, 120s
+            raise self.retry(exc=exc, countdown=30 * (2 ** self.request.retries))
+
+        finally:
+            os.environ.pop("AGENT_WORKSPACE", None)
+
+    return _run_async(_execute())

docker-compose.yml

@@ -222,9 +222,46 @@ services:
     depends_on:
       - cuccu-backend
 
+  # ──────────────────────────────────────────────
+  # PAPERCLIP DATABASE (PostgreSQL - Production)
+  # ──────────────────────────────────────────────
+  paperclip-postgres:
+    image: docker.io/postgres:17
+    container_name: paperclip_postgres
+    environment:
+      - POSTGRES_USER=paperclip
+      - POSTGRES_PASSWORD=paperclip_secret
+      - POSTGRES_DB=paperclip
+    volumes:
+      - paperclip_postgres_data:/var/lib/postgresql/data
+    ports:
+      - "5433:5432"
+    restart: unless-stopped
+
+  # ──────────────────────────────────────────────
+  # CELERY WORKER (Agent Task Queue)
+  # ──────────────────────────────────────────────
+  celery-worker:
+    build:
+      context: ./backend
+      dockerfile: Dockerfile.dev
+    container_name: canifa_celery_worker
+    command: celery -A celery_app worker --loglevel=info --concurrency=4
+    environment:
+      - CELERY_BROKER_URL=redis://langfuse-redis:6379/1
+      - CELERY_RESULT_BACKEND=redis://langfuse-redis:6379/2
+      - DATABASE_URL=postgresql+asyncpg://paperclip:paperclip_secret@paperclip-postgres:5432/paperclip
+    volumes:
+      - ./backend:/app
+    depends_on:
+      - langfuse-redis
+      - paperclip-postgres
+    restart: unless-stopped
+
 volumes:
   langfuse_postgres_data:
   langfuse_clickhouse_data:
   langfuse_clickhouse_logs:
   langfuse_minio_data:
   langfuse_redis_data:
+  paperclip_postgres_data:

docs/swarm_architecture.md

+# Swarm Architecture: Autonomous Agent-Subagent Swarm for Canifa Company
+
+This document outlines the architectural proposal to evolve Canifa Company's rigid external project orchestrator into a dynamic, self-healing **Autonomous Agent-Subagent Swarm** by leveraging the Hermes Agent core `delegate_task` framework.
+
+---
+
+## 1. Current State vs. Proposed Swarm Architecture
+
+Currently, Canifa Company uses a backend service called `ProjectOrchestrator` to execute code generation stages sequentially:
+
+```mermaid
+graph TD
+    Brief[User Project Brief] --> PM[PM Agent: writes spec.md]
+    PM --> CodeDev[Stage 2: Coder + Designer run in parallel]
+    CodeDev --> QA[QA Agent: runs Playwright tests]
+    QA --> DevOps[DevOps Agent: deploys assets]
+    style Brief fill:#1a1a2e,stroke:#3b5998,stroke-width:2px,color:#fff
+    style PM fill:#2e1a3c,stroke:#8b5cf6,stroke-width:2px,color:#fff
+    style CodeDev fill:#1a3c2e,stroke:#10b981,stroke-width:2px,color:#fff
+    style QA fill:#3c321a,stroke:#f59e0b,stroke-width:2px,color:#fff
+    style DevOps fill:#3c1a1a,stroke:#ef4444,stroke-width:2px,color:#fff
+```
+
+### The Limitations of the Current State
+1. **Rigid Flow**: If the Coder discovers an error or ambiguity in the `spec.md`, it cannot ask the PM to correct it.
+2. **No Bug Feedback Loops**: If the QA agent finds a bug in `index.html`, the execution stops or fails. The QA agent cannot automatically assign a bug-fix task back to the Coder.
+3. **Heavy Orchestrator Code**: A lot of Python and Celery scheduling boilerplate is required to manage state, wait for parallel tasks, and handle exceptions.
+
+---
+
+## 2. The Proposed Autonomous Swarm Model
+
+By exposing the Hermes core `delegate_task` tool to the agents, the swarm organizes itself dynamically. The user interacts with a single **Director Agent (CEO/Orchestrator)**, who manages the team:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as User (Web Dashboard)
+    participant Director as Director Agent (Parent)
+    participant PM as PM Subagent (Depth 1)
+    participant Dev as Coder & Designer (Depth 1 Parallel)
+    participant QA as QA Subagent (Depth 1)
+    
+    User->>Director: "Build a premium dark-mode clothing landing page"
+    Note over Director: Director analyzes brief and plans delegation
+    
+    Director->>PM: delegate_task("Create spec.md for dark-mode theme")
+    PM-->>Director: spec.md created + task summary
+    
+    rect rgb(30, 40, 50)
+        Note over Director, Dev: Parallel execution of dev workers
+        Director->>Dev: delegate_task(tasks=[Coder: "write index.html", Designer: "write styles.css"])
+        Dev-->>Director: Code & styles written + status summary
+    end
+    
+    Director->>QA: delegate_task("Verify layout with Playwright")
+    QA-->>Director: Returns 1 bug: "Hero text color contrast ratio too low"
+    
+    Note over Director: Self-healing feedback loop triggered
+    Director->>Dev: delegate_task("Fix text color contrast ratio in styles.css")
+    Dev-->>Director: Bug fixed
+    
+    Director->>QA: delegate_task("Re-run verification")
+    QA-->>Director: All tests passed (PASS)
+    
+    Director->>User: "Project completed successfully. Here are your assets!"
+```
+
+### Key Advantages of the Swarm Model
+- **Self-Healing Loops**: If a subtask fails, the parent agent detects it and re-delegates it with corrected instructions.
+- **Dynamic Threading**: The parallel execution engine inside `delegate_tool.py` manages threads concurrently, saving token roundtrips and accelerating execution.
+- **Context Isolation**: Workers only get the specific instructions and context they need. Their massive terminal output does not clutter the parent's context window.
+
+---
+
+## 3. Technical Integration Plan
+
+To build this into Canifa Company's platform without losing visual dashboard tracking, we propose the following integration points:
+
+### A. Traceable DB Logs via Event Listeners
+We can connect the progress callback inside `delegate_tool.py` to the company's database using the `ExecutionRunLog` table. This allows the frontend to show a live tree of subagents.
+
+> [!TIP]
+> When `delegate_task` emits events:
+> - `subagent.start`: Write log with `log_type="info"`, storing `subagent_id` and parent relationship in `log_metadata`.
+> - `subagent.tool`: Log every tool executed by the worker (e.g. `read_file`, `write_file`).
+> - `subagent.thinking`: Stream the worker's thought process.
+> - `subagent.complete`: Update status and show final output.
+
+### B. Isolated Sandboxed Workspaces
+To prevent files from overlapping and corrupting each other during parallel runs:
+- We can maintain a `workspaces/{company_id}/{run_id}/` root directory.
+- Each subagent gets its own workspace folder inside `subagents/{subagent_id}/` or shares a `shared/` folder if we configure it to build a shared repository.
+- File tools can be mapped through the `path_security.py` component to keep it safe.
+
+### C. UI Dashboard Visualization
+On the frontend dashboard, we can replace the simple flat terminal logs with an interactive **Swarm Tree**:
+1. A visual node graph or collapsible list showing the Parent (Director) at the top.
+2. Branching nodes showing active parallel Subagents (Coder, Designer) with their status (thinking, running tool, completed, failed).
+3. Clicking on a subagent node displays its private execution logs and terminal output.
+
+---
+
+## 4. Next Steps & Open Questions
+
+Before we write any code, we would love your thoughts on:
+1. **Dynamic vs. Semi-Dynamic**: Do you want the Director Agent to have complete freedom to define any sub-agent goals, or should we restrict delegation to templates (e.g. only delegate to roles defined in our agent database like Coder, PM, QA)?
+2. **UI Preferences**: Should we build a nested swarm hierarchy in the React frontend, or keep a single unified timeline that groups logs by agent name?

docs/swarm_detailed_specification.md

+# Technical Specification: Autonomous Swarm & Subagent Orchestration API
+
+This document provides a detailed specification of the APIs, database metadata schema, and backend execution flow required to integrate the **Autonomous Agent-Subagent Swarm** (powered by Hermes' `delegate_task` engine) into the Canifa Company platform.
+
+---
+
+## 1. Core Features & Execution Logic
+
+### A. The Director Agent (CEO) Flow
+When a user launches a project, instead of waking up agents sequentially via an external orchestrator, the platform wakes up a single **Director Agent**.
+1. **Parsing & Planning**: The Director receives the project brief and dynamically plans the stages.
+2. **Dynamic Delegation**: The Director uses the `delegate_task` tool to spawn subagents.
+3. **Synthesis**: The Director aggregates subagent results, resolves conflicts (e.g. mismatch between HTML and CSS class names), and reports the final output.
+
+### B. Parallel Execution
+When the Director requests parallel work (e.g. Coder and Designer running simultaneously), the backend uses a thread pool to run their conversation loops concurrently. Both subagents read/write to the project's shared repository workspace under `workspaces/{company_id}/{run_id}/`.
+
+### C. Self-Healing & QA Loops
+If the QA subagent detects a test failure (e.g. a broken link or layout overlap), it returns the raw output/screenshot coordinates. The Director Agent intercepts this failure and calls `delegate_task` again, passing the bug report back to the Coder subagent for correction.
+
+```
+[Director]
+   │
+   ├──> Spawns [PM] ──> Returns spec.md
+   │
+   ├──> Spawns [Coder] & [Designer] in Parallel ──> Writes index.html & styles.css
+   │
+   └──> Spawns [QA] ──> Finds Contrast Bug
+         │
+         └──> [Director] re-spawn [Coder] with Contrast Bug context
+               │
+               └──> [Coder] fixes styles.css
+```
+
+---
+
+## 2. Metadata Schema & DB Integration
+
+We leverage the existing `ExecutionRunLog` model. We do not need a database schema migration because the model already contains a `log_metadata` (JSON) field.
+
+### `ExecutionRunLog` (Existing Table)
+- `id` (String, PK)
+- `run_id` (String, FK to HeartbeatRun)
+- `log_type` (String: `stdout`, `stderr`, `info`, `error`)
+- `message` (Text: the log content, thought process, or tool result)
+- `log_metadata` (JSON: used to track hierarchy)
+- `created_at` (DateTime)
+
+### Swarm Log Metadata Payload
+For any log generated by a subagent, the `log_metadata` field will be populated with the following structure:
+```json
+{
+  "subagent_id": "sa-0-f1a2b3c4", 
+  "parent_subagent_id": null,       // Non-null if nested orchestrator spawned it
+  "depth": 1,                       // 1 = first-level child, 2 = grandchild, etc.
+  "goal": "Write styles.css with HSL design tokens",
+  "agent_name": "Designer Agent",
+  "tool_name": "write_file",        // If the log is for a tool execution
+  "status": "running"               // running, completed, failed, interrupted
+}
+```
+If `subagent_id` is missing from `log_metadata`, the log is assumed to belong to the main parent Agent (depth 0).
+
+---
+
+## 3. API Enhancements & Endpoints
+
+### A. Stream logs with Swarm Hierarchy (SSE)
+**GET** `/api/companies/{company_id}/runs/{run_id}/stream`
+
+Returns a Server-Sent Events stream of logs. For subagent logs, the JSON event payload is extended with hierarchical metadata so the UI can indent them.
+
+#### SSE Event Payload:
+```json
+{
+  "id": "log_123456",
+  "run_id": "run_abc123",
+  "log_type": "info",
+  "message": "Tool execution started: write_file styles.css",
+  "created_at": "2026-05-28T22:15:00Z",
+  "subagent_id": "sa-0-f1a2b3c4",
+  "depth": 1,
+  "goal": "Write styles.css with HSL design tokens",
+  "agent_name": "Designer Agent"
+}
+```
+
+### B. List Logs with Filtering
+**GET** `/api/companies/{company_id}/runs/{run_id}/logs`
+
+Allows filtering logs by specific subagents or returning only parent logs.
+
+#### Query Parameters:
+- `subagent_id` (Optional, string): Filter logs to a specific worker.
+- `max_depth` (Optional, int): Only return logs up to a certain hierarchy depth.
+
+### C. Swarm Execution Tree (NEW)
+**GET** `/api/companies/{company_id}/runs/{run_id}/tree`
+
+Returns the hierarchical execution tree of the swarm to let the UI render a visual tree map of the agents.
+
+#### Response:
+```json
+{
+  "run_id": "run_abc123",
+  "status": "running",
+  "agent_id": "agent_ceo",
+  "agent_name": "CEO Director",
+  "started_at": "2026-05-28T22:10:00Z",
+  "subagents": [
+    {
+      "subagent_id": "sa-0-f1a2b3c4",
+      "parent_id": null,
+      "agent_name": "Designer Agent",
+      "goal": "Write styles.css with HSL design tokens",
+      "status": "completed",
+      "tool_count": 4,
+      "started_at": "2026-05-28T22:11:00Z",
+      "subagents": []
+    },
+    {
+      "subagent_id": "sa-1-e5f6g7h8",
+      "parent_id": null,
+      "agent_name": "Coder Agent",
+      "goal": "Write HTML and structure pages",
+      "status": "running",
+      "tool_count": 8,
+      "started_at": "2026-05-28T22:11:00Z",
+      "subagents": []
+    }
+  ]
+}
+```
+
+---
+
+## 4. Execution Sandbox & Workspace Structure
+
+When subagents are created, they execute inside the same project context to collaborate on files. The folder layout is organized as follows:
+
+```
+workspaces/{company_id}/{run_id}/
+├── .git/                      <-- Project repository
+├── index.html                 <-- Shared codebase
+├── styles.css                 
+├── spec.md                    
+├── qa_report.txt              
+└── subagents/
+    ├── sa-0-f1a2b3c4/         <-- Temp directory for Designer Agent
+    └── sa-1-e5f6g7h8/         <-- Temp directory for Coder Agent
+```
+
+1. **Shared Access**: The subagents execute file tools (`read_file`, `write_file`) relative to the root of the run workspace `workspaces/{company_id}/{run_id}/`.
+2. **Isolated Commands**: When executing terminal commands (`terminal`), subagents run commands inside their respective temporary subagent folders (`subagents/{subagent_id}/`) to ensure shell processes do not overlap or interfere.

docs/swarm_implementation_plan.md

+# Implementation Plan: Autonomous Swarm & Subagent Orchestration
+
+This plan outlines the steps to implement the **Autonomous Swarm & Subagent Orchestration** using the Hermes `delegate_task` core. This will replace the rigid, static orchestrator with a dynamic, self-healing team structure.
+
+## Proposed Changes
+
+We will modify/create the following backend components to support swarm orchestration:
+
+### 1. Agent Runner & DB Log Integration
+
+#### [MODIFY] [agents.py](file:///d:/a/ai_canifa_company/backend/api/routes/agents.py)
+- Wire the subagent progress callback into `run_agent_in_background`.
+- Create a `SwarmLogWriter` class that receives callbacks from the child agents (such as `subagent.start`, `subagent.thinking`, `subagent.tool`, `subagent.complete`) and writes them directly to `ExecutionRunLog` table using `get_db_context()`.
+
+### 2. API Endpoint Upgrades
+
+#### [MODIFY] [run_logs.py](file:///d:/a/ai_canifa_company/backend/api/routes/run_logs.py)
+- **Log Stream (`/stream`)**: Update the SSE endpoint to yield subagent info (`subagent_id`, `depth`, `goal`, `agent_name`) from the `log_metadata` field.
+- **Swarm Tree (`/tree`) [NEW]**: Implement a GET endpoint to return a tree of the executing swarm (which subagents have run under this run, their status, goals, and duration).
+
+### 3. Subagent Sandbox Isolation
+
+#### [MODIFY] [delegate_tool.py](file:///d:/a/ai_canifa_company/backend/agent/tools/delegate_tool.py)
+- Ensure child workspace directory defaults to `workspaces/{company_id}/{run_id}/` (shared repository root) so file tools read/write to the correct repository path, while terminal execution is isolated.
+
+---
+
+## Verification Plan
+
+### Automated Tests
+- Create a test script `scratch/test_swarm_orchestration.py` to trigger a simulated run with a mocked subagent call.
+- Verify `ExecutionRunLog` contains records with `log_metadata` populated with `subagent_id`, `goal`, and `depth`.
+- Test the `/tree` and `/stream` endpoints using a mock DB session.
+
+### Manual Verification
+- Run the FastAPI server and trigger a wakeup event.
+- Inspect logs via `/api/companies/{company_id}/runs/{run_id}/tree` to confirm the hierarchy is correct.

docs/swarm_walkthrough.md

+# Walkthrough: Autonomous Swarm & Subagent Orchestration
+
+This walkthrough summarizes the implementation of the **Autonomous Swarm & Subagent Orchestration** (powered by Hermes' `delegate_task` engine) inside the Canifa Company platform.
+
+---
+
+## 1. Accomplishments & Architecture
+
+We successfully migrated the static, sequential agent execution model into a dynamic, self-healing **Swarm Orchestration** system. 
+
+```mermaid
+graph TD
+    Director[CEO / Director Agent] -->|delegate_task| PM[PM Subagent]
+    Director -->|delegate_task| Coder[Coder Subagent]
+    Director -->|delegate_task| Designer[Designer Subagent]
+    Director -->|delegate_task| QA[QA Subagent]
+
+    PM -.->|Write spec.md| SharedWS[(Shared Workspace)]
+    Coder -.->|Write index.html| SharedWS
+    Designer -.->|Write styles.css| SharedWS
+    QA -.->|Run tests| SharedWS
+
+    subgraph Workspace Security
+        SharedWS
+        subagents[subagents/ Directory]
+        subagents --> sa1[sa-0-pm/]
+        subagents --> sa2[sa-1-coder/]
+        subagents --> sa3[sa-2-designer/]
+    end
+```
+
+### Key Technical Enhancements:
+1. **Dynamic Swarm Log Writer (`AgentLogWriter`)**:
+   - Implemented thread-safe synchronous-to-asynchronous event bridging using `asyncio.run_coroutine_threadsafe` and event loop scheduling.
+   - Listens to child subagent progress events (`subagent.start`, `subagent.complete`, `tool.started`, `tool.completed`, etc.) and automatically parses and stores them in the database.
+   - Automatically derives friendly subagent names (e.g. `PM Agent`, `Designer Agent`, `Coder Agent`, `QA Agent`) from their task goals.
+2. **FastAPI Route Upgrades (`run_logs.py`)**:
+   - **`/stream`**: Extended SSE log stream to promote subagent hierarchy details (`subagent_id`, `depth`, `goal`, `agent_name`) to the root of the JSON event payload.
+   - **`/tree` (NEW)**: Added an endpoint to dynamically reconstruct the executing swarm tree from log metadata rows.
+   - **`/logs` (NEW)**: Added a filtered logs endpoint supporting filtering by `subagent_id` and `max_depth`.
+3. **Workspace Path Isolation (`delegate_tool.py`)**:
+   - Integrated `os.getenv("AGENT_WORKSPACE")` as the primary workspace hint for subagents.
+   - Leveraged `register_task_env_overrides` so that subagents write to the shared project repository (`workspaces/{company_id}/{run_id}/`) but execute terminal commands safely inside isolated directories (`subagents/{subagent_id}/`).
+4. **FastAPI & ORM Serialization Fixes**:
+   - Mapped database objects to dictionary payloads prior to validation with Pydantic schemas, successfully bypassing a collision between Pydantic's `metadata` alias and SQLAlchemy's `MetaData` class.
+
+---
+
+## 2. Verification Results
+
+All tests were verified E2E via a custom scratch script:
+[test_swarm_orchestration.py](file:///d:/a/ai_canifa_company/backend/scratch/test_swarm_orchestration.py)
+
+```bash
+backend\.venv\Scripts\python.exe backend\scratch\test_swarm_orchestration.py
+```
+
+### Test Logs:
+```
+Initializing test database...
+Creating mock company run: company_id=test-comp-45c5ae, run_id=run-test-5fd059
+Instantiating AgentLogWriter...
+Firing subagent progress callbacks...
+Waiting for database writes to settle...
+Verifying log entries in DB...
+Total logs written to DB: 9
+Total subagent logs: 8
+Log type: info | Msg: Tool completed: write_file | Meta: {'subagent_id': 'sa-0-pm', ...}
+...
+Verifying Swarm Tree endpoint...
+Generated Swarm Tree:
+{
+  "run_id": "run-test-5fd059",
+  "status": "running",
+  "agent_id": "agent_pm",
+  "agent_name": "CEO Director",
+  "started_at": "2026-05-28T15:23:55.903094",
+  "subagents": [
+    {
+      "subagent_id": "sa-0-pm",
+      "parent_id": null,
+      "agent_name": "PM Agent",
+      "goal": "Analyze requirements and build spec.md",
+      "status": "completed",
+      "tool_count": 1,
+      "started_at": "2026-05-28T15:23:55.953025",
+      "subagents": [
+        {
+          "subagent_id": "sa-1-coder",
+          "parent_id": "sa-0-pm",
+          "agent_name": "Coder Agent",
+          "goal": "Implement index.html and layouts",
+          "status": "completed",
+          "tool_count": 1,
+          "started_at": "2026-05-28T15:23:55.957025",
+          "subagents": []
+        }
+      ]
+    }
+  ]
+}
+Verifying Logs Filtering endpoint...
+PM subagent logs count: 4
+Coder subagent logs count: 4
+Logs at max_depth=1: 5
+ALL SWARM ORCHESTRATION TESTS PASSED SUCCESSFULLY!
+```
+
+---
+
+## 3. Implemented Files
+
+The following files have been created or modified:
+
+| Component | File | Description |
+|---|---|---|
+| **Logging Callback** | [agent_log_writer.py](file:///d:/a/ai_canifa_company/backend/services/agent_log_writer.py) | Added loop capturing, thread-safe sync-async writes, and `on_subagent_progress` callback. |
+| **Agent Setup** | [agents.py](file:///d:/a/ai_canifa_company/backend/api/routes/agents.py) | Configured parent agent instantiation with `tool_progress_callback` instead of separate event hooks. |
+| **Worker Tasks** | [agent_tasks.py](file:///d:/a/ai_canifa_company/backend/tasks/agent_tasks.py) | Integrated `tool_progress_callback` in background Celery worker tasks. |
+| **APIs / Router** | [run_logs.py](file:///d:/a/ai_canifa_company/backend/api/routes/run_logs.py) | Promoted subagent details in `/stream` (SSE), added `/tree`, added `/logs` (filtered), fixed Pydantic metadata aliases. |
+| **Workspace & Terminal** | [delegate_tool.py](file:///d:/a/ai_canifa_company/backend/agent/tools/delegate_tool.py) | Added `AGENT_WORKSPACE` resolving to prompt, and set workspace directory override logic per subagent execution. |
+| **Documentation** | [swarm_architecture.md](file:///d:/a/ai_canifa_company/docs/swarm_architecture.md) | Markdown design docs and sequence diagrams. |
+| **Documentation** | [swarm_detailed_specification.md](file:///d:/a/ai_canifa_company/docs/swarm_detailed_specification.md) | Backend schema structures and REST contracts. |
+| **Documentation** | [swarm_implementation_plan.md](file:///d:/a/ai_canifa_company/docs/swarm_implementation_plan.md) | Step-by-step development roadmap. |
+| **E2E verification** | [test_swarm_orchestration.py](file:///d:/a/ai_canifa_company/backend/scratch/test_swarm_orchestration.py) | Mock simulation script. |

docx/agent_creation_flows.md

+# Agent Creation Workflows: AI-Assisted vs. Manual Configuration
+
+This document specifies the two primary agent-creation workflows available in the Canifa Company platform: **AI-Assisted (CEO delegated)** and **Manual User Configuration (Advanced)**.
+
+---
+
+## 1. Flow A: AI-Assisted Agent Creation (CEO Delegated)
+
+In the AI-Assisted flow, users leverage their high-level **CEO Director Agent** to design and hire specialized subagents. This minimizes manual effort and ensures the new agent fits into the existing organizational tree.
+
+### Execution Sequence
+1. **User Request**: The user opens the **Add Agent** sidebar dialog and selects **"Ask the CEO to create a new agent"**.
+2. **Issue Assignment**: The system registers a new Issue assigned to the CEO Agent (`role="ceo"`):
+   - **Title**: `Create a new agent`
+   - **Description**: The user-supplied description (e.g., *"Create a Designer Agent to build styled CSS landing pages"*).
+3. **CEO Planning**: The CEO Agent analyzes the issue, determines the optimal profile for the new agent, and specifies:
+   - Name and Title (e.g. `HSL UI Designer`)
+   - Role (e.g. `designer` or `coder`)
+   - Required skills (e.g. `figma`, `css`, `design-system`)
+   - Manager relationship (`reports_to` foreign key pointing back to `agent_ceo`)
+4. **Agent Registry**: The CEO Agent invokes the agent registry tool (or triggers a background script) to write the new agent record directly to the database.
+
+---
+
+## 2. Flow B: Manual User Configuration (Advanced)
+
+For granular control, users can choose **"I want advanced configuration myself"** to configure all fields and adapter parameters manually.
+
+### Configurable Parameters
+- **Basic Info**: Name and Job Title.
+- **Reporting Line**: The manager the agent reports to (using the `ReportsToPicker` component mapped to the database `reports_to` column).
+- **Role Type**: Selected from a dropdown (`ceo`, `pm`, `designer`, `coder`, `qa`, etc.).
+- **Adapter Type & Model**: Choose the LLM provider (OpenAI, Claude, custom, etc.) and model profile.
+- **Skills**: Checkboxes corresponding to the optional skills installed in the company's library.
+
+---
+
+## 3. Backend Endpoint: `POST /api/companies/{company_id}/agent-hires`
+
+To support both manual hiring from the UI and programmatically by the CEO agent, we implemented a dedicated agent-hires API:
+
+- **Path**: `/api/companies/{company_id}/agent-hires` (rewritten via path-conversion middleware to `/api/agent-hires`)
+- **Method**: `POST`
+- **Request Schema**:
+```json
+{
+  "name": "Senior Frontend Coder",
+  "role": "coder",
+  "title": "Senior Frontend Developer",
+  "reportsTo": "agent_ceo",
+  "desiredSkills": ["html-css", "javascript", "responsive-design"],
+  "adapterType": "openai",
+  "defaultEnvironmentId": null,
+  "adapterConfig": {
+    "model": "gpt-4o-mini"
+  },
+  "runtimeConfig": {
+    "heartbeatEnabled": true
+  },
+  "budgetMonthlyCents": 0
+}
+```
+
+- **Response Schema**:
+```json
+{
+  "agent": {
+    "id": "45ef627f4b924239bb40f1943034e718",
+    "companyId": "company_123",
+    "name": "Senior Frontend Coder",
+    "role": "coder",
+    "title": "Senior Frontend Developer",
+    "icon": "",
+    "status": "active",
+    "reportsTo": "agent_ceo",
+    "capabilities": ["html-css", "javascript", "responsive-design"],
+    "adapterType": "openai",
+    "adapterConfig": {
+      "model": "gpt-4o-mini"
+    },
+    "runtimeConfig": {
+      "heartbeatEnabled": true
+    },
+    "budgetMonthlyCents": 0,
+    "createdAt": "2026-05-28T15:38:42Z",
+    "updatedAt": "2026-05-28T15:38:42Z"
+  },
+  "approval": null
+}
+```
+
+---
+
+## 4. E2E Verification Results
+
+We verified both flows E2E using the simulation script:
+[demo_both_agent_creation_flows.py](file:///d:/a/ai_canifa_company/backend/scratch/demo_both_agent_creation_flows.py)
+
+```
+--- RUNNING FLOW A: AI (CEO Agent) Generated Agent ---
+User Request to CEO Agent: 'Create a designer agent named UI Designer to design a dark mode theme with HSL variables.'
+CEO Agent plans the agent structure...
+CEO Agent executing creation tool for: HSL UI Designer (UI/UX Design Specialist) reporting to agent_ceo
+SUCCESS: CEO Agent successfully created Designer Agent 'HSL UI Designer' (ID: agent_designer_827c8fe0) reporting to agent_ceo!
+
+--- RUNNING FLOW B: Manual User Configuration via Endpoint ---
+Submitting POST request to /api/agent-hires for manual Coder Agent: 'Senior Frontend Coder'...
+SUCCESS: Endpoint returned 201 Created!
+
+--- VERIFYING ORG CHART HIERARCHY ---
+Final Org Chart:
+CEO Director (Chief Executive Officer) [CEO]
+  |-- HSL UI Designer (UI/UX Design Specialist) [DESIGNER]
+  |-- Senior Frontend Coder (Senior Frontend Developer) [CODER]
+```
+ Both the manual config form and the AI-generated delegation successfully register hierarchical relationships in the database, allowing the Org Chart page to render their tree structures correctly.

docx/swarm_architecture.md

+# Swarm Architecture: Autonomous Agent-Subagent Swarm for Canifa Company
+
+This document outlines the architectural proposal to evolve Canifa Company's rigid external project orchestrator into a dynamic, self-healing **Autonomous Agent-Subagent Swarm** by leveraging the Hermes Agent core `delegate_task` framework.
+
+---
+
+## 1. Current State vs. Proposed Swarm Architecture
+
+Currently, Canifa Company uses a backend service called `ProjectOrchestrator` to execute code generation stages sequentially:
+
+```mermaid
+graph TD
+    Brief[User Project Brief] --> PM[PM Agent: writes spec.md]
+    PM --> CodeDev[Stage 2: Coder + Designer run in parallel]
+    CodeDev --> QA[QA Agent: runs Playwright tests]
+    QA --> DevOps[DevOps Agent: deploys assets]
+    style Brief fill:#1a1a2e,stroke:#3b5998,stroke-width:2px,color:#fff
+    style PM fill:#2e1a3c,stroke:#8b5cf6,stroke-width:2px,color:#fff
+    style CodeDev fill:#1a3c2e,stroke:#10b981,stroke-width:2px,color:#fff
+    style QA fill:#3c321a,stroke:#f59e0b,stroke-width:2px,color:#fff
+    style DevOps fill:#3c1a1a,stroke:#ef4444,stroke-width:2px,color:#fff
+```
+
+### The Limitations of the Current State
+1. **Rigid Flow**: If the Coder discovers an error or ambiguity in the `spec.md`, it cannot ask the PM to correct it.
+2. **No Bug Feedback Loops**: If the QA agent finds a bug in `index.html`, the execution stops or fails. The QA agent cannot automatically assign a bug-fix task back to the Coder.
+3. **Heavy Orchestrator Code**: A lot of Python and Celery scheduling boilerplate is required to manage state, wait for parallel tasks, and handle exceptions.
+
+---
+
+## 2. The Proposed Autonomous Swarm Model
+
+By exposing the Hermes core `delegate_task` tool to the agents, the swarm organizes itself dynamically. The user interacts with a single **Director Agent (CEO/Orchestrator)**, who manages the team:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as User (Web Dashboard)
+    participant Director as Director Agent (Parent)
+    participant PM as PM Subagent (Depth 1)
+    participant Dev as Coder & Designer (Depth 1 Parallel)
+    participant QA as QA Subagent (Depth 1)
+    
+    User->>Director: "Build a premium dark-mode clothing landing page"
+    Note over Director: Director analyzes brief and plans delegation
+    
+    Director->>PM: delegate_task("Create spec.md for dark-mode theme")
+    PM-->>Director: spec.md created + task summary
+    
+    rect rgb(30, 40, 50)
+        Note over Director, Dev: Parallel execution of dev workers
+        Director->>Dev: delegate_task(tasks=[Coder: "write index.html", Designer: "write styles.css"])
+        Dev-->>Director: Code & styles written + status summary
+    end
+    
+    Director->>QA: delegate_task("Verify layout with Playwright")
+    QA-->>Director: Returns 1 bug: "Hero text color contrast ratio too low"
+    
+    Note over Director: Self-healing feedback loop triggered
+    Director->>Dev: delegate_task("Fix text color contrast ratio in styles.css")
+    Dev-->>Director: Bug fixed
+    
+    Director->>QA: delegate_task("Re-run verification")
+    QA-->>Director: All tests passed (PASS)
+    
+    Director->>User: "Project completed successfully. Here are your assets!"
+```
+
+### Key Advantages of the Swarm Model
+- **Self-Healing Loops**: If a subtask fails, the parent agent detects it and re-delegates it with corrected instructions.
+- **Dynamic Threading**: The parallel execution engine inside `delegate_tool.py` manages threads concurrently, saving token roundtrips and accelerating execution.
+- **Context Isolation**: Workers only get the specific instructions and context they need. Their massive terminal output does not clutter the parent's context window.
+
+---
+
+## 3. Technical Integration Plan
+
+To build this into Canifa Company's platform without losing visual dashboard tracking, we propose the following integration points:
+
+### A. Traceable DB Logs via Event Listeners
+We can connect the progress callback inside `delegate_tool.py` to the company's database using the `ExecutionRunLog` table. This allows the frontend to show a live tree of subagents.
+
+> [!TIP]
+> When `delegate_task` emits events:
+> - `subagent.start`: Write log with `log_type="info"`, storing `subagent_id` and parent relationship in `log_metadata`.
+> - `subagent.tool`: Log every tool executed by the worker (e.g. `read_file`, `write_file`).
+> - `subagent.thinking`: Stream the worker's thought process.
+> - `subagent.complete`: Update status and show final output.
+
+### B. Isolated Sandboxed Workspaces
+To prevent files from overlapping and corrupting each other during parallel runs:
+- We can maintain a `workspaces/{company_id}/{run_id}/` root directory.
+- Each subagent gets its own workspace folder inside `subagents/{subagent_id}/` or shares a `shared/` folder if we configure it to build a shared repository.
+- File tools can be mapped through the `path_security.py` component to keep it safe.
+
+### C. UI Dashboard Visualization
+On the frontend dashboard, we can replace the simple flat terminal logs with an interactive **Swarm Tree**:
+1. A visual node graph or collapsible list showing the Parent (Director) at the top.
+2. Branching nodes showing active parallel Subagents (Coder, Designer) with their status (thinking, running tool, completed, failed).
+3. Clicking on a subagent node displays its private execution logs and terminal output.
+
+---
+
+## 4. Next Steps & Open Questions
+
+Before we write any code, we would love your thoughts on:
+1. **Dynamic vs. Semi-Dynamic**: Do you want the Director Agent to have complete freedom to define any sub-agent goals, or should we restrict delegation to templates (e.g. only delegate to roles defined in our agent database like Coder, PM, QA)?
+2. **UI Preferences**: Should we build a nested swarm hierarchy in the React frontend, or keep a single unified timeline that groups logs by agent name?

docx/swarm_detailed_specification.md

+# Technical Specification: Autonomous Swarm & Subagent Orchestration API
+
+This document provides a detailed specification of the APIs, database metadata schema, and backend execution flow required to integrate the **Autonomous Agent-Subagent Swarm** (powered by Hermes' `delegate_task` engine) into the Canifa Company platform.
+
+---
+
+## 1. Core Features & Execution Logic
+
+### A. The Director Agent (CEO) Flow
+When a user launches a project, instead of waking up agents sequentially via an external orchestrator, the platform wakes up a single **Director Agent**.
+1. **Parsing & Planning**: The Director receives the project brief and dynamically plans the stages.
+2. **Dynamic Delegation**: The Director uses the `delegate_task` tool to spawn subagents.
+3. **Synthesis**: The Director aggregates subagent results, resolves conflicts (e.g. mismatch between HTML and CSS class names), and reports the final output.
+
+### B. Parallel Execution
+When the Director requests parallel work (e.g. Coder and Designer running simultaneously), the backend uses a thread pool to run their conversation loops concurrently. Both subagents read/write to the project's shared repository workspace under `workspaces/{company_id}/{run_id}/`.
+
+### C. Self-Healing & QA Loops
+If the QA subagent detects a test failure (e.g. a broken link or layout overlap), it returns the raw output/screenshot coordinates. The Director Agent intercepts this failure and calls `delegate_task` again, passing the bug report back to the Coder subagent for correction.
+
+```
+[Director]
+   │
+   ├──> Spawns [PM] ──> Returns spec.md
+   │
+   ├──> Spawns [Coder] & [Designer] in Parallel ──> Writes index.html & styles.css
+   │
+   └──> Spawns [QA] ──> Finds Contrast Bug
+         │
+         └──> [Director] re-spawn [Coder] with Contrast Bug context
+               │
+               └──> [Coder] fixes styles.css
+```
+
+---
+
+## 2. Metadata Schema & DB Integration
+
+We leverage the existing `ExecutionRunLog` model. We do not need a database schema migration because the model already contains a `log_metadata` (JSON) field.
+
+### `ExecutionRunLog` (Existing Table)
+- `id` (String, PK)
+- `run_id` (String, FK to HeartbeatRun)
+- `log_type` (String: `stdout`, `stderr`, `info`, `error`)
+- `message` (Text: the log content, thought process, or tool result)
+- `log_metadata` (JSON: used to track hierarchy)
+- `created_at` (DateTime)
+
+### Swarm Log Metadata Payload
+For any log generated by a subagent, the `log_metadata` field will be populated with the following structure:
+```json
+{
+  "subagent_id": "sa-0-f1a2b3c4", 
+  "parent_subagent_id": null,       // Non-null if nested orchestrator spawned it
+  "depth": 1,                       // 1 = first-level child, 2 = grandchild, etc.
+  "goal": "Write styles.css with HSL design tokens",
+  "agent_name": "Designer Agent",
+  "tool_name": "write_file",        // If the log is for a tool execution
+  "status": "running"               // running, completed, failed, interrupted
+}
+```
+If `subagent_id` is missing from `log_metadata`, the log is assumed to belong to the main parent Agent (depth 0).
+
+---
+
+## 3. API Enhancements & Endpoints
+
+### A. Stream logs with Swarm Hierarchy (SSE)
+**GET** `/api/companies/{company_id}/runs/{run_id}/stream`
+
+Returns a Server-Sent Events stream of logs. For subagent logs, the JSON event payload is extended with hierarchical metadata so the UI can indent them.
+
+#### SSE Event Payload:
+```json
+{
+  "id": "log_123456",
+  "run_id": "run_abc123",
+  "log_type": "info",
+  "message": "Tool execution started: write_file styles.css",
+  "created_at": "2026-05-28T22:15:00Z",
+  "subagent_id": "sa-0-f1a2b3c4",
+  "depth": 1,
+  "goal": "Write styles.css with HSL design tokens",
+  "agent_name": "Designer Agent"
+}
+```
+
+### B. List Logs with Filtering
+**GET** `/api/companies/{company_id}/runs/{run_id}/logs`
+
+Allows filtering logs by specific subagents or returning only parent logs.
+
+#### Query Parameters:
+- `subagent_id` (Optional, string): Filter logs to a specific worker.
+- `max_depth` (Optional, int): Only return logs up to a certain hierarchy depth.
+
+### C. Swarm Execution Tree (NEW)
+**GET** `/api/companies/{company_id}/runs/{run_id}/tree`
+
+Returns the hierarchical execution tree of the swarm to let the UI render a visual tree map of the agents.
+
+#### Response:
+```json
+{
+  "run_id": "run_abc123",
+  "status": "running",
+  "agent_id": "agent_ceo",
+  "agent_name": "CEO Director",
+  "started_at": "2026-05-28T22:10:00Z",
+  "subagents": [
+    {
+      "subagent_id": "sa-0-f1a2b3c4",
+      "parent_id": null,
+      "agent_name": "Designer Agent",
+      "goal": "Write styles.css with HSL design tokens",
+      "status": "completed",
+      "tool_count": 4,
+      "started_at": "2026-05-28T22:11:00Z",
+      "subagents": []
+    },
+    {
+      "subagent_id": "sa-1-e5f6g7h8",
+      "parent_id": null,
+      "agent_name": "Coder Agent",
+      "goal": "Write HTML and structure pages",
+      "status": "running",
+      "tool_count": 8,
+      "started_at": "2026-05-28T22:11:00Z",
+      "subagents": []
+    }
+  ]
+}
+```
+
+---
+
+## 4. Execution Sandbox & Workspace Structure
+
+When subagents are created, they execute inside the same project context to collaborate on files. The folder layout is organized as follows:
+
+```
+workspaces/{company_id}/{run_id}/
+├── .git/                      <-- Project repository
+├── index.html                 <-- Shared codebase
+├── styles.css                 
+├── spec.md                    
+├── qa_report.txt              
+└── subagents/
+    ├── sa-0-f1a2b3c4/         <-- Temp directory for Designer Agent
+    └── sa-1-e5f6g7h8/         <-- Temp directory for Coder Agent
+```
+
+1. **Shared Access**: The subagents execute file tools (`read_file`, `write_file`) relative to the root of the run workspace `workspaces/{company_id}/{run_id}/`.
+2. **Isolated Commands**: When executing terminal commands (`terminal`), subagents run commands inside their respective temporary subagent folders (`subagents/{subagent_id}/`) to ensure shell processes do not overlap or interfere.

docx/swarm_implementation_plan.md

+# Implementation Plan: Autonomous Swarm & Subagent Orchestration
+
+This plan outlines the steps to implement the **Autonomous Swarm & Subagent Orchestration** using the Hermes `delegate_task` core. This will replace the rigid, static orchestrator with a dynamic, self-healing team structure.
+
+## Proposed Changes
+
+We will modify/create the following backend components to support swarm orchestration:
+
+### 1. Agent Runner & DB Log Integration
+
+#### [MODIFY] [agents.py](file:///d:/a/ai_canifa_company/backend/api/routes/agents.py)
+- Wire the subagent progress callback into `run_agent_in_background`.
+- Create a `SwarmLogWriter` class that receives callbacks from the child agents (such as `subagent.start`, `subagent.thinking`, `subagent.tool`, `subagent.complete`) and writes them directly to `ExecutionRunLog` table using `get_db_context()`.
+
+### 2. API Endpoint Upgrades
+
+#### [MODIFY] [run_logs.py](file:///d:/a/ai_canifa_company/backend/api/routes/run_logs.py)
+- **Log Stream (`/stream`)**: Update the SSE endpoint to yield subagent info (`subagent_id`, `depth`, `goal`, `agent_name`) from the `log_metadata` field.
+- **Swarm Tree (`/tree`) [NEW]**: Implement a GET endpoint to return a tree of the executing swarm (which subagents have run under this run, their status, goals, and duration).
+
+### 3. Subagent Sandbox Isolation
+
+#### [MODIFY] [delegate_tool.py](file:///d:/a/ai_canifa_company/backend/agent/tools/delegate_tool.py)
+- Ensure child workspace directory defaults to `workspaces/{company_id}/{run_id}/` (shared repository root) so file tools read/write to the correct repository path, while terminal execution is isolated.
+
+---
+
+## Verification Plan
+
+### Automated Tests
+- Create a test script `scratch/test_swarm_orchestration.py` to trigger a simulated run with a mocked subagent call.
+- Verify `ExecutionRunLog` contains records with `log_metadata` populated with `subagent_id`, `goal`, and `depth`.
+- Test the `/tree` and `/stream` endpoints using a mock DB session.
+
+### Manual Verification
+- Run the FastAPI server and trigger a wakeup event.
+- Inspect logs via `/api/companies/{company_id}/runs/{run_id}/tree` to confirm the hierarchy is correct.

docx/swarm_walkthrough.md

+# Walkthrough: Autonomous Swarm & Subagent Orchestration
+
+This walkthrough summarizes the implementation of the **Autonomous Swarm & Subagent Orchestration** (powered by Hermes' `delegate_task` engine) inside the Canifa Company platform.
+
+---
+
+## 1. Accomplishments & Architecture
+
+We successfully migrated the static, sequential agent execution model into a dynamic, self-healing **Swarm Orchestration** system. 
+
+```mermaid
+graph TD
+    Director[CEO / Director Agent] -->|delegate_task| PM[PM Subagent]
+    Director -->|delegate_task| Coder[Coder Subagent]
+    Director -->|delegate_task| Designer[Designer Subagent]
+    Director -->|delegate_task| QA[QA Subagent]
+
+    PM -.->|Write spec.md| SharedWS[(Shared Workspace)]
+    Coder -.->|Write index.html| SharedWS
+    Designer -.->|Write styles.css| SharedWS
+    QA -.->|Run tests| SharedWS
+
+    subgraph Workspace Security
+        SharedWS
+        subagents[subagents/ Directory]
+        subagents --> sa1[sa-0-pm/]
+        subagents --> sa2[sa-1-coder/]
+        subagents --> sa3[sa-2-designer/]
+    end
+```
+
+### Key Technical Enhancements:
+1. **Dynamic Swarm Log Writer (`AgentLogWriter`)**:
+   - Implemented thread-safe synchronous-to-asynchronous event bridging using `asyncio.run_coroutine_threadsafe` and event loop scheduling.
+   - Listens to child subagent progress events (`subagent.start`, `subagent.complete`, `tool.started`, `tool.completed`, etc.) and automatically parses and stores them in the database.
+   - Automatically derives friendly subagent names (e.g. `PM Agent`, `Designer Agent`, `Coder Agent`, `QA Agent`) from their task goals.
+2. **FastAPI Route Upgrades (`run_logs.py`)**:
+   - **`/stream`**: Extended SSE log stream to promote subagent hierarchy details (`subagent_id`, `depth`, `goal`, `agent_name`) to the root of the JSON event payload.
+   - **`/tree` (NEW)**: Added an endpoint to dynamically reconstruct the executing swarm tree from log metadata rows.
+   - **`/logs` (NEW)**: Added a filtered logs endpoint supporting filtering by `subagent_id` and `max_depth`.
+3. **Workspace Path Isolation (`delegate_tool.py`)**:
+   - Integrated `os.getenv("AGENT_WORKSPACE")` as the primary workspace hint for subagents.
+   - Leveraged `register_task_env_overrides` so that subagents write to the shared project repository (`workspaces/{company_id}/{run_id}/`) but execute terminal commands safely inside isolated directories (`subagents/{subagent_id}/`).
+4. **FastAPI & ORM Serialization Fixes**:
+   - Mapped database objects to dictionary payloads prior to validation with Pydantic schemas, successfully bypassing a collision between Pydantic's `metadata` alias and SQLAlchemy's `MetaData` class.
+
+---
+
+## 2. Verification Results
+
+All tests were verified E2E via a custom scratch script:
+[test_swarm_orchestration.py](file:///d:/a/ai_canifa_company/backend/scratch/test_swarm_orchestration.py)
+
+```bash
+backend\.venv\Scripts\python.exe backend\scratch\test_swarm_orchestration.py
+```
+
+### Test Logs:
+```
+Initializing test database...
+Creating mock company run: company_id=test-comp-45c5ae, run_id=run-test-5fd059
+Instantiating AgentLogWriter...
+Firing subagent progress callbacks...
+Waiting for database writes to settle...
+Verifying log entries in DB...
+Total logs written to DB: 9
+Total subagent logs: 8
+Log type: info | Msg: Tool completed: write_file | Meta: {'subagent_id': 'sa-0-pm', ...}
+...
+Verifying Swarm Tree endpoint...
+Generated Swarm Tree:
+{
+  "run_id": "run-test-5fd059",
+  "status": "running",
+  "agent_id": "agent_pm",
+  "agent_name": "CEO Director",
+  "started_at": "2026-05-28T15:23:55.903094",
+  "subagents": [
+    {
+      "subagent_id": "sa-0-pm",
+      "parent_id": null,
+      "agent_name": "PM Agent",
+      "goal": "Analyze requirements and build spec.md",
+      "status": "completed",
+      "tool_count": 1,
+      "started_at": "2026-05-28T15:23:55.953025",
+      "subagents": [
+        {
+          "subagent_id": "sa-1-coder",
+          "parent_id": "sa-0-pm",
+          "agent_name": "Coder Agent",
+          "goal": "Implement index.html and layouts",
+          "status": "completed",
+          "tool_count": 1,
+          "started_at": "2026-05-28T15:23:55.957025",
+          "subagents": []
+        }
+      ]
+    }
+  ]
+}
+Verifying Logs Filtering endpoint...
+PM subagent logs count: 4
+Coder subagent logs count: 4
+Logs at max_depth=1: 5
+ALL SWARM ORCHESTRATION TESTS PASSED SUCCESSFULLY!
+```
+
+---
+
+## 3. Implemented Files
+
+The following files have been created or modified:
+
+| Component | File | Description |
+|---|---|---|
+| **Logging Callback** | [agent_log_writer.py](file:///d:/a/ai_canifa_company/backend/services/agent_log_writer.py) | Added loop capturing, thread-safe sync-async writes, and `on_subagent_progress` callback. |
+| **Agent Setup** | [agents.py](file:///d:/a/ai_canifa_company/backend/api/routes/agents.py) | Configured parent agent instantiation with `tool_progress_callback` instead of separate event hooks. |
+| **Worker Tasks** | [agent_tasks.py](file:///d:/a/ai_canifa_company/backend/tasks/agent_tasks.py) | Integrated `tool_progress_callback` in background Celery worker tasks. |
+| **APIs / Router** | [run_logs.py](file:///d:/a/ai_canifa_company/backend/api/routes/run_logs.py) | Promoted subagent details in `/stream` (SSE), added `/tree`, added `/logs` (filtered), fixed Pydantic metadata aliases. |
+| **Workspace & Terminal** | [delegate_tool.py](file:///d:/a/ai_canifa_company/backend/agent/tools/delegate_tool.py) | Added `AGENT_WORKSPACE` resolving to prompt, and set workspace directory override logic per subagent execution. |
+| **Documentation** | [swarm_architecture.md](file:///d:/a/ai_canifa_company/docs/swarm_architecture.md) | Markdown design docs and sequence diagrams. |
+| **Documentation** | [swarm_detailed_specification.md](file:///d:/a/ai_canifa_company/docs/swarm_detailed_specification.md) | Backend schema structures and REST contracts. |
+| **Documentation** | [swarm_implementation_plan.md](file:///d:/a/ai_canifa_company/docs/swarm_implementation_plan.md) | Step-by-step development roadmap. |
+| **E2E verification** | [test_swarm_orchestration.py](file:///d:/a/ai_canifa_company/backend/scratch/test_swarm_orchestration.py) | Mock simulation script. |