@allansantos-dev/smart-tool 0.9.79 → 0.9.81

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/CHANGELOG.md +132 -0
  2. package/README.md +82 -18
  3. package/browser_control.py +10 -3
  4. package/browser_service_client.py +3 -32
  5. package/chromium_flags.py +30 -0
  6. package/client_hooks.py +10 -8
  7. package/code_health.py +182 -0
  8. package/code_impact.py +14 -2
  9. package/config.py +76 -8
  10. package/credential_check.py +38 -0
  11. package/dependency_notice.py +262 -14
  12. package/document_converter.py +221 -0
  13. package/document_read.py +100 -25
  14. package/document_text.py +194 -6
  15. package/dossier.py +71 -9
  16. package/embedding_cache.py +32 -8
  17. package/freshness.py +3 -2
  18. package/hook_decision.py +289 -18
  19. package/hooks/pretool_router.py +5 -4
  20. package/indexer.py +92 -3
  21. package/install.py +66 -27
  22. package/install_runtime.py +24 -10
  23. package/layer_check.py +57 -0
  24. package/link_check.py +69 -0
  25. package/local_embedder.py +115 -58
  26. package/locales/pt-BR.json +122 -18
  27. package/low_priority.py +41 -0
  28. package/model_client.py +1 -1
  29. package/model_health.py +24 -6
  30. package/notice_action.py +9 -0
  31. package/package.json +1 -1
  32. package/pr_comment.py +94 -0
  33. package/pr_impact.py +292 -8
  34. package/process_limits.py +108 -0
  35. package/project_admission.py +17 -15
  36. package/project_monitor.py +33 -7
  37. package/project_scheduler.py +12 -4
  38. package/removed_callers.py +146 -0
  39. package/scout.py +6 -2
  40. package/setup_audit.py +34 -1
  41. package/setup_ui.py +241 -41
  42. package/smart_tool_daemon.py +403 -91
  43. package/tray.py +29 -9
  44. package/update_check.py +18 -0
  45. package/update_splash.py +2 -2
  46. package/usage_meter.py +78 -0
  47. package/version.py +1 -1
  48. package/web_adapters/browser/crawl4ai_search.py +7 -3
  49. package/web_document_graph.py +12 -1
  50. package/web_fetch.py +24 -0
  51. package/web_search_health.py +31 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,137 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.9.81 - beta
4
+
5
+ - `pr_impact` lists the functions the diff adds that no function and no test calls (the candidates `dead_code` finds, which
6
+ already leave out framework and registered functions), in the section "New functions nothing calls". The section is
7
+ left out when the diff adds no function or every new one has a caller; a graph the analysis limits cut is said, and so is a
8
+ check that cannot run. `project_manage action=dead_code` also reports the graph cut (`graph_note`). Tests:
9
+ `tests/test_pr_impact.py`, `tests/test_code_health.py`.
10
+ - When an edit changes only the signature of a function (parameters, order, defaults, return annotation), the edit hook and
11
+ `pr_impact` list the callers outside the edited file, as they do for a removed or renamed function; the callers come from
12
+ the graph's resolved calls and its calls left unresolved by name, a graph the analysis limits cut is said instead of
13
+ claiming no caller, a name defined twice in one file (overloads) is not compared, and a failure is a visible note. Tests:
14
+ `tests/test_removed_callers.py`, `tests/test_pr_impact.py`.
15
+ - The edit hook notes a broken local link when an HTML or Markdown file is edited, and so do the review of files a shell
16
+ call wrote and `project_manage action=pr_impact`: a relative `href`, `src` or Markdown link target that the edit adds or
17
+ changes and that points to no file or folder, resolved against the edited file and read with the reader the code graph
18
+ uses. A link that was already broken, http(s), `mailto:`, `tel:`, `data:` and `#anchor` links are left out. What cannot be
19
+ checked is listed with the reason instead of being dropped: a path from the root of a site, a template expression, a page
20
+ with a `<base>` element, a target that cannot be looked up, HTML that did not parse. `link_mode` (`warn` default, or
21
+ `off`) in `config.json` and on the setup screen; it never blocks. Tests: `tests/test_link_check.py`.
22
+ - `project_manage action=pr_impact_comment pr=<number> base=<revision>` posts the `pr_impact` report as a comment on a pull
23
+ request through the `gh` CLI, from the project folder, and returns the comment URL. It writes to GitHub, so it is off
24
+ until the user turns on "Impact report as a pull request comment" in the setup screen (Agent rules; `pr_comment` in
25
+ `config.json`, `off` by default, any other value than `off` or `on` fails loudly); with it off, or with `gh` missing or
26
+ not logged in, it refuses before building anything. The comment ends with a hidden HTML marker: a rerun edits the last
27
+ comment that has it instead of stacking another, and the body shows no path of the user's machine. Tests:
28
+ `tests/test_pr_comment.py`, `tests/test_setup_integration.py`, `tests/test_setup_page_browser.py`.
29
+ - The edit hook names the decisions recorded about the functions an edit touches: for the first three functions in a code
30
+ file, up to two notes of the project (`docs/research`, the backlog, `CLAUDE.md`, `AGENTS.md`) that name the function, as
31
+ `path:line` and the title, so the agent does not undo what a note documents. A single-word function name counts only
32
+ when a note qualifies it as `module.name` or `Class.name`, a compound name as the bare identifier. Measured on 46
33
+ touched functions of this repository, the notes shown were about the function in 22 of 22 cases (the earlier rule: 11 of
34
+ 18; the raw search: 9 of 88) and the hook stayed silent on the 27 functions with no recorded decision. It reads files
35
+ only (no network, no model, no git history, 300 ms per function), says when it fails or is cut, and never blocks.
36
+ `decision_mode` (`warn`, default, or `off`) is on the Agent rules page of the setup screen; `pr_impact` uses the same rule
37
+ and also reads the commit messages. Tests: `tests/test_decision_notes.py`, `tests/test_pr_impact.py`. Measurement:
38
+ `docs/research/2026-11-18-decision-notes-keyword-quality.md`.
39
+ - The tray menu has "Open tray log": it opens `tray.log`, and says so when the file does not exist yet. Tests:
40
+ `tests/test_tray_notices.py`.
41
+ - A toast Windows refuses is also shown as a tray balloon with the text and the refusal (cut to the balloon limits) and is
42
+ still logged to `tray.log`; a balloon that fails is logged too, and the next notices are still shown. Tests:
43
+ `tests/test_tray_notices.py`.
44
+ - The toast that says a newer version is available has an "Update now" button (the `update-now` action): it starts the
45
+ update screen for that version, and refuses any version text that is not an npm version number. Tests:
46
+ `tests/test_update_check.py`.
47
+ - The failed-update toast carries the tag `update-failed`, so each tray start replaces it instead of stacking another one.
48
+ Tests: `tests/test_update_check.py`.
49
+ - The edit hook's checks also run after a shell call that wrote files (`sed -i`, a redirection, `npm install`, `cargo add`).
50
+ The PostToolUse entry of Claude Code (Bash and PowerShell) and, new, of Codex (Bash, through the same thin command with
51
+ `--post`) reviews the files git shows changed since `HEAD`, tracked or not, whose modification time is not older than the
52
+ start of that call, which the PreToolUse hook records by `tool_use_id`; files already changed before the call are left
53
+ out. The notes are the ones `pr_impact` already adds to a whole diff (`hook_decision.review_diff`), added to the
54
+ call's context, never a block. A git failure, a start that was not recorded or a review that cannot run comes back as a
55
+ `Smart Tool shell review skipped` note; a folder that is not a git repository is left alone. Codex needs the hook update
56
+ (and its approval) once to get the new entry. Tests: `tests/test_transparent_redirect.py`,
57
+ `tests/test_codex_audit_hook.py`, `tests/test_web_fetch.py`.
58
+ - The installer prints its messages in Portuguese when the user's language is Portuguese: the language picked in the
59
+ settings, else the Windows display language. Unreadable settings are reported on stderr and the Windows language is
60
+ used. `--language en|pt-BR` forces one; the update screen and the release install check pass `--language en`, because
61
+ they read the installer's English lines. The web runtime installer prints in the same language. Tests:
62
+ `tests/test_install_language.py`, `tests/test_update_splash.py`.
63
+ - The refusals a call gets when its folder cannot become a project ("Not indexing ...: it is a personal folder ...") follow
64
+ the language saved in the settings like the rest of the product: Portuguese when it is chosen, with the folders and the
65
+ reason kept in the text, and the same English text as before otherwise. Tests: `tests/test_project_admission.py`,
66
+ `tests/test_i18n.py`.
67
+
68
+ ## 0.9.80 - beta
69
+
70
+ - The document converter keeps its results in one folder per version, `%LOCALAPPDATA%\SmartTool\cache\<version>\convert`,
71
+ named by a hash of the file content, the engine and the OCR flag: the same file read again is answered from that folder
72
+ without starting the engine, a second run creates no file, two runs at once make one, a failed read leaves nothing, and
73
+ the folders of older versions are deleted the first time it is used. It no longer makes a new temporary folder in the
74
+ system temp for every read. Tests: `tests/test_document_converter.py`.
75
+ - The edit hook also notes a credential an edit writes, in any file: only on the lines the edit adds or changes, and only
76
+ for shapes that cannot be anything else (GitHub, Slack, Stripe live, Anthropic and npm tokens, Google API keys, AWS
77
+ access key ids and secret key lines, a private-key header at the start of a line). Lines that say they are an example are
78
+ skipped, the note names the file and line and never repeats the value, and it never blocks. Tests:
79
+ `tests/test_credential_check.py`.
80
+ - `project_manage action=pr_impact` adds two sections: the files that usually change in the same commits as the diff's files
81
+ and are missing from it (the history coupling of `doc_insights`, import-linked pairs left out), and the decision notes and
82
+ commit messages that name a touched function. A single-word function name counts only as a code reference (backticks or a
83
+ call), because words such as `load` or `report` are ordinary prose: measured on this repository, the bare-word match
84
+ returned unrelated notes for most single-word names. Tests: `tests/test_pr_impact.py`, `tests/test_code_health.py`.
85
+ - The dependency check reads `Cargo.toml` (crates.io: the dependency, dev-dependency and build-dependency tables, `target.*`
86
+ and `workspace.dependencies`; path, git and `workspace = true` entries are not registry packages) and `pom.xml` (Maven:
87
+ `groupId:artifactId`, `${property}` versions resolved from the pom's own properties; a range or a version inherited from a
88
+ parent or BOM is reported as not verified), on an edit and in the audit. The OSV names `crates.io` and `Maven` come from
89
+ the OSV schema. Tests: `tests/test_dependency_manifests.py`.
90
+ - Web search page: a table of who asked the recent searches, one row per client and project folder (sessions, calls,
91
+ failures, last call, how the requester was attributed), read from the log the search tiers already write; the text of a
92
+ search is never recorded. Tests: `tests/test_web_search_requesters.py`.
93
+ - Startup page: an automatic update card with the switch (the same `auto_update` key as the tray menu), the installed
94
+ version, the last npm check, the last update, a failed automatic try and the manual command, read from the state file with
95
+ no network call; the switch is refused while `SMART_TOOL_AUTO_UPDATE=off` is set, as in the tray. Tests:
96
+ `tests/test_update_card.py`.
97
+ - The browsers Smart Tool starts with Chromium (the Playwright MCP server the agent drives, its start-up probe, the
98
+ Tier 4 crawl) no longer scan USB devices: they carry `WebUsbDeviceDetection` in their `--disable-features`. The scan
99
+ ran a few seconds after launch and froze a USB microphone that was recording. Chromium keeps only the last
100
+ `--disable-features` switch and Playwright appends the caller's arguments after its own list, so the switch repeats
101
+ the list of the Playwright bundle in use and adds the feature; a bundle where that list cannot be found fails loudly.
102
+ Existing installs pick it up on the next update. Tests: `tests/test_chromium_flags.py`
103
+ (`docs/research/2026-11-17-webusb-do-navegador-de-automacao.md`).
104
+ - `web_fetch` reads Word, PowerPoint and Excel files by URL (docx, pptx, xlsx): by content type, or by the extension
105
+ in the URL when the server sends a generic binary type, through the extractor the index uses and its archive guards.
106
+ A file that cannot be read says why. Tests: `tests/test_web_fetch.py`.
107
+ - `project_manage action=deps` lists the OSV advisories of every dependency the project's manifests declare, in
108
+ batches of 100 per ecosystem (the edit notice shares the cache). `smart_search mode=dossier history=true` also
109
+ searches commit messages, and `smart_search decision_notes=true` appends the project's decision notes to a search
110
+ answer; both default to off. Tests: `tests/test_sister_candidates.py`.
111
+ - `read_document` also reads HTML (`.html`, `.htm`), CSV and EPUB files with no new dependency: the standard HTML and
112
+ CSV parsers, and the archive guards of the Office formats for the epub package (its chapters are read in spine
113
+ order). A page or book in an encoding the reader cannot use, or over the text budget, fails with the reason. Tests:
114
+ `tests/test_document_formats.py`.
115
+ - The dependency check reads `pyproject.toml` (`project.dependencies` and `project.optional-dependencies`; Poetry
116
+ tables are not read), both on an edit and in the audit. `project_manage action=deps` asks OSV about the version a
117
+ `package-lock.json` beside a `package.json` resolved when it satisfies the range (a stale lock, or a dependency missing
118
+ from it, keeps the lower bound of the range). The setup audit runs the same check for every registered project and
119
+ reports a warning per manifest with advisories, or a note when OSV cannot answer; the 6-hour advisory cache keeps the
120
+ 30-minute schedule from asking again. `read_document` and the index read `.xlsm` workbooks like `.xlsx` (XML parts
121
+ only; `.xlsb`, `.xls`, `.ppt` and `.pptm` stay unread). Tests: `tests/test_second_lens.py`.
122
+ - `project_manage action=pr_impact` lists the tests that reach each touched function, the functions no test reaches and
123
+ the notes the edit hook would have added to the whole diff, so commits made without the hook get the same checks.
124
+ New actions `hotspots`, `dead_code`, `import_cycles` and `comments` answer the questions the generated pages hold
125
+ without writing them. `layer_mode` (default `warn`, on the setup screen) flags an edit that adds a call from a lower
126
+ layer to a higher one of the confirmed layers. `smart_search` takes `folder` and `layer`, applied before ranking. The
127
+ setup screen shows the 30-day model use over every project and an hourly volume alert (twice the busiest hour of the
128
+ purpose's previous week, at least 100, mutable for 7 days, never a notification). Tests: `tests/test_pr_impact.py`,
129
+ `tests/test_code_health.py`, `tests/test_layer_check.py`, `tests/test_search_scope.py`,
130
+ `tests/test_usage_overview.py`.
131
+ - `smart_scout` answers with the best excerpt of a PDF, docx, pptx or xlsx: the window is chosen from the lines the
132
+ index stored for the file (`indexer.indexed_lines`) instead of falling back to the search snippet, and the document
133
+ is never extracted again. A file the index holds no lines of keeps the snippet. Tests: `tests/test_scout.py`.
134
+
3
135
  ## 0.9.79 - beta
4
136
 
5
137
  - A graph cut by its limits says what it left out: `left_out` with the files, symbols and call or import relations
package/README.md CHANGED
@@ -8,7 +8,7 @@ A local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharpe
8
8
  | `smart_scout` | Answers a question about the code with the lines that answer it: reads the candidate files inside Smart Tool and returns `path:lines` with the literal text, so the files never enter the agent's context; with a `scout_model`, a small model also writes a short answer and keeps only the lines that support it; a question about why something is as it is (why, reason, decided) also lists up to three decision notes from the notes the project keeps about its intent, as ids with one excerpt each |
9
9
  | `web_search` / `web_search_result` | Web search across several sources in parallel, in the query language and in English, with a cache shared across sessions; `depth="research"` runs a multi-round research loop |
10
10
  | `web_fetch` | Reads a known URL and returns only the answer to your prompt, written by a small model; pages are cached for 24 h. Pages over 60,000 characters are not cut: the model reads the parts closest to the prompt (needs an `embedding_model`) |
11
- | `read_document` | Reads a PDF, Word, PowerPoint or Excel file as compact text, a range at a time: type, size, page/slide/sheet count and estimated tokens first, then only the pages, slides or sheets asked for (`range="3-5"`), so the file never enters the agent's context whole. Opt-in: the native Read is not redirected. Scanned PDFs fail with that reason (no OCR) |
11
+ | `read_document` | Reads a PDF, Word, PowerPoint, Excel, HTML, CSV or EPUB file as compact text, a range at a time: type, size, page/slide/sheet/part/chapter count and estimated tokens first, then only the units asked for (`range="3-5"`), so the file never enters the agent's context whole. Opt-in: the native Read is not redirected. Scanned PDFs fail with that reason (no OCR) |
12
12
  | `project_manage` | Registers and indexes projects, shows coverage, code maps, duplicated functions and index storage; `graph` with `symbol` tells what changing a function touches: callers, calls, the tests that reach it and the files that import it |
13
13
 
14
14
  Agents that must click, type or log in also get Microsoft's [Playwright MCP](https://github.com/microsoft/playwright-mcp),
@@ -17,7 +17,7 @@ registered as the `playwright` server where this machine lets a browser be drive
17
17
  An optional hook routes the agent's native Grep/Glob/Read/Bash/WebSearch/WebFetch calls to these tools when they
18
18
  are cheaper, or just tells the agent what Smart Tool would do.
19
19
 
20
- **Status:** 0.9.79 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
20
+ **Status:** 0.9.81 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
21
21
 
22
22
  ## How it works
23
23
 
@@ -59,7 +59,8 @@ session on the machine, so the same question asked twice costs nothing the secon
59
59
  **Reading a page.** `web_fetch` takes a URL and a question. It downloads the page over plain HTTP; when the page only
60
60
  shows its content with JavaScript, it opens it in a headless browser ([Moli](https://github.com/lexmount/moli)
61
61
  first, Chromium as the fallback), which never reaches this machine or your local network. PDFs are read as text, page
62
- by page. A small model then reads the page and returns only the answer, with the source.
62
+ by page, and so are Word, PowerPoint and Excel files (docx, pptx, xlsx), by content type or by the extension of the URL
63
+ when the server sends a generic binary type. A small model then reads the page and returns only the answer, with the source.
63
64
  The agent receives a paragraph instead of the whole page.
64
65
 
65
66
  **Steering the agent (optional hook).** Agents keep reaching for their built-in tools out of habit. The hook sees
@@ -83,7 +84,7 @@ gateway such as Ollama, nothing about your code leaves the machine.
83
84
  ## Install
84
85
 
85
86
  ```powershell
86
- npx @allansantos-dev/smart-tool@0.9.79 install
87
+ npx @allansantos-dev/smart-tool@0.9.81 install
87
88
  ```
88
89
 
89
90
  Updates install themselves, on by default: the tray checks npm when it starts (at logon) and every 24 h, and when there
@@ -143,10 +144,13 @@ Redirects) and Maintenance (Setup audit, Startup).
143
144
  show again**) and the **New recommended models** card on this page offer them: nothing changes until you apply, the
144
145
  models you had are kept, and **Switch back to my previous models** undoes it. The **Model failures (last 24 h)** table
145
146
  groups the failed gateway calls by type (429, 503, other 5xx, timeout, connection, authentication) and role, with the count, the first and last time and one sample, and shows the calls per purpose; a model that fails half of its calls (5 or more) also raises a
146
- notification and a tray alert. A failure inside a tool call also comes back as a warning line in the tool answer;
147
+ notification and a tray alert. The **Model use (last 30 days)** card adds the calls, failures and, when the gateway
148
+ reports them, tokens and cost per purpose over every project, and flags a purpose whose calls in one hour pass twice
149
+ its own busiest hour of the previous week (and at least 100); the flag has **Mute for 7 days** and never raises a
150
+ notification. A failure inside a tool call also comes back as a warning line in the tool answer;
147
151
  calls made by a hook or by background work (index scope and profile, block-pattern proposals) have no answer to
148
- carry it, so they show only in the table, the log and the notification. The local embedder is not in that table or in
149
- the usage meter: it is a sidecar on your machine with no price, and its state is the **Local models** section.
152
+ carry it, so they show only in the table, the log and the notification. The embeddings home records its calls and failures there like any other model, with no price; its
153
+ state, and the reason when it cannot identify its model, is the **Embedder** section.
150
154
  3. **Agents**: register the MCP server in Claude Code or Codex (runs their official `mcp add` command), install the
151
155
  hook and choose its behavior under **Agent rules**. A hook written by an older Smart Tool shows as outdated, with
152
156
  what an update changes; updating previews the entry and rewrites only Smart Tool's, after a backup. Every
@@ -268,16 +272,55 @@ Redirects) and Maintenance (Setup audit, Startup).
268
272
  `llms.txt`; it never creates the file and rewrites only the block.
269
273
 
270
274
  **Impact of a change**: `project_manage action=pr_impact [base=main]` returns a Markdown report of the change set
271
- against `base` (default `HEAD`): the touched functions with their callers, the documentation anchors left out of
272
- date, and the tests to run with their commands. It reads only; publishing it as a pull-request comment is left to
273
- the CI step that calls it.
274
-
275
- **Dependency check on edit**: an edit of `package.json`, `requirements*.txt` or `go.mod` that adds or changes a dependency lists the OSV advisory IDs of up to 5 of them (exact version, or the lower bound of `^`, `~`, `~=` and `>=`), answered from a 6 h disk cache or one 2.5 s batch call that sends only package names and versions; when OSV cannot answer, the reminder says the check was skipped and the edit goes on. `dependency_mode` in `config.json`: `warn` (default) or `off`.
275
+ against `base` (default `HEAD`): the touched functions with their callers and the tests that reach them (the ones no
276
+ test reaches are listed apart), the documentation anchors left out of date, the decision notes and commits that name
277
+ a touched function (a single-word name counts only as a code reference), the files that usually change in the same
278
+ commits and are missing from the diff, the notes the edit hook would have added to the whole diff (comments, copies,
279
+ dependency advisories, credentials) and the tests to run with their commands. It reads
280
+ only. `project_manage action=pr_impact_comment pr=<number> base=<revision>` posts the same report as a comment on that
281
+ pull request through the `gh` CLI, from the project folder, and returns the comment URL. It writes to GitHub with your
282
+ own `gh` login, so it is off until you turn on "Impact report as a pull request comment" in the setup screen (Agent
283
+ rules; `"pr_comment": "on"` in `config.json`); with it off, or with `gh` missing or not logged in, it refuses and
284
+ posts nothing. A rerun edits the last Smart Tool comment (marked by a hidden HTML comment) instead of adding another,
285
+ and the body shows no path of your machine.
286
+
287
+ **Shape of the project**: `project_manage action=hotspots` ranks the code files by commits times lines (the
288
+ riskiest to change), `dead_code` lists the functions no code calls and those only tests call (static call graph,
289
+ candidates to read before deleting), `import_cycles` lists the groups of files that import each other, and
290
+ `comments` lists comments in the wrong place across the code files (commented-out code, history tags, loose docs,
291
+ long inline blocks), for code written before the edit hook existed. Each takes `limit` and writes nothing.
292
+
293
+ **Layers on edit**: when the project has confirmed layers (`.smart-tool/layers.json`), an edit that adds a call from
294
+ a lower layer to a function of a higher one is flagged to the agent; it never blocks. `layer_mode` in
295
+ `config.json`: `warn` (default) or `off`, also on the setup screen.
296
+
297
+ **Broken links on edit**: an edit of an HTML or Markdown file that adds or changes a relative link (`href`, `src`,
298
+ a Markdown link target) to a file that does not exist is flagged to the agent, with the links it could not check
299
+ (a path from the site root, a template expression, a `<base>` element); it never blocks. `link_mode` in
300
+ `config.json`: `warn` (default) or `off`, also on the setup screen.
301
+ **Recorded decisions on edit**: for the first three functions an edit touches in a code file, the hook names up to two
302
+ notes of the project (`docs/research`, the backlog, `CLAUDE.md`, `AGENTS.md`) that name the function, as `path:line` and
303
+ the title, so the agent reads what was decided before undoing it. A single-word function name counts only when a note
304
+ qualifies it as `module.name` or `Class.name`, a compound name as the bare identifier; the search reads files only (no
305
+ network, no model, no git history, 300 ms per function), says when it fails or is cut, and never blocks.
306
+ `decision_mode` in `config.json`: `warn` (default) or `off`, also on the setup screen. The measurement behind the rule is
307
+ in `docs/research/2026-11-18-decision-notes-keyword-quality.md`.
308
+
309
+ **Folder and layer in a search**: `smart_search folder="<path>"` (or a list) and `layer="<name>"` restrict the
310
+ search to a folder of the project or to one of its confirmed layers, by their path globs. The filter runs before
311
+ the ranking, so the results are the best inside the scope, not a cut of the global list.
312
+
313
+ **Credential check on edit**: the lines an edit adds or changes in any file are checked for credential shapes that cannot be
314
+ anything else (GitHub, Slack, Stripe live, Anthropic and npm tokens, Google API keys, AWS access key ids and secret key lines, a
315
+ private-key header at the start of a line); the note names the file and line, never repeats the value and never blocks, and a
316
+ line that says it is an example is skipped.
317
+
318
+ **Dependency check on edit**: an edit of `package.json`, `requirements*.txt`, `pyproject.toml` (`project.dependencies` and `project.optional-dependencies`; Poetry tables are not read), `go.mod`, `Cargo.toml` (crates.io registry dependencies) or `pom.xml` (Maven, plain or property-resolved versions) that adds or changes a dependency lists the OSV advisory IDs of up to 5 of them (exact version, or the lower bound of `^`, `~`, `~=` and `>=`), answered from a 6 h disk cache or one 2.5 s batch call that sends only package names and versions; when OSV cannot answer, the reminder says the check was skipped and the edit goes on. `dependency_mode` in `config.json`: `warn` (default) or `off`.
276
319
 
277
320
  **PDFs** inside a project are indexed as text with `[page N]` markers (20 MiB, 300 pages and 20 s per file; a scanned, password-protected or corrupt PDF is skipped with the reason), so `smart_search` returns the page that holds a passage. **Presentations and workbooks** (`.pptx`, `.xlsx`) are indexed the
278
321
  same way: text of each slide under `[slide N]` with the speaker notes under `[notes N]`, each sheet under `[sheet NAME]` with one
279
- tab-separated line per row (cached formula values; 100,000 rows or 1 MiB of text at most). Older formats (`.ppt`, `.xls`,
280
- `.xlsm`) are not read.
322
+ tab-separated line per row (cached formula values; 100,000 rows or 1 MiB of text at most). A macro-enabled `.xlsm` is read
323
+ like an `.xlsx` (its XML parts only, no macro runs). Older formats (`.ppt`, `.xls`, `.xlsb`, `.pptm`) are not read.
281
324
 
282
325
  **Block patterns waiting for you** are shown in one approval panel: 8 per page, the ones that would have blocked
283
326
  the most logged calls first, a filter over pattern, reason and example, and bulk accept or reject of the selected
@@ -306,6 +349,17 @@ Redirects) and Maintenance (Setup audit, Startup).
306
349
  unregisters them and deletes their index files (never the project's own files) and writes a manifest in
307
350
  `junk-manifests`. The daemon applies the same test at start.
308
351
 
352
+ `project_manage action=deps project_root="<project>"` lists the known OSV advisories of every dependency the manifests
353
+ of the project declare (`package.json`, `requirements*.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`), not only the ones an edit changed;
354
+ a `package.json` with a `package-lock.json` beside it is checked at the locked version when it satisfies the range. Only package
355
+ names and versions leave the machine, in batches of 100 per ecosystem. The setup audit runs the same check for every
356
+ registered project (a warning per manifest with advisories; the 6 h cache keeps it from asking OSV on every run).
357
+
358
+ `smart_search mode=dossier history=true` also searches the messages of the commits that have a body, and
359
+ `smart_search decision_notes=true` appends the decision notes of the project (research notes, backlog, CLAUDE.md,
360
+ AGENTS.md and commit messages) to a search answer; both are off by default, and the first read of a repository's
361
+ history can take longer than the dossier budget, which the answer then says.
362
+
309
363
  `project_manage` with `action=setup_audit` and a `project_root` (or `python setup_audit.py --project <folder>`)
310
364
  reports what Claude Code and Codex actually load for that folder (settings layers, enabled plugins of both,
311
365
  hooks, MCP servers, skills, CLAUDE.md and AGENTS.md) and where they collide: several hooks deciding on the same tool in
@@ -335,10 +389,20 @@ Redirects) and Maintenance (Setup audit, Startup).
335
389
  definition in `~/.codex/config.toml`, as `/hooks` would, so no `/hooks` step is left; an entry Codex does not trust
336
390
  shows "Not approved in Codex", and **Update** records it. It is off by default. The hook script
337
391
  (`hooks/session_audit.py`) only asks the running service and prints nothing when the service is down.
338
- 4. **Local models** (optional): if the mcp-memory embedding sidecar is installed on the machine, its local embedder
339
- can serve as a fallback (or preferred) embedding model.
392
+ 4. **Embedder**: the embeddings home (casa-de-embeddings, the embedding service of this machine, found through
393
+ `~/.casa-de-embeddings/run/daemon.json`) is the default; the gateway's `embedding_model` and `rerank_model` are used
394
+ only when you choose **Gateway** here, never in place of a stopped home. The home's embedder is identified by the
395
+ `model_sha256` and `dimension` of its `/info`; a home that answers without them is reported as an error, never
396
+ replaced silently by lexical search. Rerank goes through the home's connector to the rerank host configured in it;
397
+ without one, results keep the hybrid order and say so. Switching the embedder re-embeds each project in the
398
+ background, one at a time: the old index keeps answering, the folder switches to the new index when it is complete,
399
+ and the vectors of the old model are then deleted. While the home is not running, a folder indexed with another model
400
+ keeps answering from that index and is not updated.
340
401
  5. **Web search providers** work without keys on their free public tiers; add your own key for more volume. Set your
341
- own contact (e-mail or URL) if you want public APIs such as Wikimedia to see it in the User-Agent.
402
+ own contact (e-mail or URL) if you want public APIs such as Wikimedia to see it in the User-Agent. The same page lists
403
+ who asked the recent searches (client and project folder, never the text of a search).
404
+ 6. **Automatic updates** (Startup page): the switch the tray menu also has, with the installed version, the last npm check,
405
+ the last update and a failed automatic try; no network call is made to draw it.
342
406
 
343
407
  ## Writing a model adapter
344
408
 
@@ -390,7 +454,7 @@ fails to load is listed in the setup screen with its error and does not affect t
390
454
  ## Uninstall
391
455
 
392
456
  ```powershell
393
- npx @allansantos-dev/smart-tool@0.9.79 uninstall [--target DIR] [--keep-data]
457
+ npx @allansantos-dev/smart-tool@0.9.81 uninstall [--target DIR] [--keep-data]
394
458
  ```
395
459
 
396
460
  It asks nothing and opens no window. It stops the tray and the daemon, removes the logon task, the hook entries of Smart
@@ -29,6 +29,7 @@ import time
29
29
  import tomllib
30
30
 
31
31
  import atomic_io
32
+ import chromium_flags
32
33
  import codex_config
33
34
  import endpoint_sync
34
35
  import install_runtime
@@ -44,14 +45,19 @@ CONFIG_PATH = os.path.join(paths.DATA_DIR, "playwright-mcp.json")
44
45
  HANDSHAKE_PATH = os.path.join(paths.DATA_DIR, "playwright-mcp-handshake.json")
45
46
  PROXY = os.path.join(os.path.dirname(os.path.abspath(__file__)), "lazy_mcp_proxy.py")
46
47
  AGENT_UA_MARK = "SmartToolAgentBrowser"
48
+ MCP_PLAYWRIGHT_BUNDLE = install_runtime.NODE_DIR / "node_modules" / "playwright-core" / "lib" / "coreBundle.js"
47
49
  OUTPUT_MAX_BYTES = 100 * 1024 * 1024
48
50
  PROBE_TIMEOUT_S = 60
49
51
  DENIED_TOOLS = ("browser_run_code_unsafe",)
50
52
  _CODEX_TABLE_RE = re.compile(rf"^\[mcp_servers\.{SERVER}\][ \t]*\r?\n", re.M)
51
- _CHROMIUM_PROBE = ("from playwright.sync_api import sync_playwright\n"
53
+ _CHROMIUM_PROBE = ("import sys\n"
54
+ f"sys.path.insert(0, {os.path.dirname(os.path.abspath(__file__))!r})\n"
55
+ "import chromium_flags\n"
56
+ "from playwright.sync_api import sync_playwright\n"
52
57
  "with sync_playwright() as p:\n"
53
58
  " print(p.chromium.executable_path)\n"
54
- " b = p.chromium.launch(headless=True); print(b.new_page().evaluate('navigator.userAgent')); b.close()")
59
+ " b = p.chromium.launch(headless=True, args=chromium_flags.python_chromium_args())\n"
60
+ " print(b.new_page().evaluate('navigator.userAgent')); b.close()")
55
61
 
56
62
 
57
63
  def chromium():
@@ -100,7 +106,8 @@ def write_config(user_agent):
100
106
  a CORS request does not count it as an author header, so no preflight is added; a header in extraHTTPHeaders
101
107
  forced one on every cross-origin fetch and font."""
102
108
  os.makedirs(os.path.dirname(CONFIG_PATH), exist_ok=True)
103
- config = {"browser": {"contextOptions": {"userAgent": f"{user_agent} {AGENT_UA_MARK}"}}}
109
+ config = {"browser": {"launchOptions": {"args": [chromium_flags.disable_features_arg(MCP_PLAYWRIGHT_BUNDLE)]},
110
+ "contextOptions": {"userAgent": f"{user_agent} {AGENT_UA_MARK}"}}}
104
111
  atomic_io.write_secret_text(CONFIG_PATH, json.dumps(config, indent=1))
105
112
  return CONFIG_PATH
106
113
 
@@ -8,6 +8,8 @@ import threading
8
8
  import time
9
9
  import uuid
10
10
 
11
+ import process_limits
12
+
11
13
  START_TIMEOUT_S = 45
12
14
  START_FAILURE_COOLDOWN_S = 60
13
15
  SERVICE_IDLE_S = 300
@@ -28,37 +30,6 @@ class BrowserExited(RuntimeError):
28
30
  pass
29
31
 
30
32
 
31
- def _kill_on_close_job():
32
- import ctypes
33
- from ctypes import wintypes
34
-
35
- class IoCounters(ctypes.Structure):
36
- _fields_ = [(name, ctypes.c_ulonglong) for name in
37
- ("read_ops", "write_ops", "other_ops", "read_bytes", "write_bytes", "other_bytes")]
38
-
39
- class BasicLimits(ctypes.Structure):
40
- _fields_ = [("per_process_time", ctypes.c_longlong), ("per_job_time", ctypes.c_longlong),
41
- ("flags", wintypes.DWORD), ("min_ws", ctypes.c_size_t), ("max_ws", ctypes.c_size_t),
42
- ("active_processes", wintypes.DWORD), ("affinity", ctypes.c_size_t),
43
- ("priority", wintypes.DWORD), ("scheduling", wintypes.DWORD)]
44
-
45
- class ExtendedLimits(ctypes.Structure):
46
- _fields_ = [("basic", BasicLimits), ("io", IoCounters), ("process_memory", ctypes.c_size_t),
47
- ("job_memory", ctypes.c_size_t), ("peak_process_memory", ctypes.c_size_t),
48
- ("peak_job_memory", ctypes.c_size_t)]
49
-
50
- kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
51
- kernel32.CreateJobObjectW.restype = wintypes.HANDLE
52
- job = kernel32.CreateJobObjectW(None, None)
53
- if not job:
54
- raise ctypes.WinError(ctypes.get_last_error())
55
- limits = ExtendedLimits()
56
- limits.basic.flags = 0x2000 # JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
57
- if not kernel32.SetInformationJobObject(wintypes.HANDLE(job), 9, ctypes.byref(limits), ctypes.sizeof(limits)):
58
- raise ctypes.WinError(ctypes.get_last_error())
59
- return kernel32, job
60
-
61
-
62
33
  class BrowserService:
63
34
  def __init__(self, executable, script):
64
35
  self.executable = executable
@@ -126,7 +97,7 @@ class BrowserService:
126
97
  # Kill-on-close job: the browser tree dies with the daemon even when the daemon is killed hard.
127
98
  try:
128
99
  if self.job is None:
129
- self.job = _kill_on_close_job()
100
+ self.job = process_limits.kill_on_close_job()
130
101
  kernel32, job = self.job
131
102
  import ctypes
132
103
  from ctypes import wintypes
@@ -0,0 +1,30 @@
1
+ """Chromium switches carried by every automation browser launch of Smart Tool.
2
+
3
+ `WebUsbDeviceDetection` makes Chromium enumerate USB devices a few seconds after launch, which freezes a USB
4
+ microphone that is recording. Chromium keeps only the last `--disable-features` switch, and Playwright puts its own
5
+ list first and appends the caller's arguments, so a lone switch would drop Playwright's list: the switch built here
6
+ repeats the list of the Playwright bundle the browser is launched by and adds the feature to it.
7
+ """
8
+ import re
9
+ from pathlib import Path
10
+
11
+ WEB_USB_FEATURE = "WebUsbDeviceDetection"
12
+ _FEATURE_LIST = re.compile(r"\bdisabledFeatures = \[(.*?)\]\.filter\(", re.S)
13
+ _FEATURE_NAME = re.compile(r'^\s*"([A-Za-z0-9]+)"', re.M)
14
+
15
+
16
+ def disable_features_arg(bundle):
17
+ """The single `--disable-features` switch for a launch through the Playwright driver bundle `bundle`
18
+ (coreBundle.js): that bundle's own list plus WebUsbDeviceDetection. RuntimeError when the list is not found, so a
19
+ Playwright upgrade that moves it fails loudly instead of launching without the switch."""
20
+ found = _FEATURE_LIST.search(Path(bundle).read_text(encoding="utf-8"))
21
+ names = _FEATURE_NAME.findall(found.group(1)) if found else []
22
+ if not names:
23
+ raise RuntimeError(f"No disabledFeatures list in {bundle}; chromium_flags must follow this Playwright version.")
24
+ return "--disable-features=" + ",".join([*names, WEB_USB_FEATURE])
25
+
26
+
27
+ def python_chromium_args():
28
+ """Launch arguments for Chromium started by the Python Playwright package that is imported here."""
29
+ import playwright
30
+ return [disable_features_arg(Path(playwright.__file__).parent / "driver" / "package" / "lib" / "coreBundle.js")]
package/client_hooks.py CHANGED
@@ -40,7 +40,7 @@ CLIENTS = {
40
40
  "docs": "https://code.claude.com/docs/en/hooks", "event": "PreToolUse", "matcher": "Grep|Glob|Read|Bash|PowerShell|WebSearch|WebFetch|Edit|MultiEdit|Write|mcp__smart-tool__smart_search|mcp__smart-tool__web_search|mcp__smart-tool__web_fetch", "http": True,
41
41
  "post_matcher": "Grep|Bash|PowerShell|WebFetch|WebSearch"},
42
42
  "codex": {"label": "Codex", "prefix": "codex", "files": [os.path.join(endpoint_sync.codex_dir(), "hooks.json"), os.path.join(endpoint_sync.codex_dir(), "config.toml")],
43
- "docs": "https://learn.chatgpt.com/docs/hooks", "event": "PreToolUse", "matcher": "Bash|apply_patch",
43
+ "docs": "https://learn.chatgpt.com/docs/hooks", "event": "PreToolUse", "matcher": "Bash|apply_patch", "post_matcher": "Bash",
44
44
  "after_install": "Smart Tool recorded the approval of the new definition in Codex's config.toml, as /hooks "
45
45
  "would, so Codex runs it from the next session on."},
46
46
  "cursor": {"label": "Cursor", "prefix": "cursor", "files": [os.path.join(HOME, ".cursor", "hooks.json")],
@@ -64,7 +64,7 @@ def _our_hook(hook):
64
64
 
65
65
  def _entries(client):
66
66
  """{event: (matcher, handler)} of our hook entries for the client: the PreToolUse, plus the PostToolUse that returns
67
- the Smart Tool answer of a redirected call in Claude Code."""
67
+ the Smart Tool answer of a redirected call and the review of the files a shell call wrote."""
68
68
  spec = CLIENTS[client]
69
69
  entries = {spec["event"]: (spec["matcher"], _handler(client))}
70
70
  if spec.get("post_matcher"):
@@ -237,9 +237,11 @@ def _shell_safe(path):
237
237
  return path.replace("\\", "/")
238
238
 
239
239
 
240
- def _command(client):
241
- """The PreToolUse command of a client without HTTP hooks, signed with HOOK_ORIGIN at the end."""
242
- return f"{_shell_safe(sys.executable)} {_shell_safe(HOOK_SCRIPT)} --client {client} {HOOK_ORIGIN}"
240
+ def _command(client, route=HTTP_PATH):
241
+ """The command of a client without HTTP hooks for the PreToolUse route (default) or the PostToolUse one, signed with
242
+ HOOK_ORIGIN at the end."""
243
+ after = " --post" if route == POST_PATH else ""
244
+ return f"{_shell_safe(sys.executable)} {_shell_safe(HOOK_SCRIPT)} --client {client}{after} {HOOK_ORIGIN}"
243
245
 
244
246
 
245
247
  def _port_file():
@@ -253,14 +255,14 @@ def _port_file():
253
255
 
254
256
  def _handler(client, route=HTTP_PATH, timeout=HTTP_TIMEOUT_S):
255
257
  """Claude Code posts the payload straight to the warm daemon (`type: "http"`, no process per tool call); other
256
- clients run the thin command that forwards to the PreToolUse route."""
258
+ clients run the thin command that forwards to the route."""
257
259
  if CLIENTS[client].get("http"):
258
260
  registry = daemon_launcher.read_registry()
259
261
  if not registry or not registry.get("url"):
260
262
  raise ValueError("Smart Tool daemon has no registered URL; start the daemon before installing the hook.")
261
263
  query = f"client={client}&hook-origin={OWNER}&port-file={_port_file()}"
262
264
  return {"type": "http", "url": f"{registry['url']}{route}?{query}", "timeout": timeout}
263
- return {"type": "command", "command": _command(client), "timeout": timeout}
265
+ return {"type": "command", "command": _command(client, route), "timeout": timeout}
264
266
 
265
267
 
266
268
  def _slot(groups, is_ours):
@@ -340,7 +342,7 @@ def install(client_info, token, confirm):
340
342
 
341
343
 
342
344
  def remove(client):
343
- """Takes every redirect hook entry of ours (PreToolUse, and the PostToolUse of Claude Code) out of the client's hooks
345
+ """Takes every redirect hook entry of ours (PreToolUse and PostToolUse) out of the client's hooks
344
346
  file after a backup; other hooks stay, in Codex at the approval of their new index. Returns {client, changed, file,
345
347
  backup}."""
346
348
  path = os.path.realpath(CLIENTS[client]["files"][0])