@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.
- package/CHANGELOG.md +132 -0
- package/README.md +82 -18
- package/browser_control.py +10 -3
- package/browser_service_client.py +3 -32
- package/chromium_flags.py +30 -0
- package/client_hooks.py +10 -8
- package/code_health.py +182 -0
- package/code_impact.py +14 -2
- package/config.py +76 -8
- package/credential_check.py +38 -0
- package/dependency_notice.py +262 -14
- package/document_converter.py +221 -0
- package/document_read.py +100 -25
- package/document_text.py +194 -6
- package/dossier.py +71 -9
- package/embedding_cache.py +32 -8
- package/freshness.py +3 -2
- package/hook_decision.py +289 -18
- package/hooks/pretool_router.py +5 -4
- package/indexer.py +92 -3
- package/install.py +66 -27
- package/install_runtime.py +24 -10
- package/layer_check.py +57 -0
- package/link_check.py +69 -0
- package/local_embedder.py +115 -58
- package/locales/pt-BR.json +122 -18
- package/low_priority.py +41 -0
- package/model_client.py +1 -1
- package/model_health.py +24 -6
- package/notice_action.py +9 -0
- package/package.json +1 -1
- package/pr_comment.py +94 -0
- package/pr_impact.py +292 -8
- package/process_limits.py +108 -0
- package/project_admission.py +17 -15
- package/project_monitor.py +33 -7
- package/project_scheduler.py +12 -4
- package/removed_callers.py +146 -0
- package/scout.py +6 -2
- package/setup_audit.py +34 -1
- package/setup_ui.py +241 -41
- package/smart_tool_daemon.py +403 -91
- package/tray.py +29 -9
- package/update_check.py +18 -0
- package/update_splash.py +2 -2
- package/usage_meter.py +78 -0
- package/version.py +1 -1
- package/web_adapters/browser/crawl4ai_search.py +7 -3
- package/web_document_graph.py +12 -1
- package/web_fetch.py +24 -0
- 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
|
|
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.
|
|
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
|
|
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.
|
|
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.
|
|
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
|
|
149
|
-
the
|
|
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
|
|
272
|
-
|
|
273
|
-
the
|
|
274
|
-
|
|
275
|
-
|
|
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).
|
|
280
|
-
`.
|
|
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. **
|
|
339
|
-
|
|
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.
|
|
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
|
package/browser_control.py
CHANGED
|
@@ -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 = ("
|
|
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
|
|
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": {"
|
|
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 =
|
|
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
|
|
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
|
|
242
|
-
|
|
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
|
|
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
|
|
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])
|