roboco/tests/unit/api/test_orchestrator_manual_spawn.py

"""Manual (panel) spawn: task-aware prompt helper + already-running signaling.

Covers the CEO-facing spawn-refusal / double-fire triage: a task-aware
initial prompt built server-side for a manual spawn (mirroring
``_build_pr_review_prompt``'s tone), an ``AgentReadinessError`` refusal
mapped to 409 (not an opaque 500) so the panel can show the real reason, and
an ``already_running`` marker so a no-op spawn (agent already active) is
distinguishable from a genuine new spawn.
"""

from __future__ import annotations

from datetime import UTC, datetime
from http import HTTPStatus
from types import SimpleNamespace
from typing import TYPE_CHECKING, cast
from unittest.mock import AsyncMock, MagicMock
from uuid import uuid4

import pytest
import pytest_asyncio
import roboco.services.task as task_service_module
from fastapi import FastAPI, HTTPException
from httpx import ASGITransport, AsyncClient
from roboco.api.deps import _ServiceHolder, set_orchestrator, validate_agent_id_param
from roboco.api.routes.orchestrator import (
    router as orch_router,
)
from roboco.runtime.orchestrator import AgentReadinessError, AgentState
from roboco.services.task import (
    build_manual_spawn_prompt,
    resolve_manual_spawn_prompt,
)

if TYPE_CHECKING:
    from collections.abc import AsyncIterator

    from roboco.db.tables import TaskTable

_HDR = {"X-Agent-ID": str(uuid4()), "X-Agent-Role": "ceo"}


def _fake_task(status_value: str = "pending") -> TaskTable:
    # SimpleNamespace duck-types TaskTable's 3 fields the helper reads
    # (id/title/status.value) without a real ORM row.
    return cast(
        "TaskTable",
        SimpleNamespace(
            id="task-123",
            title="Fix the thing",
            status=SimpleNamespace(value=status_value),
        ),
    )


class _FakeDbCtx:
    async def __aenter__(self) -> str:
        return "fake-db"

    async def __aexit__(self, *exc: object) -> bool:
        return False


class _FakeTaskService:
    def __init__(self, task: object | None = None, error: Exception | None = None):
        self._task = task
        self._error = error

    async def get(self, _task_id: object) -> object | None:
        if self._error:
            raise self._error
        return self._task


# ---------------------------------------------------------------------------
# build_manual_spawn_prompt — pure formatting
# ---------------------------------------------------------------------------


def test_build_manual_spawn_prompt_includes_task_fields() -> None:
    prompt = build_manual_spawn_prompt(_fake_task("awaiting_qa"), None)
    assert "TASK ID: task-123" in prompt
    assert "TITLE: Fix the thing" in prompt
    assert "STATUS: awaiting_qa" in prompt
    assert "claim verb" in prompt.lower()
    assert "CEO NOTE" not in prompt


def test_build_manual_spawn_prompt_appends_ceo_note() -> None:
    prompt = build_manual_spawn_prompt(_fake_task(), "Please prioritize this.")
    assert "== CEO NOTE ==" in prompt
    assert "Please prioritize this." in prompt
    # CEO note comes after the task framing, not instead of it.
    assert prompt.index("TASK ID") < prompt.index("CEO NOTE")


# ---------------------------------------------------------------------------
# resolve_manual_spawn_prompt — best-effort enrichment
# ---------------------------------------------------------------------------


@pytest.mark.asyncio
async def test_resolve_prompt_no_task_id_returns_message_unchanged() -> None:
    result = await resolve_manual_spawn_prompt(None, "hello")
    assert result == "hello"


@pytest.mark.asyncio
async def test_resolve_prompt_enriches_when_task_found(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setattr(task_service_module, "get_db_context", _FakeDbCtx)
    monkeypatch.setattr(
        task_service_module,
        "get_task_service",
        lambda _db: _FakeTaskService(task=_fake_task("verifying")),
    )
    result = await resolve_manual_spawn_prompt(str(uuid4()), "Ship it")
    assert result is not None
    assert "STATUS: verifying" in result
    assert "Ship it" in result


@pytest.mark.asyncio
async def test_resolve_prompt_falls_back_when_task_not_found(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setattr(task_service_module, "get_db_context", _FakeDbCtx)
    monkeypatch.setattr(
        task_service_module, "get_task_service", lambda _db: _FakeTaskService(task=None)
    )
    result = await resolve_manual_spawn_prompt(str(uuid4()), "hello")
    assert result == "hello"


@pytest.mark.asyncio
async def test_resolve_prompt_falls_back_on_bad_task_id() -> None:
    # Not a valid UUID — must not raise, must fall back unchanged.
    result = await resolve_manual_spawn_prompt("not-a-uuid", "hello")
    assert result == "hello"


@pytest.mark.asyncio
async def test_resolve_prompt_falls_back_on_db_error(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setattr(task_service_module, "get_db_context", _FakeDbCtx)
    monkeypatch.setattr(
        task_service_module,
        "get_task_service",
        lambda _db: _FakeTaskService(error=RuntimeError("db down")),
    )
    result = await resolve_manual_spawn_prompt(str(uuid4()), "hello")
    assert result == "hello"


@pytest.mark.asyncio
async def test_resolve_prompt_no_message_no_task_returns_none() -> None:
    result = await resolve_manual_spawn_prompt(None, None)
    assert result is None


# ---------------------------------------------------------------------------
# Route: AgentReadinessError -> 409, already_running signaling
# ---------------------------------------------------------------------------


@pytest_asyncio.fixture
async def orch_client() -> AsyncIterator[tuple[AsyncClient, MagicMock]]:
    app = FastAPI()
    app.include_router(orch_router, prefix="/api/orchestrator")
    orchestrator = MagicMock()
    set_orchestrator(orchestrator)
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as client:
        yield client, orchestrator
    _ServiceHolder.orchestrator = None
    app.dependency_overrides.clear()


@pytest.mark.asyncio
async def test_spawn_readiness_refusal_maps_to_409(
    orch_client: tuple[AsyncClient, MagicMock],
) -> None:
    client, orch = orch_client
    orch.get_instance = MagicMock(return_value=None)
    orch.spawn_agent = AsyncMock(
        side_effect=AgentReadinessError(
            "spawn refused for fe-dev-2 (task=t1): state=awaiting_qa requires "
            "role in {'qa'} but agent fe-dev-2 is 'developer'"
        )
    )
    response = await client.post(
        "/api/orchestrator/agents/fe-dev-2/spawn",
        json={"agent_id": "fe-dev-2", "task_id": "t1"},
        headers=_HDR,
    )
    assert response.status_code == HTTPStatus.CONFLICT
    assert "requires role in" in response.json()["detail"]


@pytest.mark.asyncio
async def test_spawn_new_agent_not_flagged_already_running(
    orch_client: tuple[AsyncClient, MagicMock],
) -> None:
    client, orch = orch_client
    orch.get_instance = MagicMock(return_value=None)
    instance = SimpleNamespace(
        id=uuid4(),
        agent_id="be-dev-1",
        state=AgentState.STARTING,
        current_task_id=None,
        error_count=0,
        started_at=datetime.now(UTC),
    )
    orch.spawn_agent = AsyncMock(return_value=instance)
    response = await client.post(
        "/api/orchestrator/agents/be-dev-1/spawn", headers=_HDR
    )
    assert response.status_code == HTTPStatus.CREATED
    assert response.json()["already_running"] is False


@pytest.mark.asyncio
async def test_spawn_already_running_agent_is_flagged(
    orch_client: tuple[AsyncClient, MagicMock],
) -> None:
    client, orch = orch_client
    shared_id = uuid4()
    existing = SimpleNamespace(
        id=shared_id,
        agent_id="ux-pm",
        state=AgentState.STARTING,
        current_task_id=None,
        error_count=0,
        started_at=datetime.now(UTC),
    )
    orch.get_instance = MagicMock(return_value=existing)
    # spawn_agent's own no-op contract: hands back the SAME instance.
    orch.spawn_agent = AsyncMock(return_value=existing)
    response = await client.post("/api/orchestrator/agents/ux-pm/spawn", headers=_HDR)
    assert response.status_code == HTTPStatus.CREATED
    body = response.json()
    assert body["already_running"] is True
    assert body["state"] == "starting"


@pytest.mark.asyncio
async def test_spawn_offline_agent_not_flagged_already_running(
    orch_client: tuple[AsyncClient, MagicMock],
) -> None:
    """A pre-existing OFFLINE instance is not "running" — a fresh spawn on top
    of it must not be reported as a no-op."""
    client, orch = orch_client
    offline = SimpleNamespace(
        id=uuid4(),
        agent_id="be-dev-1",
        state=AgentState.OFFLINE,
        current_task_id=None,
        error_count=0,
        started_at=datetime.now(UTC),
    )
    orch.get_instance = MagicMock(return_value=offline)
    new_instance = SimpleNamespace(
        id=uuid4(),
        agent_id="be-dev-1",
        state=AgentState.STARTING,
        current_task_id=None,
        error_count=0,
        started_at=datetime.now(UTC),
    )
    orch.spawn_agent = AsyncMock(return_value=new_instance)
    response = await client.post(
        "/api/orchestrator/agents/be-dev-1/spawn", headers=_HDR
    )
    assert response.status_code == HTTPStatus.CREATED
    assert response.json()["already_running"] is False


# ---------------------------------------------------------------------------
# validate_agent_id_param — path-traversal guard (agent_id flows into
# per-agent filesystem paths downstream, e.g. the grok usage dir)
# ---------------------------------------------------------------------------


def test_validated_agent_id_still_rejects_traversal() -> None:
    """Regression: every traversal vector — empty, '.'/'..' , a path
    separator, or an embedded NUL — must still 422 at the HTTP boundary
    after any refactor of the orchestrator routes, since agent_id is a
    raw request path parameter flowing into per-agent paths downstream."""
    for bad in ("", ".", "..", "a/b", "a\\b", "a\x00b"):
        with pytest.raises(HTTPException) as exc_info:
            validate_agent_id_param(bad)
        assert exc_info.value.status_code == HTTPStatus.UNPROCESSABLE_ENTITY


def test_validate_agent_id_param_accepts_plain_slug() -> None:
    assert validate_agent_id_param("be-dev-1") == "be-dev-1"


@pytest.mark.asyncio
async def test_spawn_route_rejects_traversal_agent_id(
    orch_client: tuple[AsyncClient, MagicMock],
) -> None:
    """The traversal guard still runs at the spawn route itself, not just
    when called directly — a backslash-bearing agent_id must never reach
    ``orchestrator.spawn_agent``."""
    client, orch = orch_client
    orch.spawn_agent = AsyncMock()
    response = await client.post(
        "/api/orchestrator/agents/a%5Cb/spawn",
        json={"agent_id": "a\\b"},
        headers=_HDR,
    )
    assert response.status_code == HTTPStatus.UNPROCESSABLE_ENTITY
    orch.spawn_agent.assert_not_called()


# ---------------------------------------------------------------------------
# Non-CEO callers are forbidden on every orchestrator control route
# ---------------------------------------------------------------------------


@pytest.mark.asyncio
async def test_spawn_non_ceo_is_forbidden(
    orch_client: tuple[AsyncClient, MagicMock],
) -> None:
    client, orch = orch_client
    orch.spawn_agent = AsyncMock()
    response = await client.post(
        "/api/orchestrator/agents/be-dev-1/spawn",
        json={"agent_id": "be-dev-1"},
        headers={"X-Agent-ID": str(uuid4()), "X-Agent-Role": "developer"},
    )
    assert response.status_code == HTTPStatus.FORBIDDEN
    orch.spawn_agent.assert_not_called()