@allansantos-dev/smart-tool 0.9.2 → 0.9.3

package/edit_preview.py

@@ -0,0 +1,92 @@
+"""The files an agent edit would produce, computed before the edit runs: Claude Code Edit, MultiEdit and Write, and
+Codex apply_patch (*** Begin Patch / Update File / Add File). Returns (absolute path, text before or None, text after)
+for each file it can rebuild; an edit it cannot rebuild yields nothing, so a hook built on it never blocks wrongly."""
+import os
+
+
+def _read(path):
+    try:
+        with open(path, encoding="utf-8") as stream:
+            return stream.read()
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def _replace(text, old, new, every):
+    if not old or old not in text:
+        return None
+    return text.replace(old, new) if every else text.replace(old, new, 1)
+
+
+def _claude(tool, data):
+    path = data.get("file_path")
+    if not isinstance(path, str) or not os.path.isabs(path):
+        return []
+    before = _read(path)
+    if tool == "Write":
+        content = data.get("content")
+        return [(path, before, content)] if isinstance(content, str) else []
+    if before is None:
+        return []
+    edits = data.get("edits") if tool == "MultiEdit" else [data]
+    after = before
+    for edit in edits or []:
+        after = _replace(after, edit.get("old_string"), edit.get("new_string", ""), edit.get("replace_all") is True)
+        if after is None:
+            return []
+    return [(path, before, after)]
+
+
+def _apply_hunks(text, hunks):
+    lines = text.splitlines()
+    for old, new in hunks:
+        if not old:
+            lines.extend(new)
+            continue
+        at = next((i for i in range(len(lines) - len(old) + 1) if lines[i:i + len(old)] == old), None)
+        if at is None:
+            return None
+        lines[at:at + len(old)] = new
+    return "\n".join(lines) + ("\n" if text.endswith("\n") or not text else "")
+
+
+def _codex(patch, cwd):
+    if not isinstance(patch, str) or "*** Begin Patch" not in patch:
+        return []
+    files, current = [], None
+    for raw in patch.splitlines():
+        if raw.startswith(("*** Update File: ", "*** Add File: ")):
+            current = {"action": raw.split(":", 1)[0][4:], "path": raw.split(":", 1)[1].strip(), "hunks": [[[], []]]}
+            files.append(current)
+        elif raw.startswith(("*** Delete File: ", "*** End Patch", "*** Move to: ")) or current is None:
+            current = None if raw.startswith(("*** Delete File: ", "*** End Patch")) else current
+        elif raw.startswith("@@"):
+            current["hunks"].append([[], []])
+        elif raw.startswith("+"):
+            current["hunks"][-1][1].append(raw[1:])
+        elif raw.startswith("-"):
+            current["hunks"][-1][0].append(raw[1:])
+        elif raw.startswith(" ") or raw == "":
+            current["hunks"][-1][0].append(raw[1:])
+            current["hunks"][-1][1].append(raw[1:])
+    results = []
+    for entry in files:
+        path = entry["path"] if os.path.isabs(entry["path"]) else os.path.join(cwd or os.getcwd(), entry["path"])
+        hunks = [hunk for hunk in entry["hunks"] if hunk[0] or hunk[1]]
+        if entry["action"] == "Add File":
+            results.append((path, None, "\n".join(line for hunk in hunks for line in hunk[1]) + "\n"))
+            continue
+        before = _read(path)
+        after = _apply_hunks(before, hunks) if before is not None else None
+        if after is not None:
+            results.append((path, before, after))
+    return results
+
+
+def preview(tool_name, tool_input, cwd=None):
+    data = tool_input if isinstance(tool_input, dict) else {}
+    if tool_name in ("Edit", "MultiEdit", "Write") and "file_path" in data:
+        return _claude(tool_name, data)
+    if tool_name in ("apply_patch", "Edit", "Write") and "command" in data:
+        return _codex(data.get("command"), cwd)
+    return []

package/hook_decision.py

@@ -10,11 +10,20 @@ no Claude Code, e nenhuma decisão aqui é sobre periculosidade, só sobre custo
 import json
 import os
 
+import code_graph
+import code_impact
 import config
+import doc_check
+import duplicates
+import edit_preview
 import endpoint_sync
+import project_store
 import router
 
 WEB_TOOLS = ("WebSearch", "WebFetch")
+EDIT_TOOLS = ("Edit", "MultiEdit", "Write", "apply_patch")
+MAX_DOC_FINDINGS = 5
+MAX_DUPLICATE_FINDINGS = 3
 SMART_TOOL_SERVER = "smart-tool"
 REASON_MAX_CHARS = 200
 
@@ -55,9 +64,94 @@ def advise(reason):
                                    "additionalContext": f"Smart Tool tip (the call was not blocked): {reason}"}}
 
 
+def _project_of(path):
+    target = os.path.normcase(os.path.abspath(path))
+    roots = [p["root"] for p in project_store.all_projects()
+             if target.startswith(os.path.normcase(os.path.abspath(p["root"])) + os.sep)]
+    return max(roots, key=len) if roots else None
+
+
+def _impact_line(root, rel, name):
+    """Callers and tests from the code graph, only when its analysis is already cached: the hook never waits for one."""
+    if not root or code_graph.cached_symbols(root)[0] is None:
+        return ""
+    try:
+        found = code_impact.impact(root, f"{rel}::{name}", limit=3)
+    except ValueError:
+        return ""
+    counts = found["counts"]
+    tests = ", ".join(f"{t['function']} ({t['path']})" for t in found["tests"])
+    calls = f"; tests calling it: {tests}" if tests else ""
+    return f" {counts['callers']} caller(s){calls}; project_manage affected_tests lists every test to run after the edit."
+
+
+def _doc_lines(findings):
+    lines = []
+    for root, rel, item in findings[:MAX_DOC_FINDINGS]:
+        if item["issue"] == "missing":
+            text = f"{item['name']} ({rel}:{item['start']}) has no docstring: write one (purpose, parameters, return)."
+        else:
+            text = (f"{item['name']} ({rel}:{item['start']}) changed its signature: update its docstring if the "
+                    f"contract changed.")
+        lines.append(text + _impact_line(root, rel, item["name"]))
+    if len(findings) > MAX_DOC_FINDINGS:
+        lines.append(f"{len(findings) - MAX_DOC_FINDINGS} more function(s) in the same situation.")
+    return "Smart Tool docs: " + " ".join(lines)
+
+
+def _duplicate_lines(findings):
+    lines = []
+    for rel, item in findings[:MAX_DUPLICATE_FINDINGS]:
+        existing = item["existing"]
+        where = f"{existing['name']} in {existing['path']}:{existing['lines']}"
+        if item["type"] == "exact":
+            lines.append(f"{item['name']} ({rel}:{item['lines']}) has the same body as {where}: reuse it instead of a copy.")
+        else:
+            lines.append(f"{item['name']} ({rel}:{item['lines']}) is near-identical to {where} (score {item['score']}, "
+                         f"local names ignored): check whether it can be reused.")
+    if len(findings) > MAX_DUPLICATE_FINDINGS:
+        lines.append(f"{len(findings) - MAX_DUPLICATE_FINDINGS} more copied function(s).")
+    return ("Smart Tool duplicates: " + " ".join(lines)
+            + " If the copy is intentional (moving the function, a deliberate fork), go ahead.")
+
+
+def _edit_review(payload, doc_mode, duplicate_mode):
+    """Checks of an edit before it runs. Docstrings follow doc_mode: missing ones deny the edit in require mode and
+    become a reminder in remind mode; a documented function whose signature changed always gets a reminder. Copies of
+    indexed functions follow duplicate_mode and only add context, never deny."""
+    doc_findings, duplicate_findings, failures = [], [], []
+    for path, before, after in edit_preview.preview(payload.get("tool_name"), payload.get("tool_input"), payload.get("cwd")):
+        if not doc_check.supported(path):
+            continue
+        root = _project_of(path)
+        rel = os.path.relpath(path, root).replace(os.sep, "/") if root else os.path.basename(path)
+        edited = doc_check.written(path, before, after)
+        if doc_mode != "off":
+            doc_findings += [(root, rel, item) for item in doc_check.review(path, before, after, edited)]
+        if duplicate_mode != "off" and root and edited["touched"]:
+            try:
+                duplicate_findings += [(rel, item) for item in duplicates.on_write(root, path, before, after, edited)]
+            except (ValueError, RuntimeError) as exc:
+                failures.append(f"Smart Tool duplicates check skipped: {exc}")
+    parts = ([_doc_lines(doc_findings)] if doc_findings else []) + \
+        ([_duplicate_lines(duplicate_findings)] if duplicate_findings else []) + failures
+    if not parts:
+        return {}
+    message = " ".join(parts)
+    if doc_mode == "require" and any(item["issue"] == "missing" for _root, _rel, item in doc_findings):
+        return deny(message + " Redo the edit with the docstring.")
+    return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": message}}
+
+
 def decide(payload, client, web_route):
-    """Hook output for one PreToolUse payload, following config hook_mode (redirect | advise | off)."""
+    """Hook output for one PreToolUse payload: edits follow doc_mode (require | remind | off) and duplicate_mode
+    (warn | off), the other tools follow hook_mode (redirect | advise | off)."""
     cfg = config.load_config()
+    if isinstance(payload, dict) and payload.get("tool_name") in EDIT_TOOLS:
+        doc_mode, duplicate_mode = config.doc_mode(cfg), config.duplicate_mode(cfg)
+        if doc_mode == "off" and duplicate_mode == "off":
+            return {}
+        return _edit_review(payload, doc_mode, duplicate_mode)
     mode = config.hook_mode(cfg)
     if mode == "off" or not isinstance(payload, dict):
         return {}
@@ -82,7 +176,7 @@ def _route(payload, client, web_route, cfg):
             return {}
         decision = web_route(tool_name, str(tool_input.get("url") or ""))
         return deny(clean_reason(decision.get("reason"))) if decision.get("redirect") else {}
-    router.CLIENT = client
+    router.CLIENT.set(client)
     try:
         decision, reason = router.decide(tool_name, tool_input, router_model, cwd=cwd)
     except Exception as exc:

package/index_profile.py

@@ -17,7 +17,7 @@ DOC_DATA = {"html", "htm", "json", "csv", "xml", "yaml", "yml", "svg"}
 _NAME_DOC = re.compile(r"(^|/)(readme|changelog|license|licence|contributing|install|history|authors)(\.[^/]*)?$", re.I)
 _DIR_DOC = re.compile(r"(^|/)(docs?|adrs?|documentation)/", re.I)
 _TEST = re.compile(r"(^|/)(tests?|__tests__|spec|specs|e2e|fixtures?|testdata|test-utils?)(/|$)|(^|/)test_[^/]+\.py$|"
-                   r"(^|/)conftest\.py$|_test\.(py|go)$|\.(test|spec)\.[cm]?[jt]sx?$|(^|/)[^/]*[a-z0-9](?-i:Tests?)\.java$|"
+                   r"(^|/)conftest\.py$|_test\.(py|go)$|\.(test|spec)(-d)?\.[cm]?[jt]sx?$|(^|/)[^/]*[a-z0-9](?-i:Tests?)\.java$|"
                    r"(^|/)src/test/|(^|/)test[-_][^/]*\.[cm]?[jt]sx?$|[-_]test\.[cm]?[jt]sx?$", re.I)
 _TEST_PROSE = re.compile(r"(^|/)(tests?|__tests__|e2e|fixtures?|testdata|test-utils?)(/|$)|(^|/)src/test/", re.I)
 _TEXT_LINE = re.compile(r"[A-Za-zÀ-ú]{3,}\s+[A-Za-zÀ-ú]{3,}")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allansantos-dev/smart-tool",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharper tools than their built-in search. Windows.",
   "license": "Apache-2.0",
   "author": "Allan Santos",

package/router.py

@@ -5,6 +5,7 @@ modelo pequeno se deve deixar passar ou redirecionar pra `smart_search`. Cada de
 logada em `router-metrics.jsonl` pra orientar um classificador mais fino depois, com
 base em uso real — não numa suposição a priori.
 """
+import contextvars
 import json
 import os
 import paths
@@ -17,7 +18,8 @@ import index_scope
 import indexer
 import web_search_adapters
 
-CLIENT = None
+# Per request: the daemon serves each hook call on its own thread, so a module global mixed up clients.
+CLIENT = contextvars.ContextVar("router_client", default=None)
 METRICS_PATH = os.path.join(paths.DATA_DIR, "router-metrics.jsonl")
 
 _SYSTEM_PROMPT = (
@@ -266,7 +268,7 @@ def _log_decision(tool_name, tool_input, decision, reason, extra=None):
         "tool_input": _redacted_input(tool_input),
         "decision": decision,
         "reason": reason,
-        **({"client": CLIENT} if CLIENT else {}),
+        **({"client": CLIENT.get()} if CLIENT.get() else {}),
     }
     record.update(extra or {})
     try:

package/setup_ui.py

@@ -177,18 +177,31 @@ def handle_integration_get():
         mode, mode_error = config.hook_mode(), ""
     except ValueError as exc:
         mode, mode_error = "", str(exc)
+    try:
+        doc_mode, doc_error = config.doc_mode(), ""
+    except ValueError as exc:
+        doc_mode, doc_error = "", str(exc)
+    try:
+        duplicate_mode, duplicate_error = config.duplicate_mode(), ""
+    except ValueError as exc:
+        duplicate_mode, duplicate_error = "", str(exc)
     return {"daemon_url": setup_origin(), "clients": clients, "hook_mode": mode, "hook_mode_error": mode_error,
-            "hook_modes": list(config.HOOK_MODES)}
+            "hook_modes": list(config.HOOK_MODES), "doc_mode": doc_mode, "doc_mode_error": doc_error,
+            "doc_modes": list(config.DOC_MODES), "duplicate_mode": duplicate_mode,
+            "duplicate_mode_error": duplicate_error, "duplicate_modes": list(config.DUPLICATE_MODES)}
 
 
 def handle_integration_save(body):
     """`hook_mode` sets redirect/advise/off for every client; `register_mcp` runs the client's CLI; hook in two steps:
     `preview` shows the exact change, `install` writes it (with backup)."""
-    if isinstance(body, dict) and body.get("action") == "hook_mode":
-        if body.get("mode") not in config.HOOK_MODES:
-            raise SetupError("Invalid mode: use redirect, advise or off.")
+    if isinstance(body, dict) and body.get("action") in ("hook_mode", "doc_mode", "duplicate_mode"):
+        action = body["action"]
+        allowed = {"hook_mode": config.HOOK_MODES, "doc_mode": config.DOC_MODES,
+                   "duplicate_mode": config.DUPLICATE_MODES}[action]
+        if body.get("mode") not in allowed:
+            raise SetupError(f"Invalid mode: use {', '.join(allowed)}.")
         try:
-            config.update_config(lambda cfg: cfg.update(hook_mode=body["mode"]))
+            config.update_config(lambda cfg: cfg.update({action: body["mode"]}))
         except (OSError, config.ConfigCorruptedError) as exc:
             raise SetupError(str(exc))
         return handle_integration_get()
@@ -565,6 +578,21 @@ _PAGE_TEMPLATE = """<!doctype html>
           </select>
           <span class="hint" id="hook-mode-hint">Applies to every client on the next tool call; nothing is reinstalled.</span></div>
         <div class="actions"><button type="button" id="btn-save-hook-mode">Save behavior</button></div>
+        <div class="field" style="margin-top:16px"><label for="sel-doc-mode">Documentation on edit</label>
+          <select id="sel-doc-mode">
+            <option value="remind">Remind: the edit runs; the agent is told which touched functions lack a docstring (default)</option>
+            <option value="require">Require: an edit that leaves a touched function without a docstring is blocked until it adds one</option>
+            <option value="off">Off: no documentation checks</option>
+          </select>
+          <span class="hint">Only public functions the edit touches (private, nested and override functions are exempt, as in pydocstyle, eslint-plugin-jsdoc and Checkstyle). A documented function is mentioned again only when its signature changes; body-only edits stay silent.</span></div>
+        <div class="actions"><button type="button" id="btn-save-doc-mode">Save documentation</button></div>
+        <div class="field" style="margin-top:16px"><label for="sel-duplicate-mode">Duplicate functions on edit</label>
+          <select id="sel-duplicate-mode">
+            <option value="warn">Warn: the edit runs; the agent is told when a written function copies one already in the project (default)</option>
+            <option value="off">Off: no duplicate checks on edit</option>
+          </select>
+          <span class="hint">Compares functions the edit writes with the indexed code: identical bodies, and near-identical ones with only local names changed. Never blocks.</span></div>
+        <div class="actions"><button type="button" id="btn-save-duplicate-mode">Save duplicates</button></div>
         <div class="msg" id="agents-msg" role="status"></div>
         <div id="agents-list"></div>
       </section>
@@ -849,7 +877,11 @@ async function loadAgents() {
     const data = await resp.json();
     if (!resp.ok || data.error) throw new Error(data.error);
     if (document.activeElement !== $("sel-hook-mode")) $("sel-hook-mode").value = data.hook_mode;
+    if (document.activeElement !== $("sel-doc-mode")) $("sel-doc-mode").value = data.doc_mode;
+    if (document.activeElement !== $("sel-duplicate-mode")) $("sel-duplicate-mode").value = data.duplicate_mode;
     if (data.hook_mode_error) setMsg("agents-msg", "error", data.hook_mode_error);
+    if (data.doc_mode_error) setMsg("agents-msg", "error", data.doc_mode_error);
+    if (data.duplicate_mode_error) setMsg("agents-msg", "error", data.duplicate_mode_error);
     const list = $("agents-list");
     list.textContent = "";
     for (const item of data.clients) {
@@ -913,6 +945,22 @@ async function loadAgents() {
   }
 }
 loadAgents();
+$("btn-save-doc-mode").addEventListener("click", async () => {
+  try {
+    await post("/setup/integration", { action: "doc_mode", mode: $("sel-doc-mode").value });
+    setMsg("agents-msg", "ok", "Documentation setting saved; it applies on the next edit.");
+  } catch (error) {
+    setMsg("agents-msg", "error", error.message);
+  }
+});
+$("btn-save-duplicate-mode").addEventListener("click", async () => {
+  try {
+    await post("/setup/integration", { action: "duplicate_mode", mode: $("sel-duplicate-mode").value });
+    setMsg("agents-msg", "ok", "Duplicate setting saved; it applies on the next edit.");
+  } catch (error) {
+    setMsg("agents-msg", "error", error.message);
+  }
+});
 $("btn-save-hook-mode").addEventListener("click", async () => {
   try {
     await post("/setup/integration", { action: "hook_mode", mode: $("sel-hook-mode").value });

package/smart_tool_daemon.py

@@ -48,6 +48,7 @@ import index_views
 import index_inventory
 import usage_meter
 import document_text
+import embedding_cache
 import model_defaults
 import project_identity
 import project_store
@@ -291,7 +292,7 @@ def _smart_search_job_payload(job_id):
     else:
         payload["error"] = job.get("error") or "Search did not complete."
         payload["resumable"] = bool(job.get("arguments"))
-    if job.get("stats"):
+    if job.get("stats") and job["stats"] != payload.get("result"):
         payload["stats"] = job["stats"]
     if job.get("failure_phase"):
         payload["failure_phase"] = job["failure_phase"]
@@ -302,10 +303,10 @@ def _smart_search_job_payload(job_id):
 TOOLS = [
     {
         "name": "project_manage",
-        "description": "Manages folders and indexing. list/status show project_id, storage, scope and jobs. graph reads the indexed view: coverage, references and static calls in Java, Angular, Python and JS/TS/JSX/TSX; includes HTML/CSS/Markdown references and TXT/DOCX coverage; with file_path, narrows to that file's symbols, imports and calls. inspect lists the files of a view_id; with file_path, returns only that file's chunks. usage shows consumption and reuse; duplicates lists duplicated functions (identical, near-identical and semantic bodies, min_similarity default 0.90; below that most pairs measured were false positives), excluding tests unless include_tests=true; fix real duplicates; only dismiss with duplicates_dismiss (finding_id, reason=false_positive|intentional, note) what is not a duplicate or is a copy kept on purpose: the finding stays hidden until the code changes, and duplicates_restore reopens it; integration shows the MCP client, hook and tool usage metrics; install_hook_preview shows the change that would install the hook redirecting Grep/Read to smart_search and WebSearch/WebFetch to web_search/web_fetch in this session's client and returns a plan_id; install_hook writes it with that plan_id and confirm=true, with a backup, only after the user approves the change; search_limits saves the project's default top_k per block ({code, test, doc}, each 1-20, total at most 20); storage shows disk usage and views; pin_view protects a view; cleanup_preview and cleanup_commit remove selected views after confirmation; compare compares two stored views, without checkout or embeddings. register adds a folder; preview checks the scope; index/rebuild update; pause/cancel keep checkpoints; resume continues; policy picks on_search/eager; scope adjusts the scope; remove deletes only the local index. Jobs via smart_search_result.",
+        "description": "Manages folders and indexing. Every action takes project_root (the folder) or project_id. list gives a short line per project; status shows storage, scope and jobs. graph with symbol (function, Class.method, class name, or path::name when the name repeats) answers what an edit touches: definition, callers with line, calls, tests that reach it through static calls (depth hops, default 3) and files importing it; use it before changing a function to know what to update. affected_tests answers which tests to run after editing: every test file importing a changed file (git diff against base, default HEAD, untracked included) plus changed tests, likeliest failures first, with the command to run them and run_all when config or unanalyzed code changed. graph without symbol reads the indexed view: coverage, references and static calls in Java, Angular, Python and JS/TS/JSX/TSX; includes HTML/CSS/Markdown references and TXT/DOCX coverage; with file_path, narrows to that file's symbols, imports and calls (lists capped by limit). inspect lists the files of a view_id; with file_path, returns only that file's chunks. usage shows consumption and reuse; docs lists public functions without a docstring (Python docstring, JSDoc, Javadoc; private, nested and override functions excluded) with coverage percent, excluding tests unless include_tests=true, for documenting a project that started without it; duplicates lists duplicated functions (identical, near-identical and semantic bodies, min_similarity default 0.90; below that most pairs measured were false positives), excluding tests unless include_tests=true; fix real duplicates; only dismiss with duplicates_dismiss (finding_id, reason=false_positive|intentional, note) what is not a duplicate or is a copy kept on purpose: the finding stays hidden until the code changes, and duplicates_restore reopens it; integration shows the MCP client, hook and tool usage metrics; install_hook_preview shows the change that would install the hook redirecting Grep/Read to smart_search and WebSearch/WebFetch to web_search/web_fetch in this session's client and returns a plan_id; install_hook writes it with that plan_id and confirm=true, with a backup, only after the user approves the change; search_limits saves the project's default top_k per block ({code, test, doc}, each 1-20, total at most 20); storage shows disk usage and views; pin_view protects a view; cleanup_preview and cleanup_commit remove selected views after confirmation; compare compares two stored views, without checkout or embeddings. register adds a folder; preview checks the scope; index/rebuild update; pause/cancel keep checkpoints; resume continues; policy picks on_search/eager; scope adjusts the scope; remove deletes only the local index. Jobs via smart_search_result.",
         "inputSchema": {
             "type": "object", "properties": {
-                "action": {"type": "string", "enum": ["list", "status", "register", "preview", "index", "rebuild", "pause", "cancel", "resume", "watch", "scope", "remove", "relocate", "probe", "policy", "inspect", "graph", "usage", "storage", "pin_view", "cleanup_preview", "cleanup_commit", "compare", "search_limits", "integration", "install_hook_preview", "install_hook", "duplicates", "duplicates_dismiss", "duplicates_restore"]},
+                "action": {"type": "string", "enum": ["list", "status", "register", "preview", "index", "rebuild", "pause", "cancel", "resume", "watch", "scope", "remove", "relocate", "probe", "policy", "inspect", "graph", "usage", "storage", "pin_view", "cleanup_preview", "cleanup_commit", "compare", "search_limits", "integration", "install_hook_preview", "install_hook", "duplicates", "duplicates_dismiss", "duplicates_restore", "docs", "affected_tests"]},
                 "finding_id": {"type": "string"},
                 "reason": {"type": "string", "enum": ["false_positive", "intentional"]},
                 "note": {"type": "string"},
@@ -324,6 +325,9 @@ TOOLS = [
                 "left_view":{"type":"string"},"right_view":{"type":"string"},"relations":{"type":"boolean"},
                 "update_mode": {"type": "string", "enum": ["on_search", "eager"]},
                 "view_id": {"type": "string"}, "file_path": {"type": "string"},
+                "base": {"type": "string", "default": "HEAD", "description": "affected_tests: git revision the changes are compared with (HEAD = uncommitted work; main or origin/main for a branch)"},
+                "symbol": {"type": "string", "description": "graph: function, Class.method, class name or path::name to get its callers, calls, tests and importers"},
+                "depth": {"type": "integer", "minimum": 1, "maximum": 4, "default": 3, "description": "graph with symbol: call hops searched for tests"},
                 "project_root": {"type": "string"}, "project_id": {"type": "string"},
                 "job_id": {"type": "string"}, "watch": {"type": "boolean"},
                 "manual": {"type": "boolean"}, "force_scope": {"type": "boolean"},
@@ -1414,27 +1418,69 @@ def _find_duplicates(root, arguments, dismissed):
     return duplicates.find(root, embed, configured_model, float(similarity), include_tests, limit, dismissed, include_dismissed)
 
 
+def _with_project_id(arguments):
+    """Agents know the folder, not the id: project_root resolves to the registered project's project_id."""
+    root = arguments.get("project_root")
+    if arguments.get("project_id") or not isinstance(root, str) or arguments.get("action") in ("register", "relocate"):
+        return arguments
+    wanted = project_identity.canonical_root(root)
+    match = next((p for p in project_store.all_projects() if project_identity.canonical_root(p["root"]) == wanted), None)
+    if not match:
+        raise ValueError(f"No registered project at {root}; register it first (action=register).")
+    return {**arguments, "project_id": match["id"]}
+
+
+def _project_summary(project):
+    data = _project_payload(project)
+    index = data.get("index") or {}
+    jobs = data.get("jobs") or []
+    return {"project_id": data["id"], "name": data.get("name"), "root": data["root"], "status": data.get("status"),
+            "enabled": data.get("enabled"), "paused": data.get("paused"), "update_mode": data.get("update_mode"),
+            "files": index.get("files"), "chunks": index.get("chunks"), "last_indexed": data.get("last_indexed"),
+            "view": (data.get("view") or {}).get("label"), "active_jobs": len(data.get("active_jobs") or []),
+            "last_job": {k: jobs[0].get(k) for k in ("job_id", "status", "kind")} if jobs else None,
+            "last_error": (data.get("last_error") or None) and str(data["last_error"])[:200]}
+
+
 def _project_action(arguments):
     if not isinstance(arguments, dict):
         raise ValueError("Pass the action in a JSON object.")
+    arguments = _with_project_id(arguments)
     action = arguments.get("action", "list")
     if action == "probe":
         return _probe_index_models()
-    if action in ('graph','compare','duplicates','duplicates_dismiss','duplicates_restore'):
+    if action in ('graph','compare','duplicates','duplicates_dismiss','duplicates_restore','docs','affected_tests'):
         # Análise somente leitura pode demorar; não prende o lock global de ações.
         key=arguments.get('project_id')
         if not isinstance(key,str) or not re.fullmatch(r'[a-f0-9]{16}',key):
-            raise ValueError('Pass a valid project_id.')
+            raise ValueError('Pass project_root (the folder) or a valid project_id.')
         project=project_store.get(key)
         if not project:
             raise ValueError('Project not registered.')
         if action=='duplicates':
             return _find_duplicates(project['root'], arguments, project.get('dismissed_duplicates') or {})
+        if action=='docs':
+            import doc_check
+            include_tests=arguments.get('include_tests',False)
+            if type(include_tests) is not bool:
+                raise ValueError('include_tests must be true or false.')
+            limit=_parse_bounded_int(arguments.get('limit'),default=30,min_v=1,max_v=200,field_name='limit')
+            return doc_check.coverage(project['root'],include_tests,limit,arguments.get('view_id'))
+        if action=='affected_tests':
+            import affected_tests
+            limit=_parse_bounded_int(arguments.get('limit'),default=30,min_v=1,max_v=200,field_name='limit')
+            return affected_tests.affected(project['root'],arguments.get('base','HEAD'),limit,arguments.get('view_id'))
         if action in ('duplicates_dismiss','duplicates_restore'):
             return _change_dismissal(key, project, arguments, action == 'duplicates_dismiss')
         if action=='graph':
             import code_graph
-            return code_graph.build(project['root'],arguments.get('view_id'),file_path=arguments.get('file_path'))
+            import code_impact
+            limit=_parse_bounded_int(arguments.get('limit'),default=30,min_v=1,max_v=200,field_name='limit')
+            if arguments.get('symbol') is not None:
+                return code_impact.impact(project['root'],arguments['symbol'],arguments.get('view_id'),
+                                          arguments.get('depth',3),limit)
+            graph=code_graph.build(project['root'],arguments.get('view_id'),file_path=arguments.get('file_path'))
+            return code_impact.for_agent(graph,limit) if arguments.get('file_path') else graph
         import view_compare
         return view_compare.compare(project['root'],arguments.get('left_view'),arguments.get('right_view'),
                                     arguments.get('file_path'),arguments.get('relations',True))
@@ -1513,6 +1559,9 @@ def _project_action_locked(arguments):
         _metric("install_hook", target=result["client"], changed=result["changed"])
         return result
     if action == "list":
+        if not arguments.get("full"):
+            return {"projects": [_project_summary(p) for p in project_store.all_projects()],
+                    "detail": "Use action=status with project_id or project_root for scope, jobs and index details."}
         return {"projects": [_project_payload(p) for p in project_store.all_projects()],
                 "storage_dir": indexer.INDEX_DIR,
                 "gateway": dict(_GATEWAY_STATUS),
@@ -1526,7 +1575,7 @@ def _project_action_locked(arguments):
         return {"project": _project_payload(project)}
     key = arguments.get("project_id")
     if not isinstance(key, str) or not re.fullmatch(r"[a-f0-9]{16}", key):
-        raise ValueError("Pass a valid project_id; use the list action to look it up.")
+        raise ValueError("Pass project_root (the folder) or a valid project_id.")
     project = project_store.get(key)
     if not project:
         raise ValueError("Project not registered.")
@@ -1995,10 +2044,8 @@ def _fan_out_web_search(query, num, budget_s=None, site_domains=()):
             try:
                 fut.result()
                 _record_tier_health(tier_name, success=True)
-            except (TierSkipped, browser_service_client.BrowserSkipped):
-                pass
-            except Exception:
-                _record_tier_health(tier_name, success=False)
+            except Exception as exc:
+                _record_tier_failure(tier_name, exc)
         return _cb
 
     for fut, tier_name in futures.items():
@@ -2243,8 +2290,7 @@ def _search_web_once(query, num, scope, deadline=None, assess_semantic=False,
             if not raw_results:
                 raise RuntimeError("zero results in the requested domain")
         except Exception as exc:
-            if not isinstance(exc, TierSkipped):
-                _record_tier_health(tier_name, success=False)
+            _record_tier_failure(tier_name, exc)
             errors.append(_sanitize_text(f"{tier_name}: {type(exc).__name__}: {exc}"))
             continue
         _record_tier_health(tier_name, success=True)
@@ -2278,8 +2324,7 @@ def _search_web_once(query, num, scope, deadline=None, assess_semantic=False,
             if not raw_results:
                 raise RuntimeError("zero results in the requested domain")
         except Exception as exc:
-            if not isinstance(exc, (TierSkipped, browser_service_client.BrowserSkipped)):
-                _record_tier_health(tier_name, success=False)
+            _record_tier_failure(tier_name, exc)
             errors.append(_sanitize_text(f"{tier_name}: {type(exc).__name__}: {exc}"))
             continue
         _record_tier_health(tier_name, success=True)
@@ -2588,13 +2633,26 @@ def _annotate_quick_results(rows, classification, cache=None):
     return result
 
 
-def _record_tier_health(tier_name, success):
+def _record_tier_health(tier_name, success, outcome=None):
     try:
-        web_search_health.record(tier_name, success)
+        web_search_health.record(tier_name, success, outcome)
     except Exception:
         pass  # telemetria é best-effort — nunca pode derrubar uma busca já resolvida
 
 
+def _record_tier_failure(tier_name, exc):
+    """Health entry for a failed tier call, keeping a 429, a captcha and a quota pause apart from other errors."""
+    if isinstance(exc, (TierSkipped, browser_service_client.BrowserSkipped)):
+        outcome = "paused"
+    elif isinstance(exc, WebProviderRateLimited):
+        outcome = "rate_limited"
+    elif isinstance(exc, browser_service_client.BrowserCaptcha):
+        outcome = "captcha"
+    else:
+        outcome = "failed"
+    _record_tier_health(tier_name, False, outcome)
+
+
 _is_safe_crawl_target = web_fetch.is_safe_target
 
 
@@ -3073,6 +3131,7 @@ def _tool_result(text, is_error=False):
 
 WEB_FETCH_TIMEOUT_S = 90
 WEB_FETCH_RENDER_TIMEOUT_S = 60
+WEB_FETCH_VECTOR_ROOT = os.path.join(paths.DATA_DIR, "web-fetch")
 
 
 def _render_page(url, deadline):
@@ -3085,6 +3144,30 @@ def _render_page(url, deadline):
     return (pages[0].get("markdown") or "") if pages else ""
 
 
+def _web_fetch_embed(texts, deadline):
+    """Vectors for the pieces of a long page and the prompt, with the pieces cached per embedding model. Fails loudly
+    without an embedding model: a long page is never cut back to its start in silence."""
+    model = local_embedder.resolve(config.load_config().get("embedding_model"), None)
+    if not model or model == indexer.LEXICAL_MODEL:
+        raise RuntimeError("This page is longer than 60,000 characters and choosing its relevant parts needs an "
+                           "embedding_model, which is not configured")
+    try:
+        token = model_client.get_token()
+        probe = _embed(model, texts[-1:], token, deadline=deadline)
+        cache = embedding_cache.VectorCache(WEB_FETCH_VECTOR_ROOT, indexer.INDEX_DIR, {
+            "purpose": "web_fetch_pieces", "model": model, "dimensions": len(probe[0])})
+        try:
+            pieces = cache.embed(texts[:-1], lambda batch: _embed(model, batch, token, deadline=deadline),
+                                 indexer.validate_vector, split=lambda unique: list(_embed_batches(unique)),
+                                 workers=indexer.EMBED_WORKERS)
+        finally:
+            cache.db.close()
+    except Exception as exc:
+        raise RuntimeError(f"This page is longer than 60,000 characters and the embedding model ({model}) that picks "
+                           f"its relevant parts failed: {type(exc).__name__}: {exc}"[:400]) from None
+    return pieces + probe
+
+
 def _web_fetch_unavailable():
     cfg = config.load_config()
     if not cfg.get("router_model"):
@@ -3105,18 +3188,22 @@ def _handle_web_fetch(arguments):
             raise RuntimeError(f"Gateway model unavailable ({problem}).")
         deadline = started + WEB_FETCH_TIMEOUT_S
         page = web_fetch.read_page(url, deadline, _render_page)
-        text = web_fetch.answer(config.load_config()["router_model"], prompt, page, deadline)
+        selected, pieces = web_fetch.select(page["text"], prompt, lambda texts: _web_fetch_embed(texts, deadline))
+        text = web_fetch.answer(config.load_config()["router_model"], prompt, {**page, "text": selected}, deadline)
     except Exception as exc:
         web_fetch.mark_failed(str(url))
         _metric("web_fetch", error=type(exc).__name__, elapsed_s=round(time.monotonic() - started, 2))
         raise RuntimeError(f"web_fetch failed: {str(exc).rstrip('.')}. The native WebFetch is allowed for this URL for "
                            f"{web_fetch.FAILED_TTL_S // 60} min.") from None
     _metric("web_fetch", cached=page["cached"], rendered=page["rendered"], render_error=page.get("render_error"),
-            page_chars=len(page["text"]),
+            page_chars=page["chars"], read_chars=len(selected), pieces=pieces,
             answer_chars=len(text), elapsed_s=round(time.monotonic() - started, 2))
     origin = "from cache" if page["cached"] else "rendered in the browser" if page["rendered"] else "downloaded now"
     read_at = datetime.datetime.fromtimestamp(page["fetched_at"]).strftime("%Y-%m-%d %H:%M")
-    cut = "; page cut to the first 60,000 characters" if page["truncated"] else ""
+    cut = (f"; page of {page['chars']:,} characters: the {pieces} parts most related to the request were read"
+           if pieces else "")
+    if page["truncated"]:
+        cut += f"; only the first {web_fetch.PAGE_STORE_MAX_CHARS:,} characters were kept"
     return _sanitize_text(f"Source: {page['final_url']} (read at {read_at}, {origin}{cut})\n\n{text}")
 
 
@@ -3395,7 +3482,7 @@ class MCPHandler(BaseHTTPRequestHandler):
         if self.path == "/setup/projects":
             try:
                 setup_ui.require_token(self.headers)
-                self._write_json(200, _project_action({"action": "list"}))
+                self._write_json(200, _project_action({"action": "list", "full": True}))
             except setup_ui.SetupError as exc:
                 self._write_json(403, {"error": str(exc)})
             except Exception as exc:

package/version.py

@@ -1,7 +1,7 @@
 """Single source of the Smart Tool version and of the User-Agent sent to public APIs."""
 import re
 
-VERSION = "0.9.2"
+VERSION = "0.9.3"
 _CONTACT_RE = re.compile(r"^(?:[^\s@()<>;]+@[^\s@()<>;]+\.[^\s@()<>;]+|https?://[^\s()<>;]+)$")