devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/idea/repo_tools.py

@@ -0,0 +1,1277 @@
+"""Composable repo tool surfaces for ideation and insight agent arms."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Literal
+
+from ..llm.repo_knowledge import load_repo_knowledge_index, write_repo_knowledge_index
+from ..stores.execution_store import ExecutionStore
+from .paths import get_idea_paths
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_REPOS_ROOT = Path(os.environ.get("DEVFLOW_REPOS_ROOT", "")) or Path.home() / "repos"
+
+_KEY_FILE_PATTERNS = {
+    "package.json",
+    "pyproject.toml",
+    "setup.py",
+    "setup.cfg",
+    "Cargo.toml",
+    "go.mod",
+    "Gemfile",
+    "Dockerfile",
+    "docker-compose.yml",
+    "docker-compose.yaml",
+    "Makefile",
+    "CMakeLists.txt",
+    ".env.example",
+    ".env.sample",
+    "requirements.txt",
+    "pom.xml",
+    "build.gradle",
+    "tsconfig.json",
+    "vite.config.ts",
+    "next.config.js",
+    "next.config.mjs",
+    "tailwind.config.js",
+    "tailwind.config.ts",
+    "webpack.config.js",
+    "angular.json",
+    "nuxt.config.ts",
+    "svelte.config.js",
+    "remix.config.js",
+    "astro.config.mjs",
+}
+
+_STACK_INDICATORS: dict[str, dict[str, str]] = {
+    "package.json": {"stack": "node", "framework": "detect_from_deps"},
+    "pyproject.toml": {"stack": "python", "framework": "detect_from_deps"},
+    "setup.py": {"stack": "python", "framework": "unknown"},
+    "Cargo.toml": {"stack": "rust", "framework": "unknown"},
+    "go.mod": {"stack": "go", "framework": "unknown"},
+    "Gemfile": {"stack": "ruby", "framework": "detect_from_deps"},
+    "pom.xml": {"stack": "java", "framework": "maven"},
+    "build.gradle": {"stack": "java", "framework": "gradle"},
+}
+
+_FRONTEND_FRAMEWORK_MARKERS = {
+    "next.config.js": "nextjs",
+    "next.config.mjs": "nextjs",
+    "nuxt.config.ts": "nuxt",
+    "svelte.config.js": "svelte",
+    "remix.config.js": "remix",
+    "astro.config.mjs": "astro",
+    "angular.json": "angular",
+    "vite.config.ts": "vite",
+}
+
+_ACTIVE_REPO_ROOT: Path | None = None
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _repos_root() -> Path:
+    """Return the repos root, respecting DEVFLOW_REPOS_ROOT env override."""
+    env = os.environ.get("DEVFLOW_REPOS_ROOT", "").strip()
+    if env:
+        return Path(env)
+    return Path.home() / "repos"
+
+
+@contextmanager
+def activate_repo_tools(repo_root: Path):
+    """Bind the ideation tool surface to the active workspace repo."""
+    global _ACTIVE_REPO_ROOT
+    previous = _ACTIVE_REPO_ROOT
+    _ACTIVE_REPO_ROOT = repo_root.resolve()
+    try:
+        yield
+    finally:
+        _ACTIVE_REPO_ROOT = previous
+
+
+def _require_active_repo_root() -> Path:
+    if _ACTIVE_REPO_ROOT is None:
+        raise RuntimeError("Ideation repo tools are not active outside an ideation agent run.")
+    return _ACTIVE_REPO_ROOT
+
+
+def _resolve_within_repo(repo_root: Path, path: str | None = None) -> Path:
+    target = repo_root if not path or path == "." else repo_root / path
+    try:
+        resolved = target.resolve()
+        resolved.relative_to(repo_root.resolve())
+    except ValueError as exc:
+        raise ValueError(f"path must stay within the active repo: {path!r}") from exc
+    return resolved
+
+
+def _directory_entries(target: Path, *, max_entries: int = 200) -> list[dict[str, str]]:
+    entries: list[dict[str, str]] = []
+    try:
+        for item in sorted(target.iterdir()):
+            if item.name == ".git":
+                continue
+            entries.append({
+                "name": item.name,
+                "type": "dir" if item.is_dir() else "file",
+            })
+            if len(entries) >= max_entries:
+                break
+    except OSError:
+        pass
+    return entries
+
+
+def _parse_repo_ref(repo_ref: str) -> tuple[str, str]:
+    """Extract (owner, repo_name) from a GitHub URL or owner/repo string."""
+    # https://github.com/owner/repo or git@github.com:owner/repo.git
+    m = re.match(r"(?:https?://github\.com/|git@github\.com:)([^/]+)/([^/.]+?)(?:\.git)?/?$", repo_ref)
+    if m:
+        return m.group(1), m.group(2)
+    # owner/repo
+    m = re.match(r"^([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+)$", repo_ref)
+    if m:
+        return m.group(1), m.group(2)
+    raise ValueError(f"Cannot parse repo_ref: {repo_ref!r}. Expected GitHub URL or owner/repo.")
+
+
+def _local_candidates(owner: str, repo_name: str, suggested_local_name: str | None = None) -> list[Path]:
+    """Return candidate local paths to check for an existing clone, in priority order."""
+    root = _repos_root()
+    candidates = []
+    if suggested_local_name:
+        candidates.append(root / suggested_local_name)
+    candidates.append(root / repo_name)
+    candidates.append(root / f"{owner}_{repo_name}")
+    candidates.append(root / f"{owner}-{repo_name}")
+    return candidates
+
+
+def _top_level_inventory(local_path: Path, max_entries: int = 200) -> list[dict[str, str]]:
+    """Return top-level files/dirs with type annotation."""
+    entries: list[dict[str, str]] = []
+    try:
+        for item in sorted(local_path.iterdir()):
+            if item.name.startswith(".") and item.name in {".git"}:
+                continue
+            entries.append({
+                "name": item.name,
+                "type": "dir" if item.is_dir() else "file",
+            })
+            if len(entries) >= max_entries:
+                break
+    except OSError:
+        pass
+    return entries
+
+
+def _find_key_files(local_path: Path) -> list[str]:
+    """Return key candidate files found at repo root."""
+    found = []
+    for name in sorted(_KEY_FILE_PATTERNS):
+        if (local_path / name).exists():
+            found.append(name)
+    return found
+
+
+# ---------------------------------------------------------------------------
+# Tool 1: acquire_and_inventory_repo
+# ---------------------------------------------------------------------------
+
+
+def acquire_and_inventory_repo(
+    *,
+    repo_ref: str,
+    suggested_local_name: str | None = None,
+    mode: Literal["frontend", "backend", "generic"] | None = None,
+) -> dict[str, Any]:
+    """Acquire a GitHub repo (reuse local clone or clone via gh) and return inventory.
+
+    Returns structured dict with local_path, repo_ref, cloned, inventory, key_files.
+    Raises on clone failure — no fake success.
+    """
+    owner, repo_name = _parse_repo_ref(repo_ref)
+
+    # Check for existing local clone
+    for candidate in _local_candidates(owner, repo_name, suggested_local_name):
+        if candidate.is_dir() and (candidate / ".git").is_dir():
+            return {
+                "local_path": str(candidate),
+                "repo_ref": f"{owner}/{repo_name}",
+                "cloned": False,
+                "inventory": _top_level_inventory(candidate),
+                "key_files": _find_key_files(candidate),
+            }
+
+    # Clone via gh
+    if not shutil.which("gh"):
+        raise RuntimeError("GitHub CLI (gh) is not installed or not on PATH. Cannot clone repo.")
+
+    root = _repos_root()
+    root.mkdir(parents=True, exist_ok=True)
+    target_name = suggested_local_name or repo_name
+    target_path = root / target_name
+
+    result = subprocess.run(
+        ["gh", "repo", "clone", f"{owner}/{repo_name}", str(target_path)],
+        capture_output=True,
+        text=True,
+        timeout=300,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"gh repo clone failed (rc={result.returncode}):\n"
+            f"stdout: {result.stdout.strip()}\n"
+            f"stderr: {result.stderr.strip()}"
+        )
+
+    return {
+        "local_path": str(target_path),
+        "repo_ref": f"{owner}/{repo_name}",
+        "cloned": True,
+        "inventory": _top_level_inventory(target_path),
+        "key_files": _find_key_files(target_path),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Tool 2: inspect_repo_surface
+# ---------------------------------------------------------------------------
+
+
+def _detect_stack_and_frameworks(local_path: Path) -> tuple[list[str], list[str]]:
+    """Detect stacks and frameworks from key files."""
+    stacks: list[str] = []
+    frameworks: list[str] = []
+
+    for filename, info in _STACK_INDICATORS.items():
+        if (local_path / filename).exists():
+            if info["stack"] not in stacks:
+                stacks.append(info["stack"])
+
+    for filename, fw in _FRONTEND_FRAMEWORK_MARKERS.items():
+        if (local_path / filename).exists():
+            if fw not in frameworks:
+                frameworks.append(fw)
+
+    # Detect from package.json deps
+    pkg_json = local_path / "package.json"
+    if pkg_json.exists():
+        try:
+            import json
+            pkg = json.loads(pkg_json.read_text(encoding="utf-8"))
+            all_deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+            for dep, fw in [
+                ("react", "react"), ("vue", "vue"), ("svelte", "svelte"),
+                ("@angular/core", "angular"), ("express", "express"),
+                ("fastify", "fastify"), ("next", "nextjs"), ("nuxt", "nuxt"),
+                ("remix", "remix"), ("django", "django"), ("flask", "flask"),
+                ("tailwindcss", "tailwind"),
+            ]:
+                if dep in all_deps and fw not in frameworks:
+                    frameworks.append(fw)
+        except (OSError, ValueError):
+            pass
+
+    # Detect from pyproject.toml deps
+    pyproj = local_path / "pyproject.toml"
+    if pyproj.exists():
+        try:
+            content = pyproj.read_text(encoding="utf-8")
+            for marker, fw in [
+                ("django", "django"), ("flask", "flask"), ("fastapi", "fastapi"),
+                ("starlette", "starlette"), ("streamlit", "streamlit"),
+            ]:
+                if marker in content.lower() and fw not in frameworks:
+                    frameworks.append(fw)
+        except OSError:
+            pass
+
+    return stacks, frameworks
+
+
+def _detect_patterns(local_path: Path) -> dict[str, Any]:
+    """Detect auth, API, env, and deployment patterns."""
+    auth_pattern: str | None = None
+    api_pattern: str | None = None
+    env_files: list[str] = []
+    deployment_files: list[str] = []
+
+    # Auth detection
+    auth_dirs = ["auth", "authentication", "lib/auth", "src/auth", "app/auth", "middleware/auth"]
+    for d in auth_dirs:
+        if (local_path / d).exists():
+            auth_pattern = d
+            break
+
+    # API pattern detection
+    api_dirs = ["api", "routes", "src/api", "app/api", "src/routes", "endpoints", "controllers"]
+    for d in api_dirs:
+        if (local_path / d).exists():
+            api_pattern = d
+            break
+
+    # Env files
+    for name in sorted(local_path.iterdir()) if local_path.is_dir() else []:
+        if name.name.startswith(".env") and name.is_file():
+            env_files.append(name.name)
+
+    # Deployment files
+    deploy_patterns = [
+        "Dockerfile", "docker-compose.yml", "docker-compose.yaml",
+        "fly.toml", "vercel.json", "netlify.toml", "railway.json",
+        "render.yaml", "Procfile", "app.yaml", "serverless.yml",
+        "terraform", "k8s", "kubernetes", ".github/workflows",
+        "Jenkinsfile", ".circleci",
+    ]
+    for pat in deploy_patterns:
+        p = local_path / pat
+        if p.exists():
+            deployment_files.append(pat)
+
+    return {
+        "auth_pattern": auth_pattern,
+        "api_pattern": api_pattern,
+        "env_files": env_files,
+        "deployment_files": deployment_files,
+    }
+
+
+def inspect_repo_surface(
+    *,
+    local_path: str,
+    mode: Literal["frontend", "backend", "generic"] = "generic",
+) -> dict[str, Any]:
+    """Inspect a local repo for stack, framework, auth, API, env, and deployment clues.
+
+    Returns structured JSON summary.
+    """
+    repo = Path(local_path)
+    if not repo.is_dir():
+        raise FileNotFoundError(f"Repo path does not exist: {local_path}")
+
+    stacks, frameworks = _detect_stack_and_frameworks(repo)
+    patterns = _detect_patterns(repo)
+    key_files = _find_key_files(repo)
+
+    notes: list[str] = []
+    if mode == "frontend" and not any(f in frameworks for f in ["react", "vue", "svelte", "angular", "nextjs", "nuxt"]):
+        notes.append("No recognized frontend framework detected despite frontend mode.")
+    if mode == "backend" and not any(f in frameworks for f in ["express", "fastify", "django", "flask", "fastapi"]):
+        notes.append("No recognized backend framework detected despite backend mode.")
+
+    return {
+        "local_path": local_path,
+        "mode": mode,
+        "stack": stacks,
+        "frameworks": frameworks,
+        "auth_pattern": patterns["auth_pattern"],
+        "api_pattern": patterns["api_pattern"],
+        "env_files": patterns["env_files"],
+        "deployment_files": patterns["deployment_files"],
+        "key_files": key_files,
+        "notes": notes,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Tool 3: search_repo
+# ---------------------------------------------------------------------------
+
+
+def search_repo(
+    *,
+    local_path: str,
+    query: str,
+    glob: str | None = None,
+    max_results: int = 50,
+) -> dict[str, Any]:
+    """Search a local repo using rg (ripgrep) with grep fallback.
+
+    Returns structured matches with file path, line numbers, and snippets.
+    """
+    repo = Path(local_path)
+    if not repo.is_dir():
+        raise FileNotFoundError(f"Repo path does not exist: {local_path}")
+
+    matches: list[dict[str, Any]] = []
+
+    if shutil.which("rg"):
+        cmd = ["rg", "--no-heading", "--line-number", "--max-count", str(max_results), "--color", "never"]
+        if glob:
+            cmd.extend(["--glob", glob])
+        cmd.extend([query, str(repo)])
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+        # rg returns 1 on no match, 2 on error
+        if result.returncode == 2:
+            raise RuntimeError(f"rg search error: {result.stderr.strip()}")
+        for line in result.stdout.strip().splitlines():
+            # Format: /path/to/file:line_num:content
+            parts = line.split(":", 2)
+            if len(parts) >= 3:
+                file_path = parts[0]
+                # Make path relative to repo root
+                try:
+                    rel = str(Path(file_path).relative_to(repo))
+                except ValueError:
+                    rel = file_path
+                matches.append({
+                    "file": rel,
+                    "line": int(parts[1]) if parts[1].isdigit() else parts[1],
+                    "snippet": parts[2],
+                })
+                if len(matches) >= max_results:
+                    break
+    elif shutil.which("grep"):
+        cmd = ["grep", "-rn", "--color=never"]
+        if glob:
+            cmd.extend(["--include", glob])
+        cmd.extend([query, str(repo)])
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+        if result.returncode == 2:
+            raise RuntimeError(f"grep search error: {result.stderr.strip()}")
+        for line in result.stdout.strip().splitlines():
+            parts = line.split(":", 2)
+            if len(parts) >= 3:
+                try:
+                    rel = str(Path(parts[0]).relative_to(repo))
+                except ValueError:
+                    rel = parts[0]
+                matches.append({
+                    "file": rel,
+                    "line": int(parts[1]) if parts[1].isdigit() else parts[1],
+                    "snippet": parts[2],
+                })
+                if len(matches) >= max_results:
+                    break
+    else:
+        raise RuntimeError("Neither rg (ripgrep) nor grep is available on PATH.")
+
+    return {
+        "local_path": local_path,
+        "query": query,
+        "glob": glob,
+        "match_count": len(matches),
+        "matches": matches,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Tool 4: read_repo_file
+# ---------------------------------------------------------------------------
+
+
+def read_repo_file(
+    *,
+    local_path: str,
+    file_path: str,
+    start_line: int | None = None,
+    end_line: int | None = None,
+) -> dict[str, Any]:
+    """Read a file from a local repo.
+
+    Returns text content and path metadata.
+    Paths are resolved relative to local_path if not absolute.
+    """
+    repo = Path(local_path)
+    target = Path(file_path)
+
+    # Resolve relative paths against repo root
+    if not target.is_absolute():
+        target = repo / target
+
+    # Security: ensure target is within repo
+    try:
+        target.resolve().relative_to(repo.resolve())
+    except ValueError:
+        raise ValueError(f"file_path must be within the repo: {file_path!r} is outside {local_path!r}")
+
+    if not target.is_file():
+        raise FileNotFoundError(f"File not found: {target}")
+
+    try:
+        content = target.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        raise ValueError(f"File is not valid UTF-8 text: {target}")
+
+    lines = content.splitlines(keepends=True)
+    total_lines = len(lines)
+
+    if start_line is not None or end_line is not None:
+        s = (start_line or 1) - 1  # 1-indexed to 0-indexed
+        e = end_line or total_lines
+        lines = lines[s:e]
+        content = "".join(lines)
+
+    try:
+        rel = str(target.relative_to(repo))
+    except ValueError:
+        rel = str(target)
+
+    return {
+        "local_path": local_path,
+        "file_path": rel,
+        "absolute_path": str(target),
+        "total_lines": total_lines,
+        "returned_lines": len(lines),
+        "start_line": start_line or 1,
+        "end_line": end_line or total_lines,
+        "content": content,
+    }
+
+
+def project_overview(
+    *,
+    focus: Literal["generic", "architecture", "product", "codebase"] = "generic",
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    surface = inspect_repo_surface(local_path=str(repo_root), mode="generic")
+    return {
+        "repo_root": str(repo_root),
+        "focus": focus,
+        "top_level_entries": _top_level_inventory(repo_root),
+        "key_files": surface["key_files"],
+        "stack": surface["stack"],
+        "frameworks": surface["frameworks"],
+        "auth_surface": surface["auth_pattern"],
+        "api_surface": surface["api_pattern"],
+        "env_files": surface["env_files"],
+        "deployment_files": surface["deployment_files"],
+        "notes": surface["notes"],
+    }
+
+
+def read_repo_knowledge_index(
+    *,
+    refresh: bool = False,
+    max_files: int = 2_000,
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    payload = (
+        write_repo_knowledge_index(repo_root, max_files=max_files)
+        if refresh
+        else load_repo_knowledge_index(repo_root)
+    )
+    if payload is None:
+        payload = write_repo_knowledge_index(repo_root, max_files=max_files)
+    return {
+        "repo_root": str(repo_root),
+        "schema_version": payload.get("schema_version"),
+        "generated_at": payload.get("generated_at"),
+        "git_head": payload.get("git_head"),
+        "indexed_file_count": payload.get("indexed_file_count"),
+        "skipped_file_count": payload.get("skipped_file_count"),
+        "directories": payload.get("directories") or [],
+        "story_planes": payload.get("story_planes") or [],
+        "registry": payload.get("registry") or {},
+        "search_hints": payload.get("search_hints") or {},
+        "files": payload.get("files") or [],
+    }
+
+
+def list_directory(
+    *,
+    path: str = ".",
+    max_entries: int = 200,
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    target = _resolve_within_repo(repo_root, path)
+    if not target.is_dir():
+        raise FileNotFoundError(f"Directory not found: {path}")
+    relative_path = "." if target == repo_root else str(target.relative_to(repo_root))
+    entries = _directory_entries(target, max_entries=max_entries)
+    return {
+        "repo_root": str(repo_root),
+        "path": relative_path,
+        "absolute_path": str(target),
+        "entry_count": len(entries),
+        "entries": entries,
+    }
+
+
+def search_code(
+    *,
+    query: str,
+    glob: str | None = None,
+    max_results: int = 50,
+    path: str = ".",
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    target = _resolve_within_repo(repo_root, path)
+    if not target.exists():
+        raise FileNotFoundError(f"Path not found: {path}")
+    if target.is_file():
+        search_root = target.parent
+        effective_glob = target.name
+    else:
+        search_root = target
+        effective_glob = glob
+    result = search_repo(
+        local_path=str(search_root),
+        query=query,
+        glob=effective_glob,
+        max_results=max_results,
+    )
+    return {
+        "repo_root": str(repo_root),
+        "path": "." if target == repo_root else str(target.relative_to(repo_root)),
+        "query": result["query"],
+        "glob": glob,
+        "match_count": result["match_count"],
+        "matches": result["matches"],
+    }
+
+
+def read_file(
+    *,
+    file_path: str,
+    start_line: int | None = None,
+    end_line: int | None = None,
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    result = read_repo_file(
+        local_path=str(repo_root),
+        file_path=file_path,
+        start_line=start_line,
+        end_line=end_line,
+    )
+    return {
+        "repo_root": str(repo_root),
+        "file_path": result["file_path"],
+        "absolute_path": result["absolute_path"],
+        "total_lines": result["total_lines"],
+        "returned_lines": result["returned_lines"],
+        "start_line": result["start_line"],
+        "end_line": result["end_line"],
+        "content": result["content"],
+    }
+
+
+def read_docs_context(
+    *,
+    query: str,
+    max_results: int = 8,
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    docs_root = repo_root / "ai_docs" / "context"
+    if not docs_root.exists():
+        raise FileNotFoundError(f"Docs context not found: {docs_root}")
+    result = search_repo(
+        local_path=str(docs_root),
+        query=query,
+        glob="*.md",
+        max_results=max_results,
+    )
+    return {
+        "repo_root": str(repo_root),
+        "docs_root": str(docs_root),
+        "query": result["query"],
+        "match_count": result["match_count"],
+        "matches": result["matches"],
+    }
+
+
+def read_recent_artifacts(
+    *,
+    limit: int = 10,
+    kind: str | None = None,
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    db_path = repo_root / ".devflow" / "execution.sqlite"
+    if not db_path.exists():
+        raise FileNotFoundError(f"Execution store not found: {db_path}")
+    store = ExecutionStore(db_path)
+    sql = (
+        "SELECT artifact_id, run_id, node_exec_id, kind, uri, metadata_json, created_at, updated_at "
+        "FROM artifacts"
+    )
+    params: list[Any] = []
+    if kind:
+        sql += " WHERE kind=?"
+        params.append(kind)
+    sql += " ORDER BY created_at DESC LIMIT ?"
+    params.append(max(1, int(limit)))
+    with store._connect() as conn:
+        rows = conn.execute(sql, tuple(params)).fetchall()
+    artifacts: list[dict[str, Any]] = []
+    for row in rows:
+        try:
+            metadata = json.loads(str(row["metadata_json"] or "{}"))
+        except Exception:
+            metadata = {}
+        artifacts.append(
+            {
+                "artifact_id": str(row["artifact_id"]),
+                "run_id": str(row["run_id"]),
+                "node_exec_id": None if row["node_exec_id"] is None else str(row["node_exec_id"]),
+                "kind": str(row["kind"]),
+                "uri": str(row["uri"]),
+                "metadata": metadata if isinstance(metadata, dict) else {},
+                "created_at": int(row["created_at"]),
+                "updated_at": int(row["updated_at"]),
+            }
+        )
+    return {
+        "repo_root": str(repo_root),
+        "db_path": str(db_path),
+        "artifact_count": len(artifacts),
+        "artifacts": artifacts,
+    }
+
+
+def inspect_routes(
+    *,
+    path: str = ".",
+    max_results: int = 20,
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    target = _resolve_within_repo(repo_root, path)
+    if not target.exists():
+        raise FileNotFoundError(f"Path not found: {path}")
+    route_globs = ["*route*", "*routes*", "*router*", "*api*", "*endpoint*", "*controller*"]
+    route_queries = ["router", "route", "endpoint", "controller", "APIRouter", "FastAPI", "Blueprint", "express.Router", "app.get", "app.post", "app.put", "app.delete", "app.patch"]
+    matches: list[dict[str, Any]] = []
+    seen: set[tuple[str, Any, str]] = set()
+    search_root = target if target.is_dir() else target.parent
+    for glob in route_globs:
+        for query in route_queries:
+            result = search_repo(
+                local_path=str(search_root),
+                query=query,
+                glob=glob if target.is_dir() else target.name,
+                max_results=max_results,
+            )
+            for item in result["matches"]:
+                key = (str(item.get("file")), item.get("line"), str(item.get("snippet")))
+                if key in seen:
+                    continue
+                seen.add(key)
+                matches.append(item)
+                if len(matches) >= max_results:
+                    break
+            if len(matches) >= max_results:
+                break
+        if len(matches) >= max_results:
+            break
+    return {
+        "repo_root": str(repo_root),
+        "path": "." if target == repo_root else str(target.relative_to(repo_root)),
+        "match_count": len(matches),
+        "matches": matches,
+    }
+
+
+def inspect_data_model(
+    *,
+    path: str = ".",
+    max_results: int = 20,
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    target = _resolve_within_repo(repo_root, path)
+    if not target.exists():
+        raise FileNotFoundError(f"Path not found: {path}")
+    model_queries = ["model", "schema", "entity", "table", "migration", "sqlalchemy", "BaseModel", "dataclass"]
+    matches: list[dict[str, Any]] = []
+    seen: set[tuple[str, Any, str]] = set()
+    search_root = target if target.is_dir() else target.parent
+    effective_glob = None if target.is_dir() else target.name
+    for query in model_queries:
+        result = search_repo(
+            local_path=str(search_root),
+            query=query,
+            glob=effective_glob,
+            max_results=max_results,
+        )
+        for item in result["matches"]:
+            key = (str(item.get("file")), item.get("line"), str(item.get("snippet")))
+            if key in seen:
+                continue
+            seen.add(key)
+            matches.append(item)
+            if len(matches) >= max_results:
+                break
+        if len(matches) >= max_results:
+            break
+    return {
+        "repo_root": str(repo_root),
+        "path": "." if target == repo_root else str(target.relative_to(repo_root)),
+        "match_count": len(matches),
+        "matches": matches,
+    }
+
+
+def devflow_create_idea(
+    *,
+    idea_id: str,
+    summary: str,
+    project_id: str | None = None,
+    problem_statement: str | None = None,
+    target_users: list[str] | None = None,
+    desired_outcomes: list[str] | None = None,
+    in_scope: list[str] | None = None,
+    out_of_scope: list[str] | None = None,
+    constraints: list[str] | None = None,
+    acceptance_criteria: list[str] | None = None,
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    normalized_idea_id = str(idea_id).strip()
+    if not normalized_idea_id:
+        raise ValueError("idea_id is required")
+    payload: dict[str, Any] = {
+        "idea_id": normalized_idea_id,
+        "project_id": str(project_id).strip() or None if project_id is not None else None,
+        "title": str(summary).strip(),
+        "summary": str(summary).strip(),
+        "problem_statement": str(problem_statement or "").strip(),
+        "target_users": [str(item).strip() for item in (target_users or []) if str(item).strip()],
+        "desired_outcomes": [str(item).strip() for item in (desired_outcomes or []) if str(item).strip()],
+        "initial_scope": {
+            "in_scope": [str(item).strip() for item in (in_scope or []) if str(item).strip()],
+            "out_of_scope": [str(item).strip() for item in (out_of_scope or []) if str(item).strip()],
+        },
+        "constraints": [str(item).strip() for item in (constraints or []) if str(item).strip()],
+        "acceptance_criteria": [str(item).strip() for item in (acceptance_criteria or []) if str(item).strip()],
+        "latest_message": str(summary).strip(),
+    }
+    idea_path = get_idea_paths(repo_root, idea_id=normalized_idea_id).idea_dir / "idea.json"
+    idea_path.parent.mkdir(parents=True, exist_ok=True)
+    idea_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+    store = ExecutionStore(repo_root / ".devflow" / "execution.sqlite")
+    run = store.start_run(
+        kind="ideation_arm_devflow_create_idea",
+        repo_root=repo_root,
+        args={"idea_id": normalized_idea_id, "project_id": payload["project_id"]},
+    )
+    queue_id = store.enqueue_idea_creation_task(
+        project_id=payload["project_id"],
+        enqueue_run_id=run.run_id,
+        idea_id=normalized_idea_id,
+        title=str(payload["title"]),
+        idea_payload_path=str(idea_path),
+    )
+    return {
+        "repo_root": str(repo_root),
+        "run_id": run.run_id,
+        "idea_id": normalized_idea_id,
+        "idea_path": str(idea_path),
+        "idea_creation_queue_id": queue_id,
+        "status": "queued",
+    }
+
+
+def devflow_generate_stories(
+    *,
+    idea_id: str,
+    project_id: str | None = None,
+    candidate_planes: list[str] | None = None,
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    normalized_idea_id = str(idea_id).strip()
+    if not normalized_idea_id:
+        raise ValueError("idea_id is required")
+    idea_path = get_idea_paths(repo_root, idea_id=normalized_idea_id).idea_dir / "idea.json"
+    if not idea_path.exists():
+        raise FileNotFoundError(f"Idea payload not found: {idea_path}")
+    payload = json.loads(idea_path.read_text(encoding="utf-8"))
+    title = str(payload.get("title") or payload.get("summary") or normalized_idea_id).strip() or normalized_idea_id
+    resolved_project_id = str(project_id).strip() or None if project_id is not None else (str(payload.get("project_id") or "").strip() or None)
+    store = ExecutionStore(repo_root / ".devflow" / "execution.sqlite")
+    run = store.start_run(
+        kind="ideation_arm_devflow_generate_stories",
+        repo_root=repo_root,
+        args={"idea_id": normalized_idea_id, "project_id": resolved_project_id, "candidate_planes": candidate_planes or []},
+    )
+    queue_id = store.enqueue_idea_task(
+        project_id=resolved_project_id,
+        enqueue_run_id=run.run_id,
+        idea_id=normalized_idea_id,
+        title=title,
+        idea_payload_path=str(idea_path),
+        candidate_planes=candidate_planes or [],
+    )
+    return {
+        "repo_root": str(repo_root),
+        "run_id": run.run_id,
+        "idea_id": normalized_idea_id,
+        "idea_path": str(idea_path),
+        "idea_queue_id": queue_id,
+        "status": "queued",
+        "candidate_planes": list(candidate_planes or []),
+    }
+
+
+def devflow_kick_queue(
+    *,
+    project_id: str,
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    normalized_project_id = str(project_id).strip()
+    if not normalized_project_id:
+        raise ValueError("project_id is required")
+    cmd = ["devflow", "worker", "start", "--project", normalized_project_id, "--once"]
+    result = subprocess.run(
+        cmd,
+        cwd=str(repo_root),
+        capture_output=True,
+        text=True,
+        timeout=300,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            "devflow worker start --once failed: "
+            f"rc={result.returncode} stdout={result.stdout.strip()} stderr={result.stderr.strip()}"
+        )
+    return {
+        "repo_root": str(repo_root),
+        "project_id": normalized_project_id,
+        "command": cmd,
+        "status": "completed",
+        "stdout": result.stdout.strip(),
+    }
+
+
+def devflow_status(
+    *,
+    project_id: str | None = None,
+) -> dict[str, Any]:
+    repo_root = _require_active_repo_root()
+    db_path = repo_root / ".devflow" / "execution.sqlite"
+    if not db_path.exists():
+        raise FileNotFoundError(f"Execution store not found: {db_path}")
+    store = ExecutionStore(db_path)
+    where = ""
+    params: list[Any] = []
+    if project_id is not None and str(project_id).strip():
+        where = " WHERE project_id=?"
+        params.append(str(project_id).strip())
+    queues: dict[str, dict[str, int]] = {}
+    with store._connect() as conn:
+        for table, key in [
+            ("scope_queue", "scope"),
+            ("idea_creation_queue", "idea_creation"),
+            ("idea_queue", "idea"),
+            ("story_queue", "story"),
+            ("source_doc_mutation_queue", "source_doc_mutation"),
+        ]:
+            rows = conn.execute(
+                f"SELECT status, COUNT(*) AS total FROM {table}{where} GROUP BY status",
+                tuple(params),
+            ).fetchall()
+            counts = {str(row["status"]): int(row["total"]) for row in rows}
+            queues[key] = {
+                "queued": int(counts.get("queued", 0)),
+                "claimed": int(counts.get("claimed", 0)),
+                "in_progress": int(counts.get("in_progress", 0)),
+                "completed": int(counts.get("completed", 0)),
+                "failed": int(counts.get("failed", 0)),
+                "total": sum(counts.values()),
+            }
+    return {
+        "repo_root": str(repo_root),
+        "project_id": None if project_id is None else str(project_id).strip() or None,
+        "queues": queues,
+    }
+
+
+def propose_idea(
+    *,
+    idea_id: str,
+    summary: str,
+    project_id: str | None = None,
+    problem_statement: str | None = None,
+    target_users: list[str] | None = None,
+    desired_outcomes: list[str] | None = None,
+    in_scope: list[str] | None = None,
+    out_of_scope: list[str] | None = None,
+    constraints: list[str] | None = None,
+    acceptance_criteria: list[str] | None = None,
+) -> dict[str, Any]:
+    payload = {
+        "idea_id": str(idea_id).strip() or "idea",
+        "project_id": str(project_id).strip() or None if project_id is not None else None,
+        "summary": str(summary).strip(),
+        "problem_statement": str(problem_statement or "").strip(),
+        "target_users": [str(item).strip() for item in (target_users or []) if str(item).strip()],
+        "desired_outcomes": [str(item).strip() for item in (desired_outcomes or []) if str(item).strip()],
+        "initial_scope": {
+            "in_scope": [str(item).strip() for item in (in_scope or []) if str(item).strip()],
+            "out_of_scope": [str(item).strip() for item in (out_of_scope or []) if str(item).strip()],
+        },
+        "constraints": [str(item).strip() for item in (constraints or []) if str(item).strip()],
+        "acceptance_criteria": [str(item).strip() for item in (acceptance_criteria or []) if str(item).strip()],
+    }
+    missing_fields: list[str] = []
+    for key in ("summary", "target_users", "desired_outcomes", "constraints", "acceptance_criteria"):
+        if payload.get(key) in (None, "", [], {}):
+            missing_fields.append(key)
+    if not list((payload.get("initial_scope") or {}).get("in_scope") or []):
+        missing_fields.append("initial_scope")
+    decision = "sufficient" if not missing_fields else "too_thin"
+    preview = {
+        "decision": decision,
+        "passed": decision == "sufficient",
+        "rationale": "The idea is specific enough to move into DevFlow." if decision == "sufficient" else "The idea is still too thin to move into DevFlow cleanly.",
+        "missing_fields": missing_fields,
+        "follow_up": None if decision == "sufficient" else f"This is still too thin to build cleanly. Biggest gap: {missing_fields[0]}.",
+    }
+    return {
+        "idea_id": payload["idea_id"],
+        "project_id": payload["project_id"],
+        "summary": payload["summary"],
+        "preview": preview,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Tool specs by arm
+# ---------------------------------------------------------------------------
+
+_SHARED_READ_TOOL_SPECS: list[dict[str, Any]] = [
+    {
+        "name": "project_overview",
+        "description": "Summarize the active project at a high level, including top-level structure, stack signals, key files, and major surfaces relevant to the current question.",
+        "parameters": {
+            "focus": {
+                "type": "string",
+                "required": False,
+                "enum": ["generic", "architecture", "product", "codebase"],
+                "description": "Optional lens for the summary.",
+            },
+        },
+    },
+    {
+        "name": "read_repo_knowledge_index",
+        "description": (
+            "Read or refresh the fast PageIndex-style repo knowledge index: directory map, "
+            "key files, story-plane anchors, registry canonicals, and search hints."
+        ),
+        "parameters": {
+            "refresh": {"type": "boolean", "required": False, "description": "Refresh the index before reading it."},
+            "max_files": {
+                "type": "integer",
+                "required": False,
+                "description": "Maximum files to summarize during refresh.",
+            },
+        },
+    },
+    {
+        "name": "search_code",
+        "description": "Search the active project for code or text matches and return file paths, line numbers, and snippets.",
+        "parameters": {
+            "query": {"type": "string", "required": True, "description": "Search pattern (regex supported)"},
+            "path": {"type": "string", "required": False, "description": "Optional file or directory path relative to the active repo root."},
+            "glob": {"type": "string", "required": False, "description": "File glob filter (e.g. '*.py')"},
+            "max_results": {"type": "integer", "required": False, "description": "Max matches to return (default 50)"},
+        },
+    },
+    {
+        "name": "read_file",
+        "description": "Read a file from the active project. Supports line range selection.",
+        "parameters": {
+            "file_path": {"type": "string", "required": True, "description": "File path relative to the active repo root."},
+            "start_line": {"type": "integer", "required": False, "description": "First line to read (1-indexed)"},
+            "end_line": {"type": "integer", "required": False, "description": "Last line to read (inclusive)"},
+        },
+    },
+    {
+        "name": "read_docs_context",
+        "description": "Search the repo's docs context for relevant documentation matches.",
+        "parameters": {
+            "query": {"type": "string", "required": True, "description": "Search pattern for docs context."},
+            "max_results": {"type": "integer", "required": False, "description": "Max matches to return (default 8)"},
+        },
+    },
+    {
+        "name": "read_recent_artifacts",
+        "description": "Read the most recent execution artifacts from the local DevFlow execution store.",
+        "parameters": {
+            "limit": {"type": "integer", "required": False, "description": "Max artifacts to return (default 10)."},
+            "kind": {"type": "string", "required": False, "description": "Optional artifact kind filter."},
+        },
+    },
+    {
+        "name": "inspect_routes",
+        "description": "Inspect likely route, API, controller, or endpoint surfaces in the active repo.",
+        "parameters": {
+            "path": {"type": "string", "required": False, "description": "Optional file or directory path relative to the active repo root."},
+            "max_results": {"type": "integer", "required": False, "description": "Max matches to return (default 20)."},
+        },
+    },
+    {
+        "name": "inspect_data_model",
+        "description": "Inspect likely data-model, schema, entity, migration, or table definitions in the active repo.",
+        "parameters": {
+            "path": {"type": "string", "required": False, "description": "Optional file or directory path relative to the active repo root."},
+            "max_results": {"type": "integer", "required": False, "description": "Max matches to return (default 20)."},
+        },
+    },
+]
+
+_IDEATION_ONLY_TOOL_SPECS: list[dict[str, Any]] = [
+    {
+        "name": "devflow_create_idea",
+        "description": "Persist an idea payload locally and enqueue it onto the DevFlow idea-creation queue.",
+        "parameters": {
+            "idea_id": {"type": "string", "required": True, "description": "Canonical idea id to create."},
+            "summary": {"type": "string", "required": True, "description": "Short summary of the idea."},
+            "project_id": {"type": "string", "required": False, "description": "Optional project id."},
+            "problem_statement": {"type": "string", "required": False, "description": "Optional problem statement."},
+            "target_users": {"type": "array", "required": False, "description": "Optional target users list."},
+            "desired_outcomes": {"type": "array", "required": False, "description": "Optional desired outcomes list."},
+            "in_scope": {"type": "array", "required": False, "description": "Optional in-scope items."},
+            "out_of_scope": {"type": "array", "required": False, "description": "Optional out-of-scope items."},
+            "constraints": {"type": "array", "required": False, "description": "Optional constraints list."},
+            "acceptance_criteria": {"type": "array", "required": False, "description": "Optional acceptance criteria list."},
+        },
+    },
+    {
+        "name": "devflow_generate_stories",
+        "description": "Enqueue an existing idea for DevFlow story generation.",
+        "parameters": {
+            "idea_id": {"type": "string", "required": True, "description": "Idea id to enqueue for story generation."},
+            "project_id": {"type": "string", "required": False, "description": "Optional project id override."},
+            "candidate_planes": {"type": "array", "required": False, "description": "Optional candidate planes for downstream generation."},
+        },
+    },
+    {
+        "name": "devflow_kick_queue",
+        "description": "Run one DevFlow worker pass for the given project.",
+        "parameters": {
+            "project_id": {"type": "string", "required": True, "description": "Project id whose queue should be processed once."},
+        },
+    },
+    {
+        "name": "devflow_status",
+        "description": "Read current DevFlow queue counts for the active repo, optionally scoped to one project.",
+        "parameters": {
+            "project_id": {"type": "string", "required": False, "description": "Optional project id filter."},
+        },
+    },
+    {
+        "name": "propose_idea",
+        "description": "Synthesize a lightweight idea proposal preview from the provided idea details.",
+        "parameters": {
+            "idea_id": {"type": "string", "required": True, "description": "Idea id for the synthesized proposal."},
+            "summary": {"type": "string", "required": True, "description": "Short summary of the idea."},
+            "project_id": {"type": "string", "required": False, "description": "Optional project id."},
+            "problem_statement": {"type": "string", "required": False, "description": "Optional problem statement."},
+            "target_users": {"type": "array", "required": False, "description": "Optional target users list."},
+            "desired_outcomes": {"type": "array", "required": False, "description": "Optional desired outcomes list."},
+            "in_scope": {"type": "array", "required": False, "description": "Optional in-scope items."},
+            "out_of_scope": {"type": "array", "required": False, "description": "Optional out-of-scope items."},
+            "constraints": {"type": "array", "required": False, "description": "Optional constraints list."},
+            "acceptance_criteria": {"type": "array", "required": False, "description": "Optional acceptance criteria list."},
+        },
+    },
+]
+
+_INSIGHT_ONLY_TOOL_SPECS: list[dict[str, Any]] = [
+    {
+        "name": "devflow_status",
+        "description": "Read current DevFlow queue counts for the active repo, optionally scoped to one project.",
+        "parameters": {
+            "project_id": {"type": "string", "required": False, "description": "Optional project id filter."},
+        },
+    },
+]
+
+REPO_TOOL_SPECS: list[dict[str, Any]] = [*_SHARED_READ_TOOL_SPECS, *_IDEATION_ONLY_TOOL_SPECS]
+INSIGHT_REPO_TOOL_SPECS: list[dict[str, Any]] = [*_SHARED_READ_TOOL_SPECS, *_INSIGHT_ONLY_TOOL_SPECS]
+
+_ALL_REPO_TOOL_DISPATCH: dict[str, Any] = {
+    "project_overview": project_overview,
+    "read_repo_knowledge_index": read_repo_knowledge_index,
+    "search_code": search_code,
+    "read_file": read_file,
+    "read_docs_context": read_docs_context,
+    "read_recent_artifacts": read_recent_artifacts,
+    "inspect_routes": inspect_routes,
+    "inspect_data_model": inspect_data_model,
+    "devflow_create_idea": devflow_create_idea,
+    "devflow_generate_stories": devflow_generate_stories,
+    "devflow_kick_queue": devflow_kick_queue,
+    "devflow_status": devflow_status,
+    "propose_idea": propose_idea,
+}
+
+REPO_TOOL_DISPATCH: dict[str, Any] = {name: _ALL_REPO_TOOL_DISPATCH[name] for name in (spec["name"] for spec in REPO_TOOL_SPECS)}
+INSIGHT_REPO_TOOL_DISPATCH: dict[str, Any] = {
+    name: _ALL_REPO_TOOL_DISPATCH[name] for name in (spec["name"] for spec in INSIGHT_REPO_TOOL_SPECS)
+}
+
+
+def detect_repo_refs_in_text(text: str) -> list[str]:
+    """Detect likely GitHub repo references in free text.
+
+    Returns list of owner/repo strings found.
+    """
+    refs: list[str] = []
+    # GitHub URLs
+    for m in re.finditer(r"https?://github\.com/([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)", text):
+        ref = m.group(1).rstrip("/").removesuffix(".git")
+        if ref not in refs:
+            refs.append(ref)
+    # owner/repo patterns (conservative: require surrounding whitespace or start/end)
+    for m in re.finditer(r"(?:^|\s)([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)(?:\s|$)", text):
+        candidate = m.group(1)
+        # Filter out obvious non-repo patterns
+        if "/" in candidate and not candidate.startswith("/") and "." not in candidate.split("/")[0]:
+            if candidate not in refs:
+                refs.append(candidate)
+    return refs
+
+
+def build_repo_tool_guidance(repo_refs: list[str] | None = None) -> list[str]:
+    """Build guidance strings for the ideation agent about available repo tools."""
+    guidance = [
+        "You have access to the ideation-arm tool surface for the active project.",
+        (
+            "Read / understand: read_repo_knowledge_index, project_overview, search_code, read_file, "
+            "read_docs_context, read_recent_artifacts, inspect_routes, inspect_data_model."
+        ),
+        "Act (DevFlow only): devflow_create_idea, devflow_generate_stories, devflow_kick_queue, devflow_status.",
+        "Synthesis: propose_idea.",
+        "Do not use anything outside that approved ideation-arm tool surface.",
+    ]
+    if repo_refs:
+        refs_str = ", ".join(repo_refs)
+        guidance.append(
+            f"Repo references mentioned in context: {refs_str}. Treat them as discussion context unless the relevant files are present in the active workspace."
+        )
+    return guidance
+
+
+def build_insight_repo_tool_guidance(repo_refs: list[str] | None = None) -> list[str]:
+    """Build guidance strings for the insight agent about available repo tools."""
+    guidance = [
+        "You have access to the insight-arm tool surface for the active project.",
+        (
+            "Read / investigate: read_repo_knowledge_index, project_overview, search_code, read_file, "
+            "read_docs_context, read_recent_artifacts, inspect_routes, inspect_data_model, devflow_status."
+        ),
+        "Use these tools for repo understanding, evidence gathering, and DevFlow status checks only.",
+        "Do not use anything outside that approved insight-arm tool surface.",
+    ]
+    if repo_refs:
+        refs_str = ", ".join(repo_refs)
+        guidance.append(
+            f"Repo references mentioned in context: {refs_str}. Treat them as discussion context unless the relevant files are present in the active workspace."
+        )
+    return guidance