devcouncil 0.3.0 → 0.4.0

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

@@ -0,0 +1,236 @@
+"""Registry-backed MCP debugger and runtime-trace tools."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from mcp.types import TextContent, Tool
+
+from devcouncil.codeintel.debug.consent import require_debug_consent, set_debug_consent
+from devcouncil.codeintel.debug.discovery import adapter_by_id, discover_adapters
+from devcouncil.codeintel.debug.session import get_debug_manager
+from devcouncil.codeintel.debug.tracing import NodeCpuProfileProvider, PythonTraceProvider, import_runtime_trace
+from devcouncil.codeintel.service import canonical_project_root
+from devcouncil.integrations.mcp.util import error_text, json_text
+
+Handler = Callable[[Path, dict], Awaitable[list[TextContent]]]
+
+
+def _schema(properties: dict, required: list[str] | None = None) -> dict:
+    schema: dict = {"type": "object", "properties": {
+        "projectPath": {"type": "string", "description": "Explicit repository path."},
+        **properties,
+    }}
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def tools() -> list[Tool]:
+    return [
+        Tool(
+            name="devcouncil_debug_discover",
+            description=(
+                "Discover installed DAP adapters after explicit one-time consent; "
+                "returns paths, versions, hashes, and launch/attach support."
+            ),
+            inputSchema=_schema({"consent": {"type": "boolean", "default": False}}),
+        ),
+        Tool(
+            name="devcouncil_debug_start",
+            description="Launch or attach a capability-negotiated DAP session.",
+            inputSchema=_schema({
+                "adapterId": {"type": "string"},
+                "adapterCommand": {"type": "array", "items": {"type": "string"}},
+                "request": {"type": "string", "enum": ["launch", "attach"], "default": "launch"},
+                "configuration": {"type": "object"},
+                "initialBreakpoints": {
+                    "type": "object",
+                    "additionalProperties": {"type": "array", "items": {"type": "integer"}},
+                },
+                "timeout": {"type": "number", "minimum": 1, "maximum": 120, "default": 30},
+            }),
+        ),
+        Tool(
+            name="devcouncil_debug_breakpoints",
+            description="Replace all breakpoints for one source in a DAP session.",
+            inputSchema=_schema({
+                "sessionId": {"type": "string"},
+                "source": {"type": "string"},
+                "lines": {"type": "array", "items": {"type": "integer"}},
+            }, ["sessionId", "source", "lines"]),
+        ),
+        Tool(
+            name="devcouncil_debug_control",
+            description="Continue, pause, or step a DAP session.",
+            inputSchema=_schema({
+                "sessionId": {"type": "string"},
+                "action": {"type": "string", "enum": ["continue", "pause", "next", "stepIn", "stepOut"]},
+                "threadId": {"type": "integer"},
+            }, ["sessionId", "action"]),
+        ),
+        Tool(
+            name="devcouncil_debug_inspect",
+            description="Inspect threads, stack frames, scopes, variables, source, or disassembly.",
+            inputSchema=_schema({
+                "sessionId": {"type": "string"},
+                "operation": {"type": "string", "enum": ["threads", "stackTrace", "scopes", "variables", "source", "disassemble"]},
+                "arguments": {"type": "object"},
+            }, ["sessionId", "operation"]),
+        ),
+        Tool(
+            name="devcouncil_debug_evaluate",
+            description="Side-effectful DAP evaluate; allowSideEffects must be explicitly true.",
+            inputSchema=_schema({
+                "sessionId": {"type": "string"},
+                "expression": {"type": "string"},
+                "frameId": {"type": "integer"},
+                "allowSideEffects": {"type": "boolean", "const": True},
+            }, ["sessionId", "expression", "allowSideEffects"]),
+        ),
+        Tool(
+            name="devcouncil_debug_trace",
+            description="Capture a DAP stack, run exact Python tracing, or import JSONL/Node CPU profile evidence.",
+            inputSchema=_schema({
+                "provider": {"type": "string", "enum": ["dap-stack", "python", "node", "import"]},
+                "sessionId": {"type": "string"},
+                "threadId": {"type": "integer"},
+                "script": {"type": "string"},
+                "args": {"type": "array", "items": {"type": "string"}},
+                "path": {"type": "string"},
+            }, ["provider"]),
+        ),
+        Tool(
+            name="devcouncil_debug_stop",
+            description="Disconnect a DAP session and optionally leave the debuggee running.",
+            inputSchema=_schema({
+                "sessionId": {"type": "string"},
+                "terminateDebuggee": {"type": "boolean", "default": True},
+            }, ["sessionId"]),
+        ),
+    ]
+
+
+async def _discover(root: Path, arguments: dict) -> list[TextContent]:
+    if arguments.get("consent") is True:
+        set_debug_consent(root, True)
+    require_debug_consent(root)
+    return json_text({"consent": True, "adapters": [adapter.as_dict() for adapter in discover_adapters()]})
+
+
+def _command(arguments: dict) -> list[str]:
+    supplied = arguments.get("adapterCommand")
+    if isinstance(supplied, list) and supplied:
+        return [str(value) for value in supplied]
+    adapter_id = str(arguments.get("adapterId") or "debugpy")
+    adapter = adapter_by_id(adapter_id)
+    if adapter is None:
+        raise ValueError(f"adapter {adapter_id!r} was not discovered")
+    return list(adapter.command)
+
+
+async def _start(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    session = get_debug_manager().start(
+        root,
+        _command(arguments),
+        request=str(arguments.get("request", "launch")),
+        arguments=dict(arguments.get("configuration") or {}),
+        initial_breakpoints={
+            str(source): [int(line) for line in lines]
+            for source, lines in dict(arguments.get("initialBreakpoints") or {}).items()
+        },
+        timeout=float(arguments.get("timeout", 30.0)),
+    )
+    return json_text(session.as_dict())
+
+
+async def _breakpoints(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    return json_text(get_debug_manager().set_breakpoints(
+        str(arguments["sessionId"]), str(arguments["source"]), [int(value) for value in arguments["lines"]]
+    ))
+
+
+async def _control(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    return json_text(get_debug_manager().control(
+        str(arguments["sessionId"]),
+        str(arguments["action"]),
+        thread_id=int(arguments["threadId"]) if arguments.get("threadId") is not None else None,
+    ))
+
+
+async def _inspect(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    return json_text(get_debug_manager().inspect(
+        str(arguments["sessionId"]), str(arguments["operation"]), dict(arguments.get("arguments") or {})
+    ))
+
+
+async def _evaluate(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    if arguments.get("allowSideEffects") is not True:
+        raise PermissionError("debug evaluate requires allowSideEffects=true")
+    return json_text(get_debug_manager().evaluate(
+        str(arguments["sessionId"]),
+        str(arguments["expression"]),
+        frame_id=int(arguments["frameId"]) if arguments.get("frameId") is not None else None,
+        allow_side_effects=True,
+    ))
+
+
+async def _trace(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    provider = str(arguments["provider"])
+    if provider == "dap-stack":
+        return json_text(get_debug_manager().capture_stack(
+            str(arguments["sessionId"]), thread_id=int(arguments["threadId"])
+        ))
+    if provider == "python":
+        return json_text(PythonTraceProvider(root).run(
+            Path(str(arguments["script"])), [str(value) for value in arguments.get("args") or []]
+        ))
+    if provider == "node":
+        return json_text(NodeCpuProfileProvider(root).run(
+            Path(str(arguments["script"])), [str(value) for value in arguments.get("args") or []]
+        ))
+    if provider == "import":
+        return json_text(import_runtime_trace(root, Path(str(arguments["path"]))))
+    raise ValueError(f"unsupported trace provider: {provider}")
+
+
+async def _stop(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    session_id = str(arguments["sessionId"])
+    get_debug_manager().stop(session_id, terminate_debuggee=bool(arguments.get("terminateDebuggee", True)))
+    return json_text({"stopped": session_id})
+
+
+REGISTRY: dict[str, Handler] = {
+    "devcouncil_debug_discover": _discover,
+    "devcouncil_debug_start": _start,
+    "devcouncil_debug_breakpoints": _breakpoints,
+    "devcouncil_debug_control": _control,
+    "devcouncil_debug_inspect": _inspect,
+    "devcouncil_debug_evaluate": _evaluate,
+    "devcouncil_debug_trace": _trace,
+    "devcouncil_debug_stop": _stop,
+}
+
+
+async def dispatch(name: str, default_root: Path, arguments: dict) -> list[TextContent] | None:
+    handler = REGISTRY.get(name)
+    if handler is None:
+        return None
+    explicit = arguments.get("projectPath")
+    root = canonical_project_root(Path(explicit) if isinstance(explicit, str) and explicit else default_root)
+    try:
+        return await handler(root, arguments)
+    except PermissionError as exc:
+        return error_text(str(exc), code="debug_consent_required", tool=name)
+    except FileNotFoundError as exc:
+        return error_text(str(exc), code="not_found", tool=name)
+    except (KeyError, TypeError, ValueError, RuntimeError, TimeoutError) as exc:
+        return error_text(str(exc), code="debug_error", tool=name)

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

@@ -0,0 +1,70 @@
+"""Evidence read/write 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,
+    parse_cli_json,
+    required_string_argument,
+    run_cli_command,
+)
+
+
+async def handle_append_evidence(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
+    summary_text, arg_error = required_string_argument(arguments, "summary")
+    if arg_error:
+        return arg_error
+    assert task_id is not None and lease_token is not None
+    exit_code = arguments.get("exit_code", 0)
+    if not isinstance(exit_code, int) or isinstance(exit_code, bool):
+        return error_text("exit_code must be an integer", code="invalid_arguments")
+    cli_args = [
+        "evidence-append", task_id,
+        "--lease-token", lease_token,
+        "--command", command or "",
+        "--summary", summary_text or "",
+        "--exit-code", str(exit_code),
+        "--json",
+    ]
+    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_get_evidence(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
+    assert task_id is not None
+    command_filter = optional_string_argument(arguments, "command")
+    if command_filter == "":
+        return error_text("command must be a string", code="invalid_arguments", argument="command")
+    limit = int_argument(arguments, "limit", 20, minimum=1, maximum=100)
+    cli_args = ["evidence-list", task_id, "--limit", str(limit), "--json"]
+    if command_filter:
+        cli_args.extend(["--command", command_filter])
+    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/git.py

@@ -0,0 +1,99 @@
+"""Git diff MCP tool handlers."""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    CLI_TIMEOUT_SECONDS,
+    error_text,
+    is_git_repo,
+    json_text,
+    optional_string_argument,
+    optional_string_list_argument,
+    truncate_text,
+)
+from devcouncil.storage.db import Database
+from devcouncil.storage.repositories import TaskRepository
+
+
+async def git_diff(root: Path, paths: list[str], staged: bool) -> dict[str, object]:
+    """Compute a (optionally path-scoped, optionally staged) git diff."""
+    diff_args = ["git", "diff"]
+    numstat_args = ["git", "diff", "--numstat"]
+    namestatus_args = ["git", "diff", "--name-status"]
+    if staged:
+        for args in (diff_args, numstat_args, namestatus_args):
+            args.append("--cached")
+    if paths:
+        for args in (diff_args, numstat_args, namestatus_args):
+            args.append("--")
+            args.extend(paths)
+
+    def _run(args: list[str]) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            args, cwd=root, capture_output=True, text=True,
+            encoding="utf-8", errors="replace", timeout=CLI_TIMEOUT_SECONDS,
+        )
+
+    try:
+        loop = asyncio.get_event_loop()
+        diff_proc, numstat_proc, namestatus_proc = await asyncio.gather(
+            loop.run_in_executor(None, _run, diff_args),
+            loop.run_in_executor(None, _run, numstat_args),
+            loop.run_in_executor(None, _run, namestatus_args),
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return {"ok": False, "files": [], "unified_diff": "", "truncated": False, "error": str(exc)}
+
+    status_by_path: dict[str, str] = {}
+    for line in namestatus_proc.stdout.splitlines():
+        parts = line.split("\t")
+        if len(parts) >= 2:
+            status_by_path[parts[-1].replace("\\", "/")] = parts[0]
+
+    files: list[dict[str, object]] = []
+    for line in numstat_proc.stdout.splitlines():
+        parts = line.split("\t")
+        if len(parts) < 3:
+            continue
+        added_str, deleted_str, file_path = parts[0], parts[1], parts[-1]
+        file_path = file_path.replace("\\", "/")
+        files.append({
+            "path": file_path,
+            "status": status_by_path.get(file_path, "M"),
+            "additions": int(added_str) if added_str.isdigit() else 0,
+            "deletions": int(deleted_str) if deleted_str.isdigit() else 0,
+        })
+
+    unified_diff, truncated = truncate_text(diff_proc.stdout)
+    return {"ok": True, "files": files, "unified_diff": unified_diff, "truncated": truncated, "staged": staged}
+
+
+async def handle_get_diff(root: Path, db: Database | None, arguments: dict) -> list[TextContent]:
+    if not is_git_repo(root):
+        return error_text("get_diff requires a git repository.", code="not_a_git_repo")
+    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")
+    explicit_paths, arg_error = optional_string_list_argument(arguments, "paths")
+    if arg_error:
+        return arg_error
+    staged_value = arguments.get("staged", False)
+    if not isinstance(staged_value, bool):
+        return error_text("staged must be a boolean", code="invalid_arguments", argument="staged")
+    scope_paths: list[str] = list(explicit_paths)
+    if task_id and db:
+        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)
+        for planned in task.planned_files:
+            p = planned.path.replace("\\", "/")
+            if p not in scope_paths:
+                scope_paths.append(p)
+    return json_text(await git_diff(root, scope_paths, staged_value))

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

@@ -0,0 +1,36 @@
+"""Code-review graph context MCP tool handlers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    json_text,
+    run_cli_command,
+)
+
+
+async def handle_graph_context(root: Path, arguments: dict) -> list[TextContent]:
+    files = arguments.get("files", [])
+    if not isinstance(files, list):
+        files = []
+    file_args: list[str] = []
+    for item in files:
+        if isinstance(item, str) and item:
+            file_args.extend(["--file", item])
+    result = run_cli_command(["graph-context", "--json", *file_args], root)
+    if result.get("ok"):
+        try:
+            payload = json.loads(str(result.get("stdout") or "{}"))
+            return json_text(payload)
+        except json.JSONDecodeError:
+            pass
+    from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
+
+    context = CodeReviewGraphAdapter(root).get_context(
+        [file for file in files if isinstance(file, str)]
+    )
+    return [TextContent(type="text", text=context.model_dump_json(indent=2))]

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

@@ -0,0 +1,53 @@
+"""Agent handoff MCP tool handler."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    json_text,
+    parse_cli_json,
+    required_string_argument,
+    run_cli_command,
+)
+
+
+async def handle_handoff_agent(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
+    from_agent, arg_error = required_string_argument(arguments, "from_agent")
+    if arg_error:
+        return arg_error
+    to_agent, arg_error = required_string_argument(arguments, "to_agent")
+    if arg_error:
+        return arg_error
+    assert task_id is not None and lease_token is not None
+    cli_args = [
+        "handoff-leased", task_id,
+        "--lease-token", lease_token,
+        "--from", from_agent or "",
+        "--to", to_agent or "",
+        "--json",
+    ]
+    instruction = str(arguments.get("instruction") or "")
+    if instruction:
+        cli_args.extend(["--instruction", instruction])
+    payload, cli_error = parse_cli_json(run_cli_command(cli_args, root))
+    if cli_error:
+        return cli_error
+    assert payload is not None
+    if not payload.get("ok"):
+        from devcouncil.integrations.mcp.util import error_text
+        return error_text(
+            str(payload.get("error") or "handoff failed"),
+            code=str(payload.get("code") or "handoff_failed"),
+            task_id=task_id,
+        )
+    return json_text(payload)

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

@@ -0,0 +1,30 @@
+"""Knowledge selection MCP tool handlers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    json_text,
+    required_string_argument,
+    run_cli_command,
+)
+from devcouncil.knowledge.knowledge_select import select_knowledge_payload
+
+
+async def handle_select_knowledge(root: Path, arguments: dict) -> list[TextContent]:
+    goal, arg_error = required_string_argument(arguments, "goal")
+    if arg_error:
+        return arg_error
+    assert goal is not None
+    result = run_cli_command(["okf", "select", "--json", "--goal", goal], root)
+    if result.get("ok"):
+        try:
+            payload = json.loads(str(result.get("stdout") or "{}"))
+            return json_text(payload)
+        except json.JSONDecodeError:
+            pass
+    return json_text(select_knowledge_payload(root, goal))

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

@@ -0,0 +1,70 @@
+"""Task lease MCP tool handlers (release, renew, list)."""
+
+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_release_task(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
+    assert task_id is not None and lease_token is not None
+    payload, cli_error = parse_cli_json(
+        run_cli_command(["release", task_id, "--lease-token", lease_token, "--json"], root),
+    )
+    if cli_error:
+        return cli_error
+    assert payload is not None
+    return json_text(payload)
+
+
+async def handle_renew_lease(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
+    assert task_id is not None and lease_token is not None
+    ttl_value = arguments.get("ttl_seconds")
+    if ttl_value is not None and (not isinstance(ttl_value, int) or isinstance(ttl_value, bool)):
+        return error_text("ttl_seconds must be an integer", code="invalid_arguments", argument="ttl_seconds")
+    cli_args = ["lease", "renew", task_id, "--lease-token", lease_token, "--json"]
+    if isinstance(ttl_value, int) and not isinstance(ttl_value, bool):
+        cli_args.extend(["--ttl-seconds", str(ttl_value)])
+    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_list_leases(root: Path, db: object, arguments: dict) -> list[TextContent]:
+    del db  # routed through CLI service layer
+    active_only = arguments.get("active_only", True)
+    if not isinstance(active_only, bool):
+        return error_text("active_only must be a boolean", code="invalid_arguments", argument="active_only")
+    cli_args = ["lease", "list", "--json"]
+    if not active_only:
+        cli_args.append("--all")
+    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)