devcouncil 0.3.1 → 0.4.1

package/src/devcouncil/integrations/mcp/handlers/next_task.py

@@ -0,0 +1,35 @@
+"""Next-task selection MCP tool handler."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    error_text,
+    json_text,
+    optional_string_argument,
+    parse_cli_json,
+    run_cli_command,
+)
+
+
+async def handle_next_task(root: Path, db: object, arguments: dict) -> list[TextContent]:
+    del db  # routed through CLI service layer
+    status_filter = optional_string_argument(arguments, "status")
+    if status_filter == "":
+        return error_text("status must be a string", code="invalid_arguments", argument="status")
+    client_id = optional_string_argument(arguments, "client_id")
+    if client_id == "":
+        return error_text("client_id must be a string", code="invalid_arguments", argument="client_id")
+    cli_args = ["next-task", "--json"]
+    if status_filter:
+        cli_args.extend(["--status", status_filter])
+    if client_id:
+        cli_args.extend(["--client-id", client_id])
+    payload, cli_error = parse_cli_json(run_cli_command(cli_args, root))
+    if cli_error:
+        return cli_error
+    assert payload is not None
+    return json_text(payload)

package/src/devcouncil/integrations/mcp/handlers/policy.py

@@ -0,0 +1,80 @@
+"""Policy and command-recording MCP tool handlers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    error_text,
+    json_text,
+    optional_string_argument,
+    parse_cli_json,
+    required_string_argument,
+    run_cli_command,
+)
+
+RECORD_COMMAND_STATUSES = frozenset({"started", "finished", "failed", "blocked"})
+
+
+async def handle_policy_check_write(root: Path, db: object, arguments: dict) -> list[TextContent]:
+    del db  # routed through CLI service layer
+    path, arg_error = required_string_argument(arguments, "path")
+    if arg_error:
+        return arg_error
+    assert path is not None
+    task_id = optional_string_argument(arguments, "task_id")
+    if task_id == "":
+        return error_text("task_id must be a string", code="invalid_arguments", argument="task_id")
+    cli_args = ["policy-check", path, "--json"]
+    if task_id:
+        cli_args.extend(["--task-id", task_id])
+    payload, cli_error = parse_cli_json(run_cli_command(cli_args, root))
+    if cli_error:
+        return cli_error
+    assert payload is not None
+    return json_text(payload)
+
+
+async def handle_record_command(root: Path, db: object, arguments: dict) -> list[TextContent]:
+    del db  # routed through CLI service layer
+    task_id, arg_error = required_string_argument(arguments, "task_id")
+    if arg_error:
+        return arg_error
+    lease_token, arg_error = required_string_argument(arguments, "lease_token")
+    if arg_error:
+        return arg_error
+    command, arg_error = required_string_argument(arguments, "command")
+    if arg_error:
+        return arg_error
+    status, arg_error = required_string_argument(arguments, "status")
+    if arg_error:
+        return arg_error
+    assert task_id is not None and lease_token is not None
+    if status not in RECORD_COMMAND_STATUSES:
+        return error_text(
+            f"status must be one of {sorted(RECORD_COMMAND_STATUSES)}",
+            code="invalid_arguments",
+            argument="status",
+        )
+    exit_code = arguments.get("exit_code")
+    if exit_code is not None and (not isinstance(exit_code, int) or isinstance(exit_code, bool)):
+        return error_text("exit_code must be an integer", code="invalid_arguments")
+    cli_args = [
+        "record-command", task_id,
+        "--lease-token", lease_token,
+        "--command", command or "",
+        "--status", status or "finished",
+        "--json",
+    ]
+    if isinstance(exit_code, int):
+        cli_args.extend(["--exit-code", str(exit_code)])
+    reason = str(arguments.get("reason") or "")
+    if reason:
+        cli_args.extend(["--reason", reason])
+    payload, cli_error = parse_cli_json(run_cli_command(cli_args, root))
+    if cli_error:
+        return cli_error
+    assert payload is not None
+    return json_text(payload)

package/src/devcouncil/integrations/mcp/handlers/prompts.py

@@ -0,0 +1,168 @@
+"""MCP prompt templates and live status snapshots."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import NamedTuple
+
+from mcp.types import GetPromptResult, Prompt, PromptArgument, PromptMessage, TextContent
+
+from devcouncil.app.project_status import compute_phase
+from devcouncil.executors.advisor_tool import ADVISOR_STEERING_NUDGE
+from devcouncil.integrations.mcp.util import normalize_arguments
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import ArtifactGraphRepository, StateRepository
+
+
+class PromptSpec(NamedTuple):
+    name: str
+    description: str
+    arguments: list[PromptArgument]
+
+
+PROMPT_SPECS: list[PromptSpec] = [
+    PromptSpec(
+        name="devcouncil_implement_next_task",
+        description="Pick up the next unblocked DevCouncil task and implement it through the policy-gated MCP loop.",
+        arguments=[
+            PromptArgument(name="client_id", description="Optional stable client id used for the task lease.", required=False),
+        ],
+    ),
+    PromptSpec(
+        name="devcouncil_repair_task",
+        description="Repair the blocking verification gaps for a task (defaults to the active running task).",
+        arguments=[
+            PromptArgument(name="task_id", description="Task id, e.g. TASK-001. Defaults to the active task.", required=False),
+        ],
+    ),
+    PromptSpec(
+        name="devcouncil_verify_task",
+        description="Run DevCouncil verification for a task and report blocking gaps.",
+        arguments=[
+            PromptArgument(name="task_id", description="Task id, e.g. TASK-001. Defaults to the active task.", required=False),
+        ],
+    ),
+    PromptSpec(
+        name="devcouncil_review_live",
+        description="Review pending live-review critique cards and resolve the blocking ones.",
+        arguments=[
+            PromptArgument(name="task_id", description="Optional task scope for the live-review cards.", required=False),
+        ],
+    ),
+    PromptSpec(
+        name="devcouncil_project_status",
+        description="Summarize the current DevCouncil project phase, tasks, and blocking gaps.",
+        arguments=[],
+    ),
+    PromptSpec(
+        name="devcouncil_apply_knowledge",
+        description="Select the ingested project knowledge (OKF + design) that applies to a goal and inject it.",
+        arguments=[
+            PromptArgument(name="goal", description="The task or goal to find applicable project knowledge for.", required=True),
+        ],
+    ),
+]
+
+
+def status_snapshot(root: Path) -> str:
+    """A short live status block for prompt bodies, or an init hint when uninitialized."""
+    db = get_db(root)
+    if not db:
+        return (
+            "DevCouncil is not initialized here yet — run `dev status` or `dev map` "
+            "(both auto-bootstrap a minimal project) or `dev init` for full setup."
+        )
+    try:
+        with db.get_session() as session:
+            graph = ArtifactGraphRepository(session).load_graph()
+            summary = graph.coverage_summary()
+            state = StateRepository(session).get_state()
+            phase = compute_phase(graph, state.current_phase if state else None)
+        return (
+            f"Phase: {phase} | "
+            f"tasks: {summary['total_tasks']} | "
+            f"gaps: {summary['total_gaps']} ({summary['blocking_gaps']} blocking)"
+        )
+    except Exception:
+        return "DevCouncil status unavailable."
+
+
+def render_prompt_text(name: str, arguments: dict, root: Path) -> str:
+    snapshot = status_snapshot(root)
+    if name == "devcouncil_implement_next_task":
+        client_id = arguments.get("client_id") or "claude-code"
+        return (
+            "You are implementing the next DevCouncil task under policy enforcement.\n\n"
+            f"Project status: {snapshot}\n\n"
+            "Do exactly this:\n"
+            "1. Call `devcouncil_next_task` to get the highest-priority unblocked task.\n"
+            f"2. Call `devcouncil_checkout_task` with that task_id and client_id='{client_id}' to acquire a lease.\n"
+            "3. Read the task scope with `devcouncil_get_task` and `devcouncil_get_prompt`; inspect files with `devcouncil_read_file` and `devcouncil_get_diff`.\n"
+            "4. Make changes ONLY through `devcouncil_write_file` / `devcouncil_apply_patch` (the policy gate rejects out-of-scope or protected paths) and run tests with `devcouncil_run_command`.\n"
+            f"5. {ADVISOR_STEERING_NUDGE}\n"
+            "6. Call `devcouncil_verify_task`; if it reports blocking gaps, fix them and re-verify.\n"
+            "7. When verified, call `devcouncil_release_task` with the lease token.\n\n"
+            "Never edit files outside the task scope. If a write is rejected, call `devcouncil_update_task_scope` only when the change is legitimately in-scope."
+        )
+    if name == "devcouncil_repair_task":
+        task_id = arguments.get("task_id") or "(the active task)"
+        return (
+            f"Repair the blocking verification gaps for {task_id}.\n\n"
+            f"Project status: {snapshot}\n\n"
+            "1. Call `devcouncil_get_gaps` (blocking_only=true) and `devcouncil_get_next_actions` for the task.\n"
+            "2. Inspect the relevant files and evidence with `devcouncil_read_file` and `devcouncil_get_evidence`.\n"
+            "3. Apply minimal fixes via `devcouncil_apply_patch` / `devcouncil_write_file`.\n"
+            f"4. {ADVISOR_STEERING_NUDGE}\n"
+            "5. Re-run `devcouncil_verify_task` until no blocking gaps remain, then `devcouncil_release_task`."
+        )
+    if name == "devcouncil_verify_task":
+        task_id = arguments.get("task_id") or "(the active task)"
+        return (
+            f"Run DevCouncil verification for {task_id} and report the result.\n\n"
+            f"Project status: {snapshot}\n\n"
+            "Call `devcouncil_verify_task` (you must hold the task lease via `devcouncil_checkout_task`). "
+            "Summarize the blocking gaps and proposed next actions; do not mark work complete while blocking gaps remain."
+        )
+    if name == "devcouncil_review_live":
+        scope = arguments.get("task_id")
+        scope_line = f" scoped to {scope}" if scope else ""
+        return (
+            f"Review the pending live-review critique cards{scope_line}.\n\n"
+            "1. Call `devcouncil_live_review` for the blocker count and `devcouncil_live_cards` (status='open') for the cards.\n"
+            "2. For each blocking card, call `devcouncil_live_repair_prompt` (or `devcouncil_live_repair_all`) to get a ready-to-apply repair.\n"
+            "3. Apply the fixes through the policy-gated write tools and re-verify."
+        )
+    if name == "devcouncil_project_status":
+        return (
+            "Summarize the DevCouncil project state for the user.\n\n"
+            f"Live snapshot: {snapshot}\n\n"
+            "Call `devcouncil_status` and `devcouncil_report` for the full coverage report, then give a concise "
+            "phase / tasks / blocking-gaps summary and recommend the next action."
+        )
+    if name == "devcouncil_apply_knowledge":
+        goal = arguments.get("goal") or ""
+        return (
+            f"Find and apply the project knowledge that applies to this goal: {goal!r}.\n\n"
+            "Call `devcouncil_select_knowledge` with the goal, then treat the returned preamble as authoritative "
+            "project context (design system + OKF docs) for any code you write toward this goal."
+        )
+    return f"Unknown DevCouncil prompt: {name}"
+
+
+def list_prompts() -> list[Prompt]:
+    return [
+        Prompt(name=spec.name, description=spec.description, arguments=list(spec.arguments))
+        for spec in PROMPT_SPECS
+    ]
+
+
+def get_prompt(name: str, arguments: dict | None, root: Path) -> GetPromptResult:
+    spec = next((spec for spec in PROMPT_SPECS if spec.name == name), None)
+    if spec is None:
+        raise ValueError(f"Unknown prompt: {name}")
+    args = normalize_arguments(arguments)
+    text = render_prompt_text(name, args, root)
+    return GetPromptResult(
+        description=spec.description,
+        messages=[PromptMessage(role="user", content=TextContent(type="text", text=text))],
+    )

package/src/devcouncil/integrations/mcp/handlers/provenance.py

@@ -0,0 +1,87 @@
+"""Task provenance and MCP corpus resource handlers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.types import Resource, TextContent
+from pydantic import AnyUrl
+
+from devcouncil.integrations.mcp.util import (
+    json_text,
+    parse_cli_json,
+    required_string_argument,
+    run_cli_command,
+    run_cli_json,
+)
+from devcouncil.knowledge.resource_discovery import (
+    discover_knowledge_sources,
+    knowledge_source_uri,
+)
+
+__all__ = [
+    "discover_knowledge_sources",
+    "handle_get_task_provenance",
+    "knowledge_settings",
+    "knowledge_source_uri",
+    "list_resources",
+    "read_resource",
+]
+
+# Re-export for callers that imported from this module.
+from devcouncil.knowledge.resource_discovery import knowledge_settings  # noqa: E402
+
+
+async def handle_get_task_provenance(root: Path, db: object, arguments: dict) -> list[TextContent]:
+    task_id, arg_error = required_string_argument(arguments, "task_id")
+    if arg_error:
+        return arg_error
+    assert task_id is not None
+    payload, cli_error = run_cli_json(["provenance", task_id, "--json"], root)
+    if cli_error:
+        return cli_error
+    assert payload is not None
+    return json_text(payload)
+
+
+async def list_resources(root: Path) -> list[Resource]:
+    """Expose the DevCouncil corpus as browsable MCP resources."""
+    payload, _cli_error = parse_cli_json(
+        run_cli_command(["resource", "list", "--json"], root, truncate=False),
+    )
+    if payload is not None:
+        descriptors = payload.get("resources") or []
+        if isinstance(descriptors, list):
+            return [
+                Resource(
+                    uri=AnyUrl(item["uri"]),
+                    name=item["name"],
+                    description=item["description"],
+                    mimeType=item["mimeType"],
+                )
+                for item in descriptors
+                if isinstance(item, dict) and item.get("uri")
+            ]
+    # Fallback when CLI is unavailable (e.g. during early init).
+    from devcouncil.reporting.mcp_resources import list_mcp_resource_uris
+
+    return [
+        Resource(
+            uri=AnyUrl(item["uri"]),
+            name=item["name"],
+            description=item["description"],
+            mimeType=item["mimeType"],
+        )
+        for item in list_mcp_resource_uris(root)
+    ]
+
+
+async def read_resource(root: Path, uri: AnyUrl) -> str:
+    key = str(uri).rstrip("/")
+    result = run_cli_command(["resource", "read", key], root, truncate=False)
+    stdout = result.get("stdout")
+    if result.get("ok") and stdout is not None:
+        return str(stdout)
+    from devcouncil.reporting.mcp_resources import read_mcp_resource
+
+    return read_mcp_resource(root, key)

package/src/devcouncil/integrations/mcp/handlers/read.py

@@ -0,0 +1,103 @@
+"""Read-file MCP tool handler."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    error_text,
+    int_argument,
+    is_secret_path,
+    json_text,
+    optional_string_argument,
+    required_string_argument,
+    truncate_text,
+    within_root,
+)
+from devcouncil.storage.db import Database
+from devcouncil.storage.repositories import TaskRepository
+
+
+async def handle_read_file(
+    root: Path,
+    arguments: dict,
+    db: Database | None = None,
+) -> list[TextContent]:
+    rel_path, arg_error = required_string_argument(arguments, "path")
+    if arg_error:
+        return arg_error
+    assert rel_path is not None
+    task_id = optional_string_argument(arguments, "task_id")
+    if task_id == "":
+        return error_text("task_id must be a string", code="invalid_arguments", argument="task_id")
+    if task_id:
+        if db is None:
+            return error_text(
+                "DevCouncil not initialized in this directory.",
+                code="not_initialized",
+            )
+        with db.get_session() as session:
+            task = TaskRepository(session).get_by_id(task_id)
+        if task is None:
+            return error_text(f"Task {task_id} not found.", code="not_found", task_id=task_id)
+        planned = {pf.path.replace("\\", "/") for pf in task.planned_files}
+        normalized = rel_path.replace("\\", "/")
+        if normalized not in planned:
+            # Fail closed: never broaden task scope to arbitrary repo paths.
+            return error_text(
+                f"Path {normalized} is outside task {task_id} planned-file scope.",
+                code="out_of_scope",
+                path=normalized,
+                task_id=task_id,
+            )
+    if is_secret_path(root, rel_path):
+        return error_text(
+            "Refusing to read a secret/credential path.",
+            code="secret_path", path=rel_path,
+        )
+    target = within_root(root, rel_path)
+    if target is None:
+        return error_text("path escapes the project root", code="path_escape", path=rel_path)
+    if not target.exists() or not target.is_file():
+        return error_text(f"File not found: {rel_path}", code="not_found", path=rel_path)
+    try:
+        raw = target.read_bytes()
+    except OSError as exc:
+        return error_text(f"Read failed: {exc}", code="read_failed", path=rel_path)
+    sha256 = hashlib.sha256(raw).hexdigest()
+    text = raw.decode("utf-8", errors="replace")
+    all_lines = text.splitlines()
+    line_count = len(all_lines)
+    line_range = optional_string_argument(arguments, "line_range")
+    if line_range == "":
+        return error_text("line_range must be a string", code="invalid_arguments", argument="line_range")
+    selected = all_lines
+    if line_range:
+        try:
+            start_str, _, end_str = line_range.partition("-")
+            start = max(1, int(start_str))
+            end = int(end_str) if end_str else line_count
+        except ValueError:
+            return error_text("line_range must look like '10-40'", code="invalid_arguments", argument="line_range")
+        selected = all_lines[start - 1:end]
+    else:
+        offset = int_argument(arguments, "offset", 0, minimum=0, maximum=10_000_000)
+        limit_value = arguments.get("limit")
+        if isinstance(limit_value, int) and not isinstance(limit_value, bool):
+            limit = max(1, limit_value)
+            selected = all_lines[offset:offset + limit]
+        elif offset:
+            selected = all_lines[offset:]
+    windowed = "\n".join(selected)
+    content, truncated = truncate_text(windowed)
+    return json_text({
+        "ok": True,
+        "path": rel_path.replace("\\", "/"),
+        "content": content,
+        "sha256": sha256,
+        "line_count": line_count,
+        "truncated": truncated,
+    })

package/src/devcouncil/integrations/mcp/handlers/router_cache.py

@@ -0,0 +1,53 @@
+"""Per-root ModelRouter cache for MCP verify/supervise handlers."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from devcouncil.integrations.mcp.handlers import ast_lsp as ast_lsp_handlers
+
+logger = logging.getLogger(__name__)
+
+_ROUTER_CACHE: dict[str, tuple[Any, Any]] = {}
+
+
+def reset_caches() -> None:
+    """Drop all per-root MCP caches (router/ast/lsp). For test isolation."""
+    _ROUTER_CACHE.clear()
+    ast_lsp_handlers.reset_caches()
+
+
+def load_router(root: Path):
+    """Build a ModelRouter from project config, or return None when no provider key
+    is configured. Cached per resolved project root with config stat invalidation."""
+    key = str(root.resolve())
+    try:
+        cfg_stat = (root / ".devcouncil" / "config.yaml").stat()
+        signature: object = (cfg_stat.st_mtime_ns, cfg_stat.st_size, cfg_stat.st_ino)
+    except OSError:
+        signature = None
+    cached = _ROUTER_CACHE.get(key)
+    if cached is not None and cached[0] == signature:
+        return cached[1]
+    router = _build_router(root)
+    _ROUTER_CACHE[key] = (signature, router)
+    return router
+
+
+def _build_router(root: Path):
+    try:
+        from devcouncil.app.config import get_api_key, load_config
+        from devcouncil.llm.provider import create_provider, validate_model_provider
+        from devcouncil.llm.router import ModelRouter
+
+        config = load_config(root)
+        validate_model_provider(config.models.provider)
+        api_key = get_api_key(config.models.provider, root)
+        provider = create_provider(config.models.provider, api_key, project_root=root, provider_prefs=config.provider)
+        role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
+        return ModelRouter(provider, role_config, project_root=root)
+    except Exception:
+        logger.warning("Failed to build MCP model router for %s", root, exc_info=True)
+        return None

package/src/devcouncil/integrations/mcp/handlers/run.py

@@ -0,0 +1,53 @@
+"""Run-command MCP tool handler."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    error_text,
+    json_text,
+    parse_cli_json,
+    required_string_argument,
+    run_cli_command,
+)
+
+
+async def handle_run_command(root: Path, db: object, arguments: dict) -> list[TextContent]:
+    del db  # routed through CLI service layer
+    task_id, arg_error = required_string_argument(arguments, "task_id")
+    if arg_error:
+        return arg_error
+    lease_token, arg_error = required_string_argument(arguments, "lease_token")
+    if arg_error:
+        return arg_error
+    command, arg_error = required_string_argument(arguments, "command")
+    if arg_error:
+        return arg_error
+    assert task_id is not None and lease_token is not None and command is not None
+    cli_args = [
+        "run-cmd", task_id,
+        "--lease-token", lease_token,
+        "--command", command,
+        "--json",
+    ]
+    payload, cli_error = parse_cli_json(run_cli_command(cli_args, root))
+    if cli_error:
+        return cli_error
+    assert payload is not None
+    if payload.get("code") == "command_not_allowed":
+        return error_text(
+            str(payload.get("error") or "Command is not in the task allowlist."),
+            code="command_not_allowed",
+            task_id=task_id,
+            command=str(payload.get("command") or command),
+        )
+    if payload.get("code") == "run_failed":
+        return error_text(
+            str(payload.get("error") or "Could not run command"),
+            code="run_failed",
+            task_id=task_id,
+        )
+    return json_text(payload)

package/src/devcouncil/integrations/mcp/handlers/runs.py

@@ -0,0 +1,69 @@
+"""Agent run listing and inspection MCP tool handlers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    error_text,
+    int_argument,
+    json_text,
+    optional_string_argument,
+    required_string_argument,
+    run_cli_json,
+    truncate_text,
+)
+
+
+async def handle_list_agent_runs(root: Path, arguments: dict) -> list[TextContent]:
+    status_filter = optional_string_argument(arguments, "status")
+    if status_filter == "":
+        return error_text("status must be a string", code="invalid_arguments", argument="status")
+    limit = int_argument(arguments, "limit", 20, minimum=1, maximum=500)
+    cli_args = ["runs", "list", "--json", "--limit", str(limit)]
+    if status_filter:
+        cli_args.extend(["--status", status_filter])
+    payload, cli_error = run_cli_json(cli_args, root)
+    if cli_error:
+        return cli_error
+    assert payload is not None
+    runs = payload.get("runs") or []
+    if not isinstance(runs, list):
+        runs = []
+    total = payload.get("total", payload.get("count", len(runs)))
+    return json_text({
+        "ok": True,
+        "runs": runs,
+        "total": total,
+        "returned": len(runs),
+    })
+
+
+async def handle_get_run(root: Path, arguments: dict) -> list[TextContent]:
+    run_id, arg_error = required_string_argument(arguments, "run_id")
+    if arg_error:
+        return arg_error
+    assert run_id is not None
+    payload, cli_error = run_cli_json(["runs", "show", run_id, "--json"], root)
+    if cli_error:
+        return cli_error
+    assert payload is not None
+    if not payload.get("ok", True):
+        return error_text(
+            str(payload.get("error") or f"Run {run_id} not found."),
+            code=str(payload.get("code") or "not_found"),
+            run_id=run_id,
+        )
+    tail = str(payload.get("transcript_tail") or "")
+    truncated_tail, truncated = truncate_text(tail)
+    return json_text({
+        "ok": True,
+        "run_id": payload.get("run_id", run_id),
+        "manifest": payload.get("manifest"),
+        "orphaned": payload.get("orphaned", False),
+        "transcript_path": payload.get("transcript_path"),
+        "transcript_tail": truncated_tail,
+        "transcript_truncated": truncated,
+    })