krnl-code 1.0.4__py3-none-any.whl

krnl_agent/parallel_executor.py

@@ -0,0 +1,139 @@
+"""Parallel Executor for Phase 5: Parallel Execution.
+
+Implements concurrent execution of multiple specialized agents.
+"""
+from __future__ import annotations
+
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+
+@dataclass
+class AgentTask:
+    """A task to be executed by an agent."""
+    agent_name: str
+    task: str
+    context: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AgentResult:
+    """Result from an agent task execution."""
+    agent_name: str
+    task: str
+    result: Any
+    success: bool
+    error: Optional[str] = None
+
+
+class ParallelExecutor:
+    """Executes multiple agent tasks concurrently."""
+
+    def __init__(self, max_workers: int = 4):
+        self.max_workers = max_workers
+
+    async def execute_tasks(
+        self,
+        tasks: list[AgentTask],
+        agent_handler: Callable[[str, str, dict[str, Any]], Any],
+    ) -> list[AgentResult]:
+        """Execute multiple agent tasks concurrently.
+
+        Args:
+            tasks: List of AgentTask objects to execute.
+            agent_handler: Async function that handles agent execution.
+                          Signature: (agent_name, task, context) -> result
+
+        Returns:
+            List of AgentResult objects in the same order as input tasks.
+        """
+        results = []
+
+        async def execute_single(task: AgentTask) -> AgentResult:
+            try:
+                result = await agent_handler(task.agent_name, task.task, task.context)
+                return AgentResult(
+                    agent_name=task.agent_name,
+                    task=task.task,
+                    result=result,
+                    success=True,
+                )
+            except Exception as e:
+                return AgentResult(
+                    agent_name=task.agent_name,
+                    task=task.task,
+                    result=None,
+                    success=False,
+                    error=str(e),
+                )
+
+        # Execute tasks concurrently with semaphore to limit concurrency
+        semaphore = asyncio.Semaphore(self.max_workers)
+
+        async def execute_with_semaphore(task: AgentTask) -> AgentResult:
+            async with semaphore:
+                return await execute_single(task)
+
+        # Run all tasks concurrently
+        results = await asyncio.gather(
+            *[execute_with_semaphore(task) for task in tasks],
+            return_exceptions=False,
+        )
+
+        return results
+
+    def execute_tasks_sync(
+        self,
+        tasks: list[AgentTask],
+        agent_handler: Callable[[str, str, dict[str, Any]], Any],
+    ) -> list[AgentResult]:
+        """Execute multiple agent tasks concurrently (synchronous wrapper).
+
+        Args:
+            tasks: List of AgentTask objects to execute.
+            agent_handler: Function that handles agent execution.
+                          Signature: (agent_name, task, context) -> result
+
+        Returns:
+            List of AgentResult objects in the same order as input tasks.
+        """
+        results = []
+
+        def execute_single(task: AgentTask) -> AgentResult:
+            try:
+                result = agent_handler(task.agent_name, task.task, task.context)
+                return AgentResult(
+                    agent_name=task.agent_name,
+                    task=task.task,
+                    result=result,
+                    success=True,
+                )
+            except Exception as e:
+                return AgentResult(
+                    agent_name=task.agent_name,
+                    task=task.task,
+                    result=None,
+                    success=False,
+                    error=str(e),
+                )
+
+        with ThreadPoolExecutor(max_workers=self.max_workers) as executor:
+            results = list(executor.map(execute_single, tasks))
+
+        return results
+
+    def get_summary(self, results: list[AgentResult]) -> dict[str, Any]:
+        """Get a summary of execution results."""
+        total = len(results)
+        successful = sum(1 for r in results if r.success)
+        failed = total - successful
+
+        return {
+            "total_tasks": total,
+            "successful": successful,
+            "failed": failed,
+            "success_rate": successful / total if total > 0 else 0,
+            "agents_used": list(set(r.agent_name for r in results)),
+        }

krnl_agent/permissions.py

@@ -0,0 +1,128 @@
+"""Permission engine — allow / ask / deny rules by tool + glob.
+
+Replaces the coarse auto-approve flags with fine-grained control, e.g.
+    allow:  read_file(**), git_status, git_diff
+    ask:    run_command(*), write_file(**)
+    deny:   delete_file(**/.git/**), run_command(rm -rf*)
+
+Rules are evaluated in order (first match wins); otherwise per-category defaults
+apply. "Always allow" decisions from an approval prompt are appended and
+persisted to ~/.krnl-agent/permissions.json.
+"""
+from __future__ import annotations
+
+import fnmatch
+import json
+from dataclasses import dataclass
+
+from .settings import SETTINGS_DIR
+
+PERMISSIONS_FILE = SETTINGS_DIR / "permissions.json"
+
+_READ_TOOLS = {
+    "list_files", "read_file", "search_text", "glob",
+    "process_output", "process_list", "git_status", "git_diff",
+}
+_COMMAND_TOOLS = {"run_command", "bash_background"}
+
+
+@dataclass
+class Rule:
+    tool: str       # tool name or "*"
+    pattern: str    # glob matched against the action's target string
+    action: str     # allow | ask | deny
+
+
+def _target(tool: str, args: dict) -> str:
+    if tool in ("run_command", "bash_background"):
+        return args.get("command", "")
+    if tool.startswith("mcp__"):
+        return f"{tool} {json.dumps(args)[:200]}"
+    return args.get("path") or args.get("url") or args.get("query") or ""
+
+
+def parse_rule(spec: str, action: str) -> Rule:
+    """Parse 'tool(pattern)' or 'tool' into a Rule."""
+    spec = spec.strip()
+    if spec.endswith(")") and "(" in spec:
+        tool, pattern = spec[:-1].split("(", 1)
+        return Rule(tool.strip() or "*", pattern.strip() or "*", action)
+    return Rule(spec or "*", "*", action)
+
+
+class Permissions:
+    def __init__(
+        self,
+        rules: list[Rule] | None = None,
+        *,
+        default_writes: str = "ask",
+        default_commands: str = "ask",
+        default_reads: str = "allow",
+    ):
+        self.rules = rules or []
+        self.default_writes = default_writes
+        self.default_commands = default_commands
+        self.default_reads = default_reads
+
+    @classmethod
+    def from_config(cls, perms: dict, *, auto_writes: bool, auto_commands: bool) -> "Permissions":
+        rules: list[Rule] = []
+        for action in ("deny", "ask", "allow"):  # deny first so it's checked first
+            for spec in (perms.get(action) or []):
+                rules.append(parse_rule(spec, action))
+        # persisted user "always allow" rules
+        rules += _load_persisted()
+        return cls(
+            rules,
+            default_writes="allow" if auto_writes else "ask",
+            default_commands="allow" if auto_commands else "ask",
+        )
+
+    def decide(self, tool: str, args: dict) -> str:
+        target = _target(tool, args)
+        for r in self.rules:
+            if r.tool in (tool, "*") and fnmatch.fnmatch(target, r.pattern):
+                return r.action
+        if tool in _READ_TOOLS:
+            return self.default_reads
+        if tool in _COMMAND_TOOLS or tool.startswith("mcp__"):
+            return self.default_commands
+        return self.default_writes
+
+    def add_always_allow(self, tool: str, args: dict) -> None:
+        target = _target(tool, args)
+        pattern = _generalize(tool, target)
+        rule = Rule(tool, pattern, "allow")
+        self.rules.insert(0, rule)
+        _persist(rule)
+
+
+def _generalize(tool: str, target: str) -> str:
+    """Turn a concrete target into a sensible reusable glob."""
+    if tool in ("run_command", "bash_background"):
+        first = target.split() [0] if target.split() else target
+        return f"{first}*"
+    if "/" in target:
+        return target  # exact path
+    return target or "*"
+
+
+# --------------------------------------------------------------------------- #
+def _load_persisted() -> list[Rule]:
+    try:
+        data = json.loads(PERMISSIONS_FILE.read_text(encoding="utf-8"))
+        return [Rule(r["tool"], r["pattern"], r["action"]) for r in data.get("rules", [])]
+    except Exception:
+        return []
+
+
+def _persist(rule: Rule) -> None:
+    try:
+        SETTINGS_DIR.mkdir(parents=True, exist_ok=True)
+        existing = []
+        if PERMISSIONS_FILE.exists():
+            existing = json.loads(PERMISSIONS_FILE.read_text(encoding="utf-8")).get("rules", [])
+        existing.insert(0, {"tool": rule.tool, "pattern": rule.pattern, "action": rule.action})
+        PERMISSIONS_FILE.write_text(json.dumps({"rules": existing}, indent=2), encoding="utf-8")
+    except Exception:
+        pass

krnl_agent/plugins.py

@@ -0,0 +1,105 @@
+"""Plugins — installable bundles of skills, commands, and MCP servers.
+
+A plugin is a folder (or a `.zip` URL) containing any of:
+    <plugin>/skills/<name>/SKILL.md     # skills
+    <plugin>/commands/*.md              # custom slash commands
+    <plugin>/krnl-plugin.yaml          # manifest: name, description, mcp servers
+
+Installed plugins live in `~/.krnl-agent/plugins/<name>/`. Their skills,
+commands, and MCP servers are merged into every session automatically.
+"""
+from __future__ import annotations
+
+import io
+import shutil
+import zipfile
+from pathlib import Path
+
+import yaml
+
+from .settings import SETTINGS_DIR
+
+PLUGINS_DIR = SETTINGS_DIR / "plugins"
+
+
+def _manifest(plugin_dir: Path) -> dict:
+    for name in ("krnl-plugin.yaml", "krnl-plugin.yml", "krnl-plugin.json"):
+        p = plugin_dir / name
+        if p.is_file():
+            try:
+                return yaml.safe_load(p.read_text(encoding="utf-8")) or {}
+            except Exception:
+                return {}
+    return {}
+
+
+def list_plugins() -> list[dict]:
+    if not PLUGINS_DIR.is_dir():
+        return []
+    out = []
+    for d in sorted(PLUGINS_DIR.iterdir()):
+        if d.is_dir():
+            m = _manifest(d)
+            out.append({"name": d.name, "description": m.get("description", "")})
+    return out
+
+
+def install(source: str) -> str:
+    """Install from a local directory or a .zip URL. Returns the plugin name."""
+    PLUGINS_DIR.mkdir(parents=True, exist_ok=True)
+    src = Path(source)
+    if src.is_dir():
+        name = _manifest(src).get("name") or src.name
+        dest = PLUGINS_DIR / name
+        if dest.exists():
+            shutil.rmtree(dest)
+        shutil.copytree(src, dest)
+        return name
+    if source.startswith(("http://", "https://")) and source.endswith(".zip"):
+        import httpx
+
+        data = httpx.get(source, follow_redirects=True, timeout=60).content
+        name = Path(source).stem
+        dest = PLUGINS_DIR / name
+        if dest.exists():
+            shutil.rmtree(dest)
+        with zipfile.ZipFile(io.BytesIO(data)) as zf:
+            zf.extractall(dest)
+        # if the zip wrapped everything in a single top folder, flatten it
+        entries = [p for p in dest.iterdir()]
+        if len(entries) == 1 and entries[0].is_dir():
+            inner = entries[0]
+            for child in inner.iterdir():
+                shutil.move(str(child), str(dest / child.name))
+            inner.rmdir()
+        return _manifest(dest).get("name") or name
+    raise ValueError("source must be a local directory or an http(s) .zip URL")
+
+
+def remove(name: str) -> bool:
+    dest = PLUGINS_DIR / name
+    if dest.is_dir():
+        shutil.rmtree(dest)
+        return True
+    return False
+
+
+def _plugin_dirs() -> list[Path]:
+    if not PLUGINS_DIR.is_dir():
+        return []
+    return [d for d in PLUGINS_DIR.iterdir() if d.is_dir()]
+
+
+def plugin_skill_dirs() -> list[Path]:
+    return [d / "skills" for d in _plugin_dirs() if (d / "skills").is_dir()]
+
+
+def plugin_command_dirs() -> list[Path]:
+    return [d / "commands" for d in _plugin_dirs() if (d / "commands").is_dir()]
+
+
+def plugin_mcp_servers() -> dict:
+    servers: dict = {}
+    for d in _plugin_dirs():
+        servers.update((_manifest(d).get("mcp", {}) or {}).get("servers", {}) or {})
+    return servers

krnl_agent/pricing.py

@@ -0,0 +1,85 @@
+"""Token to cost estimation.
+
+Prices are USD per 1M tokens (input, output), matched by substring against the
+model id (longest match wins), so 'gpt-4o-mini-2024-..' resolves correctly.
+
+Two ways a model gets priced:
+  1. A per-model override from config (`pricing:` in config.yaml) - authoritative.
+  2. The built-in table below.
+Unknown models return 0.0 (we only ever estimate, never bill); for those, the CLI
+tells you to add a price under `pricing:`.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+# (input_per_1M, output_per_1M)
+PRICES: dict[str, tuple[float, float]] = {
+    # OpenAI
+    "gpt-4o-mini": (0.15, 0.60),
+    "gpt-4o": (2.50, 10.0),
+    "gpt-4.1-mini": (0.40, 1.60),
+    "gpt-4.1-nano": (0.10, 0.40),
+    "gpt-4.1": (2.00, 8.00),
+    "gpt-5-nano": (0.05, 0.40),
+    "gpt-5-mini": (0.25, 2.00),
+    "gpt-5.5": (1.25, 10.0),
+    "gpt-5": (1.25, 10.0),
+    "o4-mini": (1.10, 4.40),
+    "o3-mini": (1.10, 4.40),
+    "o3": (2.00, 8.00),
+    "o1-mini": (1.10, 4.40),
+    "o1": (15.0, 60.0),
+    # Anthropic
+    "claude-3-5-haiku": (0.80, 4.00),
+    "claude-haiku": (1.00, 5.00),
+    "claude-3-5-sonnet": (3.00, 15.0),
+    "claude-sonnet": (3.00, 15.0),
+    "claude-opus": (15.0, 75.0),
+    # Google
+    "gemini-2.5-pro": (1.25, 10.0),
+    "gemini-2.5-flash": (0.30, 2.50),
+    "gemini-2.0-flash": (0.10, 0.40),
+    "gemini-1.5-flash": (0.075, 0.30),
+    "gemini-1.5-pro": (1.25, 5.00),
+    "gemini": (0.10, 0.40),
+    # others
+    "deepseek": (0.27, 1.10),
+    "grok": (2.00, 10.0),
+    "mistral-large": (2.00, 6.00),
+    "mistral": (0.20, 0.60),
+    "llama": (0.0, 0.0),
+    "qwen": (0.0, 0.0),
+}
+
+
+def _rate_from(table: dict, model: str) -> Optional[tuple[float, float]]:
+    m = (model or "").lower()
+    for key in sorted(table, key=len, reverse=True):  # longest (most specific) wins
+        if key.lower() in m:
+            v = table[key]
+            if isinstance(v, dict):
+                return float(v.get("input", 0)), float(v.get("output", 0))
+            return float(v[0]), float(v[1])
+    return None
+
+
+def rate_for(model: str, overrides: Optional[dict] = None) -> Optional[tuple[float, float]]:
+    """Return (input_per_1M, output_per_1M) or None if the model is unpriced."""
+    if overrides:
+        r = _rate_from(overrides, model)
+        if r is not None:
+            return r
+    return _rate_from(PRICES, model)
+
+
+def is_priced(model: str, overrides: Optional[dict] = None) -> bool:
+    return rate_for(model, overrides) is not None
+
+
+def cost_for(model: str, prompt_tokens: int, completion_tokens: int,
+             overrides: Optional[dict] = None) -> float:
+    rate = rate_for(model, overrides)
+    if rate is None:
+        return 0.0
+    return prompt_tokens / 1_000_000 * rate[0] + completion_tokens / 1_000_000 * rate[1]

krnl_agent/prompts.py

@@ -0,0 +1,60 @@
+"""System prompt for the coding agent.
+
+The prompt is deliberately tight and concrete: clear tool-use rules and a
+plan-first discipline are what let a *small* model behave well on focused tasks.
+"""
+from __future__ import annotations
+
+
+def system_prompt(workspace_path: str, file_tree: str) -> str:
+    return f"""You are Krnl Agent, an expert pair-programmer working INSIDE a user's project.
+You operate by calling tools. You can read files, search, edit/create/delete
+files, and run shell commands — always scoped to the workspace.
+
+Workspace root: {workspace_path}
+
+Operating rules:
+1. PLAN FIRST. For any non-trivial task, briefly state a short plan (2-5 steps)
+   in plain text before acting. Keep it terse.
+2. GROUND YOURSELF. Never guess file contents. Use `read_file` and `search_text`
+   to learn the real code before editing. Prefer small, targeted reads.
+3. EDIT SURGICALLY. Use `edit_file` (exact search/replace) for changes to
+   existing files — it is safer and cheaper than rewriting. Use `write_file`
+   only for whole new files or full rewrites. `old_string` must match the file
+   EXACTLY, including indentation, and be unique enough to target one spot.
+4. ONE STEP AT A TIME. Make one logical change, observe the tool result, then
+   continue. Do not assume an edit applied — the result tells you.
+5. RESPECT APPROVAL. Edits and commands may be rejected by the user. If a tool
+   result says the action was rejected, adapt — do not retry the identical action.
+6. VERIFY when reasonable (run tests, run the file, re-read the edited region),
+   but don't run long or destructive commands without good reason.
+7. STOP when done. When the task is complete, reply with a concise final summary
+   (what changed and why) and DO NOT call any more tools. That ends the turn.
+
+Extra capabilities:
+- `todo_write`: for any task with 3+ steps, keep a checklist updated — exactly one
+  item `in_progress` at a time. It keeps you organized and the user informed.
+  WARNING: After updating the checklist, you MUST immediately call a real tool
+  (write_file, edit_file, run_command, etc.). Never call todo_write twice in a row
+  without doing real work in between.
+- `spawn_agent`: delegate a focused, independent sub-task to a sub-agent (e.g. a
+  separate investigation). It returns a summary; you stay the orchestrator.
+- `multi_edit`: several edits to one file atomically. `glob`: find files by pattern.
+- `web_search` / `web_fetch`: look up current information when needed.
+- `bash_background` + `process_output`/`process_kill`/`process_list`: long-running
+  processes like dev servers (never block on them with run_command)
+- `git_status` / `git_diff` / `git_commit`: inspect and commit changes.
+- `mcp__*` tools (if present) come from connected MCP servers — use them like any tool.
+
+Large file strategy: When creating files with 100+ lines (CSS, JS, HTML, etc.):
+1. Use write_file for the first portion (e.g. first 150 lines).
+2. Use edit_file to append remaining sections one at a time.
+3. Never attempt to write more content than can fit in a single tool call output.
+   If unsure, write smaller chunks and build up incrementally.
+
+Be concise. Favor correctness over cleverness. Match the project's existing
+style and conventions.
+
+Current files (truncated):
+{file_tree}
+"""

krnl_agent/repomap.py

@@ -0,0 +1,133 @@
+"""Token-friendly semantic repo map.
+
+Instead of reading whole files, the agent can pull a compact *outline* of the
+repository: per-file lists of the top-level symbols (classes, functions, methods,
+exported consts) with their line numbers. This is language-agnostic - it uses
+lightweight regex signatures, so there are no heavy parser dependencies - and the
+output is bounded so it always fits in a small slice of the context window.
+
+The agent reads the map first to locate code, then `read_file` only the specific
+ranges it needs. That turns "read 40 files to find the auth handler" into "read
+one outline, then one function".
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+# Per-language symbol signatures: (compiled regex, kind). Group 1 is the name.
+_LANG_PATTERNS: dict[str, list[tuple[re.Pattern, str]]] = {
+    "py": [
+        (re.compile(r"^\s*class\s+([A-Za-z_]\w*)"), "class"),
+        (re.compile(r"^\s*(?:async\s+)?def\s+([A-Za-z_]\w*)"), "def"),
+    ],
+    "js": [
+        (re.compile(r"^\s*(?:export\s+)?(?:default\s+)?class\s+([A-Za-z_$][\w$]*)"), "class"),
+        (re.compile(r"^\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)"), "function"),
+        (re.compile(r"^\s*(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\(?[^=]*=>"), "const-fn"),
+    ],
+    "ts": [
+        (re.compile(r"^\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)"), "class"),
+        (re.compile(r"^\s*(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)"), "interface"),
+        (re.compile(r"^\s*(?:export\s+)?type\s+([A-Za-z_$][\w$]*)"), "type"),
+        (re.compile(r"^\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)"), "function"),
+        (re.compile(r"^\s*(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*[:=]"), "const"),
+    ],
+    "go": [
+        (re.compile(r"^\s*func\s+(?:\([^)]*\)\s*)?([A-Za-z_]\w*)"), "func"),
+        (re.compile(r"^\s*type\s+([A-Za-z_]\w*)\s+(?:struct|interface)"), "type"),
+    ],
+    "rs": [
+        (re.compile(r"^\s*(?:pub\s+)?fn\s+([A-Za-z_]\w*)"), "fn"),
+        (re.compile(r"^\s*(?:pub\s+)?(?:struct|enum|trait)\s+([A-Za-z_]\w*)"), "type"),
+    ],
+    "java": [
+        (re.compile(r"^\s*(?:public|private|protected).*\bclass\s+([A-Za-z_]\w*)"), "class"),
+        (re.compile(r"^\s*(?:public|private|protected|static).*\b([A-Za-z_]\w*)\s*\([^;{]*\)\s*\{"), "method"),
+    ],
+    "rb": [
+        (re.compile(r"^\s*class\s+([A-Za-z_]\w*)"), "class"),
+        (re.compile(r"^\s*def\s+([A-Za-z_][\w?!]*)"), "def"),
+    ],
+}
+# File extension -> language key.
+_EXT_LANG = {
+    ".py": "py", ".js": "js", ".jsx": "js", ".mjs": "js", ".cjs": "js",
+    ".ts": "ts", ".tsx": "ts", ".go": "go", ".rs": "rs", ".java": "java",
+    ".rb": "rb",
+}
+
+_MAX_FILES = 400
+_MAX_SYMBOLS_PER_FILE = 40
+_MAX_TOTAL_LINES = 1500
+
+
+def _symbols_in(path: Path, lang: str) -> list[tuple[int, str, str]]:
+    """Return (line_no, kind, name) for symbols in one file."""
+    pats = _LANG_PATTERNS.get(lang, [])
+    out: list[tuple[int, str, str]] = []
+    try:
+        with open(path, encoding="utf-8", errors="ignore") as fh:
+            for i, line in enumerate(fh, 1):
+                if len(line) > 400:
+                    continue
+                for rx, kind in pats:
+                    m = rx.match(line)
+                    if m:
+                        out.append((i, kind, m.group(1)))
+                        break
+                if len(out) >= _MAX_SYMBOLS_PER_FILE:
+                    out.append((i, "…", "(more symbols truncated)"))
+                    break
+    except Exception:
+        return out
+    return out
+
+
+def build_map(ctx, path: str = ".", lang_filter: str | None = None) -> str:
+    """Build a compact outline of the workspace (or a sub-path).
+
+    `ctx` is a tools.ToolContext (used for sandboxing + ignore rules).
+    """
+    base = ctx.resolve(path)
+    if not base.exists():
+        return f"Path not found: {path}"
+    if base.is_file():
+        files = [base]
+    else:
+        files = []
+        for root, dirs, names in os.walk(base):
+            rroot = ctx.rel(Path(root))
+            dirs[:] = [d for d in sorted(dirs)
+                       if not ctx.is_ignored(f"{rroot}/{d}".lstrip("./"))]
+            for n in sorted(names):
+                fp = Path(root) / n
+                if fp.suffix.lower() in _EXT_LANG and not ctx.is_ignored(ctx.rel(fp)):
+                    files.append(fp)
+            if len(files) >= _MAX_FILES:
+                break
+
+    lines: list[str] = []
+    total = 0
+    shown = 0
+    for fp in sorted(files):
+        lang = _EXT_LANG.get(fp.suffix.lower())
+        if not lang or (lang_filter and lang != lang_filter):
+            continue
+        syms = _symbols_in(fp, lang)
+        if not syms:
+            continue
+        lines.append(f"\n{ctx.rel(fp)}")
+        for ln, kind, name in syms:
+            lines.append(f"  {ln:>5}  {kind} {name}")
+            total += 1
+        shown += 1
+        if total >= _MAX_TOTAL_LINES:
+            lines.append("\n… (map truncated; narrow with path= or lang=)")
+            break
+
+    if not lines:
+        return "(no recognizable source symbols found)"
+    header = f"# Repo map — {shown} file(s), {total} symbols (line  kind  name)"
+    return header + "\n" + "\n".join(lines)