@allansantos-dev/smart-tool 0.9.80 → 0.9.82
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 +129 -0
- package/NOTICE +1 -1
- package/README.md +59 -14
- package/agent_redirect.py +32 -0
- package/autostart.py +32 -25
- package/browser_bridge.py +320 -0
- package/browser_control.py +76 -39
- package/browser_service_client.py +1 -7
- package/client_hooks.py +42 -41
- package/code_graph.py +56 -15
- package/code_graph_java.mjs +21 -12
- package/code_health.py +19 -12
- package/code_impact.py +1 -1
- package/codex_config.py +3 -0
- package/config.py +35 -0
- package/daemon_launcher.py +37 -5
- package/doc_candidates.py +63 -0
- package/doc_check.py +9 -3
- package/doc_extras.py +2 -3
- package/doc_insights.py +26 -2
- package/doc_prose.py +59 -11
- package/doc_registry.py +241 -0
- package/doc_scope.py +205 -39
- package/doc_turn.py +205 -0
- package/doc_validate.py +52 -9
- package/document_read.py +4 -2
- package/dossier.py +40 -5
- package/edit_shape.py +119 -0
- package/endpoint_sync.py +3 -21
- package/engine_home.py +95 -0
- package/hook_call.py +132 -0
- package/hook_decision.py +337 -23
- package/hooks/pretool_router.py +36 -29
- package/hooks/turn_end.py +40 -0
- package/index_views.py +5 -0
- package/install.py +90 -36
- package/install_runtime.py +24 -10
- package/lazy_mcp_proxy.py +10 -9
- package/link_check.py +69 -0
- package/local_embedder.py +9 -2
- package/locales/pt-BR.json +72 -4
- package/model_breaker.py +6 -5
- package/model_client.py +1 -1
- package/model_health.py +24 -6
- package/notice_action.py +9 -0
- package/package.json +2 -2
- package/pr_comment.py +94 -0
- package/pr_impact.py +216 -35
- package/process_limits.py +17 -3
- package/project_admission.py +17 -15
- package/project_identity.py +19 -1
- package/project_scan.py +98 -0
- package/removed_callers.py +146 -0
- package/scout_access.py +48 -0
- package/setup_ui.py +33 -4
- package/shell_reads.py +67 -0
- package/smart_tool_daemon.py +149 -39
- package/tray.py +60 -9
- package/update_splash.py +2 -2
- package/venv_launch.py +67 -0
- package/version.py +1 -1
- package/web_adapters/node/engine-home.mjs +42 -0
- package/web_adapters/node/package-lock.json +13 -0
- package/web_adapters/node/package.json +1 -0
- package/web_document_graph.py +12 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,134 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.9.82 - beta
|
|
4
|
+
|
|
5
|
+
- The edit hook adds two lines to its note, both read from what is already cached and silent otherwise (no analysis is
|
|
6
|
+
started, no `git` runs): the import cycle a Python import the edit adds at module level closes in the indexed import
|
|
7
|
+
graph, named with its chain of files, and the hotspot (top ten by commits times lines, ten commits or more) or the file
|
|
8
|
+
that usually changes with an edited one and is not in the edit. Context only, never a denial. `import_cycles`,
|
|
9
|
+
`hotspots` and `coupled_with` keep their answers; `code_graph.cached_graph` and `doc_insights.cached_history` are the new
|
|
10
|
+
cache-only readers.
|
|
11
|
+
- The Claude Code hooks (PreToolUse, PostToolUse, SubagentStart, Stop) are command hooks now, like Codex's, instead of
|
|
12
|
+
`http` hooks with the daemon port written into `settings.json`. The hook reads the daemon's run file on every call and
|
|
13
|
+
waits out a restart with backoff (up to 10 s), so a restart or an install prints nothing; a daemon that stays
|
|
14
|
+
unreachable lets the call through with one plain message naming the hook, its owner, the cause and what happened to the
|
|
15
|
+
call, and the next calls stay silent until the daemon answers. Claude Code's own `hook failed: read ECONNRESET` and
|
|
16
|
+
`connect ECONNREFUSED` lines came from the http transport and could not be changed. The cost is one short process per
|
|
17
|
+
hooked call (about 0.2 s on this machine against 11 ms). `settings.json` holds no port, so a port change rewrites no
|
|
18
|
+
hook; an older entry shows as outdated until the hook is installed again (Agent rules). Codex entries pass `--route`
|
|
19
|
+
instead of `--post`.
|
|
20
|
+
- Claude Code subagents now start knowing about the Smart Tool: a SubagentStart hook (`/hooks/subagent-start`, installed
|
|
21
|
+
with the other hooks and removed by uninstall) tells each one that, for a question across several files, its first call
|
|
22
|
+
is `smart_scout`, before Grep or Read. It adds context only and never denies; `hook_mode` off says nothing. Measured in
|
|
23
|
+
isolation: 8 of 8 subagents used the Smart Tool with it against 4 of 8 without.
|
|
24
|
+
- The PreToolUse hook also covers subagent launches (`Agent`, `Task`): an Explore launch with a short, targeted prompt
|
|
25
|
+
carries a tip with the `smart_scout` call to make, in redirect and advise modes; the launch is never denied, and every
|
|
26
|
+
other launch (coding, whole-product or broad reviews, web research, other agent types) gets nothing. Off mode says
|
|
27
|
+
nothing, and so does a session where `smart_scout` cannot be called without a permission prompt (a mode that allows
|
|
28
|
+
every tool, or an allow rule for the tool, its server or `mcp__smart-tool__*`, and no deny rule).
|
|
29
|
+
- A third source file read through the shell (`cat`, `head`, `sed -n`) in ten minutes carries a tip to call `smart_scout`
|
|
30
|
+
(redirect and advise modes, no blocking; off says nothing, and only where `smart_scout` is callable). A single read is
|
|
31
|
+
never touched: the shell is what a known file needs and `smart_search` cannot return its exact lines. The subagent start
|
|
32
|
+
sentence also names `smart_search`.
|
|
33
|
+
- **The generated documentation format changes; regenerate `docs/scope` once.** The symbol marker of each entry now
|
|
34
|
+
carries body and docstring stamps next to the signature (`signature="…" body="…" docstring="…"`), so
|
|
35
|
+
`action=docs check=true`, the edit hook, `docs symbol=` and validation also catch a body or docstring changed under
|
|
36
|
+
the same signature (`body_changed`, `docstring_changed`). A page in the older format fails loud and asks to
|
|
37
|
+
regenerate (`action=docs generate=true`, which keeps the written prose); there is no compatibility mode. The
|
|
38
|
+
`code="…"` stamp of a feature's paragraph now covers the entry point and every function its flow reaches, so a
|
|
39
|
+
change deep in the flow marks the paragraph stale: paragraphs written before this version are reported stale once.
|
|
40
|
+
- Each technical entry names the features whose flow reaches it (`- Feature: [name](functional.md#…)` or
|
|
41
|
+
`- Feature: none`); feature sections list their functions without the old cut at 12; a new `chain` check of validation
|
|
42
|
+
fails when one side names a link the other does not.
|
|
43
|
+
- **A Claude Code hook is added**: installing the hook now also writes a `Stop` entry of type `command`
|
|
44
|
+
(`hooks/turn_end.py … --hook-origin=smart-tool`), which reads the daemon address from its run file on every call and
|
|
45
|
+
fails loud with its origin when the daemon is down. At the end of a turn in a project with a generated `docs/scope`,
|
|
46
|
+
the daemon rewrites without a model only the pages of the functions the turn changed (at most 20 functions and 60
|
|
47
|
+
chain nodes per turn, 2 attempts per function), rewrites with the docs model only the stale paragraphs of the
|
|
48
|
+
features they belong to (a rejected paragraph keeps its old text and is reported), proposes up to two "possible"
|
|
49
|
+
features from the embeddings home for a public function no entry point reaches (status candidate, never confirmed by
|
|
50
|
+
the embedder), and blocks the turn once with the docstrings to check against a new body. A continuation of the
|
|
51
|
+
session (`stop_hook_active`) exits at once. Uninstalling removes the entry.
|
|
52
|
+
- **A database is added**: `~/.smart-tool/data/doc_registry.db`, a per-function registry in its own SQLite file (WAL,
|
|
53
|
+
`synchronous=FULL`) with the stamps of the code and of its documentation, the dates, a status and the feature links.
|
|
54
|
+
The stamps in the pages stay the truth, so a lost registry is rebuilt from them; work a crash interrupted resumes at
|
|
55
|
+
daemon start, at the next end of turn and at a session's first call.
|
|
56
|
+
- Java: the line checks of validation take the bare method name, so Java methods (with or without parameters,
|
|
57
|
+
overloads included) no longer fail them, and a call through a field typed by an interface the project declares
|
|
58
|
+
becomes an edge to the declared method (methods inherited from a library stay unresolved).
|
|
59
|
+
- Tests: `tests/test_doc_chain.py`, `tests/test_code_graph_java.py`, Java cases in `tests/test_doc_validate.py`.
|
|
60
|
+
- `project_manage action=credentials` scans every git-tracked text file from disk and lists the file and line of each
|
|
61
|
+
credential shape (never the value), so a token committed earlier or sitting in a `.env` file is reported, which the
|
|
62
|
+
edit hook and the index (it skips `.env`, `.pem`, `.key`) cannot do. `action=links` lists the relative links in the
|
|
63
|
+
tracked HTML and Markdown files that point to a missing file, and the links it could not decide (root-relative,
|
|
64
|
+
template expressions, pages with a `<base>` element) as unchecked, not broken. Both take `limit` and write nothing.
|
|
65
|
+
Tests: `tests/test_project_scan.py`.
|
|
66
|
+
|
|
67
|
+
## 0.9.81 - beta
|
|
68
|
+
|
|
69
|
+
- `pr_impact` lists the functions the diff adds that no function and no test calls (the candidates `dead_code` finds, which
|
|
70
|
+
already leave out framework and registered functions), in the section "New functions nothing calls". The section is
|
|
71
|
+
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
|
|
72
|
+
check that cannot run. `project_manage action=dead_code` also reports the graph cut (`graph_note`). Tests:
|
|
73
|
+
`tests/test_pr_impact.py`, `tests/test_code_health.py`.
|
|
74
|
+
- When an edit changes only the signature of a function (parameters, order, defaults, return annotation), the edit hook and
|
|
75
|
+
`pr_impact` list the callers outside the edited file, as they do for a removed or renamed function; the callers come from
|
|
76
|
+
the graph's resolved calls and its calls left unresolved by name, a graph the analysis limits cut is said instead of
|
|
77
|
+
claiming no caller, a name defined twice in one file (overloads) is not compared, and a failure is a visible note. Tests:
|
|
78
|
+
`tests/test_removed_callers.py`, `tests/test_pr_impact.py`.
|
|
79
|
+
- 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
|
|
80
|
+
call wrote and `project_manage action=pr_impact`: a relative `href`, `src` or Markdown link target that the edit adds or
|
|
81
|
+
changes and that points to no file or folder, resolved against the edited file and read with the reader the code graph
|
|
82
|
+
uses. A link that was already broken, http(s), `mailto:`, `tel:`, `data:` and `#anchor` links are left out. What cannot be
|
|
83
|
+
checked is listed with the reason instead of being dropped: a path from the root of a site, a template expression, a page
|
|
84
|
+
with a `<base>` element, a target that cannot be looked up, HTML that did not parse. `link_mode` (`warn` default, or
|
|
85
|
+
`off`) in `config.json` and on the setup screen; it never blocks. Tests: `tests/test_link_check.py`.
|
|
86
|
+
- `project_manage action=pr_impact_comment pr=<number> base=<revision>` posts the `pr_impact` report as a comment on a pull
|
|
87
|
+
request through the `gh` CLI, from the project folder, and returns the comment URL. It writes to GitHub, so it is off
|
|
88
|
+
until the user turns on "Impact report as a pull request comment" in the setup screen (Agent rules; `pr_comment` in
|
|
89
|
+
`config.json`, `off` by default, any other value than `off` or `on` fails loudly); with it off, or with `gh` missing or
|
|
90
|
+
not logged in, it refuses before building anything. The comment ends with a hidden HTML marker: a rerun edits the last
|
|
91
|
+
comment that has it instead of stacking another, and the body shows no path of the user's machine. Tests:
|
|
92
|
+
`tests/test_pr_comment.py`, `tests/test_setup_integration.py`, `tests/test_setup_page_browser.py`.
|
|
93
|
+
- The edit hook names the decisions recorded about the functions an edit touches: for the first three functions in a code
|
|
94
|
+
file, up to two notes of the project (`docs/research`, the backlog, `CLAUDE.md`, `AGENTS.md`) that name the function, as
|
|
95
|
+
`path:line` and the title, so the agent does not undo what a note documents. A single-word function name counts only
|
|
96
|
+
when a note qualifies it as `module.name` or `Class.name`, a compound name as the bare identifier. Measured on 46
|
|
97
|
+
touched functions of this repository, the notes shown were about the function in 22 of 22 cases (the earlier rule: 11 of
|
|
98
|
+
18; the raw search: 9 of 88) and the hook stayed silent on the 27 functions with no recorded decision. It reads files
|
|
99
|
+
only (no network, no model, no git history, 300 ms per function), says when it fails or is cut, and never blocks.
|
|
100
|
+
`decision_mode` (`warn`, default, or `off`) is on the Agent rules page of the setup screen; `pr_impact` uses the same rule
|
|
101
|
+
and also reads the commit messages. Tests: `tests/test_decision_notes.py`, `tests/test_pr_impact.py`. Measurement:
|
|
102
|
+
`docs/research/2026-11-18-decision-notes-keyword-quality.md`.
|
|
103
|
+
- The tray menu has "Open tray log": it opens `tray.log`, and says so when the file does not exist yet. Tests:
|
|
104
|
+
`tests/test_tray_notices.py`.
|
|
105
|
+
- A toast Windows refuses is also shown as a tray balloon with the text and the refusal (cut to the balloon limits) and is
|
|
106
|
+
still logged to `tray.log`; a balloon that fails is logged too, and the next notices are still shown. Tests:
|
|
107
|
+
`tests/test_tray_notices.py`.
|
|
108
|
+
- The toast that says a newer version is available has an "Update now" button (the `update-now` action): it starts the
|
|
109
|
+
update screen for that version, and refuses any version text that is not an npm version number. Tests:
|
|
110
|
+
`tests/test_update_check.py`.
|
|
111
|
+
- The failed-update toast carries the tag `update-failed`, so each tray start replaces it instead of stacking another one.
|
|
112
|
+
Tests: `tests/test_update_check.py`.
|
|
113
|
+
- The edit hook's checks also run after a shell call that wrote files (`sed -i`, a redirection, `npm install`, `cargo add`).
|
|
114
|
+
The PostToolUse entry of Claude Code (Bash and PowerShell) and, new, of Codex (Bash, through the same thin command with
|
|
115
|
+
`--post`) reviews the files git shows changed since `HEAD`, tracked or not, whose modification time is not older than the
|
|
116
|
+
start of that call, which the PreToolUse hook records by `tool_use_id`; files already changed before the call are left
|
|
117
|
+
out. The notes are the ones `pr_impact` already adds to a whole diff (`hook_decision.review_diff`), added to the
|
|
118
|
+
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
|
|
119
|
+
`Smart Tool shell review skipped` note; a folder that is not a git repository is left alone. Codex needs the hook update
|
|
120
|
+
(and its approval) once to get the new entry. Tests: `tests/test_transparent_redirect.py`,
|
|
121
|
+
`tests/test_codex_audit_hook.py`, `tests/test_web_fetch.py`.
|
|
122
|
+
- The installer prints its messages in Portuguese when the user's language is Portuguese: the language picked in the
|
|
123
|
+
settings, else the Windows display language. Unreadable settings are reported on stderr and the Windows language is
|
|
124
|
+
used. `--language en|pt-BR` forces one; the update screen and the release install check pass `--language en`, because
|
|
125
|
+
they read the installer's English lines. The web runtime installer prints in the same language. Tests:
|
|
126
|
+
`tests/test_install_language.py`, `tests/test_update_splash.py`.
|
|
127
|
+
- The refusals a call gets when its folder cannot become a project ("Not indexing ...: it is a personal folder ...") follow
|
|
128
|
+
the language saved in the settings like the rest of the product: Portuguese when it is chosen, with the folders and the
|
|
129
|
+
reason kept in the text, and the same English text as before otherwise. Tests: `tests/test_project_admission.py`,
|
|
130
|
+
`tests/test_i18n.py`.
|
|
131
|
+
|
|
3
132
|
## 0.9.80 - beta
|
|
4
133
|
|
|
5
134
|
- The document converter keeps its results in one folder per version, `%LOCALAPPDATA%\SmartTool\cache\<version>\convert`,
|
package/NOTICE
CHANGED
package/README.md
CHANGED
|
@@ -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.82 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
|
|
21
21
|
|
|
22
22
|
## How it works
|
|
23
23
|
|
|
@@ -84,7 +84,7 @@ gateway such as Ollama, nothing about your code leaves the machine.
|
|
|
84
84
|
## Install
|
|
85
85
|
|
|
86
86
|
```powershell
|
|
87
|
-
npx @allansantos-dev/smart-tool@0.9.
|
|
87
|
+
npx @allansantos-dev/smart-tool@0.9.82 install
|
|
88
88
|
```
|
|
89
89
|
|
|
90
90
|
Updates install themselves, on by default: the tray checks npm when it starts (at logon) and every 24 h, and when there
|
|
@@ -172,10 +172,13 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
172
172
|
`browser_run_code_unsafe`, which runs arbitrary JavaScript in the server process, is denied in the client
|
|
173
173
|
(`permissions.deny` in `~/.claude/settings.json`, `disabled_tools` in `~/.codex/config.toml`); if it cannot be
|
|
174
174
|
denied, the server is not registered. A `playwright` server you registered yourself is never touched. Remove it with
|
|
175
|
-
`claude mcp remove playwright -s user` / `codex mcp remove playwright`.
|
|
176
|
-
proxy (`lazy_mcp_proxy.py`, standard library only) that answers the handshake and the tool list from a cache
|
|
177
|
-
probe writes and starts the Node server on the first tool call, so a session that never opens a browser does
|
|
178
|
-
keep a 97 MB Node process; it ends with the session.
|
|
175
|
+
`claude mcp remove playwright -s user` / `codex mcp remove playwright`. Claude Code's registered command is a small
|
|
176
|
+
stdio proxy (`lazy_mcp_proxy.py`, standard library only) that answers the handshake and the tool list from a cache
|
|
177
|
+
the probe writes and starts the Node server on the first tool call, so a session that never opens a browser does
|
|
178
|
+
not keep a 97 MB Node process; it ends with the session. The browser tools reach Codex through the daemon URL
|
|
179
|
+
(`url = "<daemon>/playwright/mcp"` in `~/.codex/config.toml`, next to the smart-tool entry) instead of one proxy per
|
|
180
|
+
conversation thread: the daemon answers the handshake from the same cache and starts one shared Node server on the
|
|
181
|
+
first tool call, with a browser context of its own for each Codex thread, and stops it after an hour without calls.
|
|
179
182
|
|
|
180
183
|
**Who asked for a web search**: every provider call in `~/.smart-tool/data/web-search-health.jsonl` and every
|
|
181
184
|
record of `research-metrics.jsonl` made for a `web_search` carries `requester`: `client`, `mcp_session` (first 12
|
|
@@ -254,10 +257,17 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
254
257
|
context read from the code, and a paragraph is written only when every name, option and version it cites exists in
|
|
255
258
|
the code and it is in English; a rejected one is asked again once with the reason, then reported with its fix. A call stops after about
|
|
256
259
|
40 s and says how many blocks are left. The prose can also be written by hand between the markers; regenerating keeps it, reports blocks whose module
|
|
257
|
-
or entry point is gone, and never overwrites a file that Smart Tool did not write. Each anchor records the signature
|
|
258
|
-
it was generated from: `action=docs check=true` lists anchors whose function changed
|
|
259
|
-
to missing anchors and entry paragraphs written for
|
|
260
|
-
|
|
260
|
+
or entry point is gone, and never overwrites a file that Smart Tool did not write. Each anchor records the signature,
|
|
261
|
+
body and docstring it was generated from: `action=docs check=true` lists anchors whose function changed any of the
|
|
262
|
+
three or is gone, links to missing anchors and entry paragraphs written for older code of their feature (the
|
|
263
|
+
`code="..."` stamp of the block covers the entry point and every function its flow reaches; delete it after
|
|
264
|
+
rewriting the paragraph by hand). Each technical entry names the features it belongs to (`Feature: ...` or
|
|
265
|
+
`Feature: none`) and each feature lists its functions, and validation checks that both sides agree. With the Claude
|
|
266
|
+
Code hook installed, a Stop hook runs the end-of-turn step: the pages of the functions the turn changed are rewritten
|
|
267
|
+
without a model, the stale paragraphs of their features are rewritten by the docs model, a public function no entry
|
|
268
|
+
point reaches gets up to two "possible" features from the embeddings home (never confirmed by it), and the agent is
|
|
269
|
+
asked once to check a docstring whose function body changed; a per-function registry
|
|
270
|
+
(`~/.smart-tool/data/doc_registry.db`) keeps that work across crashes. `action=docs validate=true` checks every claim of `docs/scope` against the code and writes `docs/scope/validation.md`, `action=docs symbol=NAME` tells where a function is documented, and the documentation hook warns
|
|
261
271
|
when an edit makes a documented entry out of date. The link lives in the documents, never inside docstrings.
|
|
262
272
|
The same run writes fifteen optional documents under `docs/scope/extras`, all from the graph and the git log: folder
|
|
263
273
|
structure, docstring coverage per folder, module Mermaid, tests README, configuration read by the code, dependencies
|
|
@@ -277,18 +287,39 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
277
287
|
a touched function (a single-word name counts only as a code reference), the files that usually change in the same
|
|
278
288
|
commits and are missing from the diff, the notes the edit hook would have added to the whole diff (comments, copies,
|
|
279
289
|
dependency advisories, credentials) and the tests to run with their commands. It reads
|
|
280
|
-
only
|
|
290
|
+
only. `project_manage action=pr_impact_comment pr=<number> base=<revision>` posts the same report as a comment on that
|
|
291
|
+
pull request through the `gh` CLI, from the project folder, and returns the comment URL. It writes to GitHub with your
|
|
292
|
+
own `gh` login, so it is off until you turn on "Impact report as a pull request comment" in the setup screen (Agent
|
|
293
|
+
rules; `"pr_comment": "on"` in `config.json`); with it off, or with `gh` missing or not logged in, it refuses and
|
|
294
|
+
posts nothing. A rerun edits the last Smart Tool comment (marked by a hidden HTML comment) instead of adding another,
|
|
295
|
+
and the body shows no path of your machine.
|
|
281
296
|
|
|
282
297
|
**Shape of the project**: `project_manage action=hotspots` ranks the code files by commits times lines (the
|
|
283
298
|
riskiest to change), `dead_code` lists the functions no code calls and those only tests call (static call graph,
|
|
284
299
|
candidates to read before deleting), `import_cycles` lists the groups of files that import each other, and
|
|
285
300
|
`comments` lists comments in the wrong place across the code files (commented-out code, history tags, loose docs,
|
|
286
|
-
long inline blocks), for code written before the edit hook existed.
|
|
301
|
+
long inline blocks), for code written before the edit hook existed. `credentials` lists, per git-tracked text file
|
|
302
|
+
(read from disk, so `.env` files and old commits count), the file and line of each credential shape and never the
|
|
303
|
+
value; `links` lists the relative links in tracked HTML and Markdown files that point to a missing file, and the ones
|
|
304
|
+
it could not decide (root-relative, template expressions, pages with a `<base>` element) as unchecked, not broken.
|
|
305
|
+
Each takes `limit` and writes nothing.
|
|
287
306
|
|
|
288
307
|
**Layers on edit**: when the project has confirmed layers (`.smart-tool/layers.json`), an edit that adds a call from
|
|
289
308
|
a lower layer to a function of a higher one is flagged to the agent; it never blocks. `layer_mode` in
|
|
290
309
|
`config.json`: `warn` (default) or `off`, also on the setup screen.
|
|
291
310
|
|
|
311
|
+
**Broken links on edit**: an edit of an HTML or Markdown file that adds or changes a relative link (`href`, `src`,
|
|
312
|
+
a Markdown link target) to a file that does not exist is flagged to the agent, with the links it could not check
|
|
313
|
+
(a path from the site root, a template expression, a `<base>` element); it never blocks. `link_mode` in
|
|
314
|
+
`config.json`: `warn` (default) or `off`, also on the setup screen.
|
|
315
|
+
**Recorded decisions on edit**: for the first three functions an edit touches in a code file, the hook names up to two
|
|
316
|
+
notes of the project (`docs/research`, the backlog, `CLAUDE.md`, `AGENTS.md`) that name the function, as `path:line` and
|
|
317
|
+
the title, so the agent reads what was decided before undoing it. A single-word function name counts only when a note
|
|
318
|
+
qualifies it as `module.name` or `Class.name`, a compound name as the bare identifier; the search reads files only (no
|
|
319
|
+
network, no model, no git history, 300 ms per function), says when it fails or is cut, and never blocks.
|
|
320
|
+
`decision_mode` in `config.json`: `warn` (default) or `off`, also on the setup screen. The measurement behind the rule is
|
|
321
|
+
in `docs/research/2026-11-18-decision-notes-keyword-quality.md`.
|
|
322
|
+
|
|
292
323
|
**Folder and layer in a search**: `smart_search folder="<path>"` (or a list) and `layer="<name>"` restrict the
|
|
293
324
|
search to a folder of the project or to one of its confirmed layers, by their path globs. The filter runs before
|
|
294
325
|
the ranking, so the results are the best inside the scope, not a cut of the global list.
|
|
@@ -298,6 +329,16 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
298
329
|
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
|
|
299
330
|
line that says it is an example is skipped.
|
|
300
331
|
|
|
332
|
+
**Import cycles and history on edit**: two more lines of the edit note, read only from what is already cached (the
|
|
333
|
+
code graph analysis and the git history the daemon holds in memory), so the hook never waits for an analysis and never
|
|
334
|
+
runs `git`; with nothing cached they say nothing. A Python import the edit adds at module level (an import inside a
|
|
335
|
+
function is the usual way to break a cycle and is skipped) that names a project file with a way back to the edited
|
|
336
|
+
file in the indexed import graph is flagged with the chain (`a.py -> b.py -> c.py -> a.py`). A code file in the ten
|
|
337
|
+
riskiest by commits times lines (the `hotspots` ranking) with at least ten commits is named a hotspot, and a file
|
|
338
|
+
outside the edit that usually changes in the same commits as an edited one (the `coupled_with` rule: hidden coupling
|
|
339
|
+
without an import between them) is named as its partner. They add context only, never block, and follow the modes of
|
|
340
|
+
the other edit notes (all of them `off` silences the review).
|
|
341
|
+
|
|
301
342
|
**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`.
|
|
302
343
|
|
|
303
344
|
**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
|
|
@@ -374,7 +415,11 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
374
415
|
(`hooks/session_audit.py`) only asks the running service and prints nothing when the service is down.
|
|
375
416
|
4. **Embedder**: the embeddings home (casa-de-embeddings, the embedding service of this machine, found through
|
|
376
417
|
`~/.casa-de-embeddings/run/daemon.json`) is the default; the gateway's `embedding_model` and `rerank_model` are used
|
|
377
|
-
only when you choose **Gateway** here, never in place of a stopped home.
|
|
418
|
+
only when you choose **Gateway** here, never in place of a stopped home. With the home chosen, the service installs
|
|
419
|
+
it when it is missing, brings it to the registry's version when it is older (the engine registry's kit checks the
|
|
420
|
+
SHA-256 and the Ed25519 signature of the asset) and starts it, looking again once a day and ten minutes after a
|
|
421
|
+
failure; a home that already answers at the registry's version or newer is left alone, and when it cannot be brought
|
|
422
|
+
up, searches stay lexical and the warning names the reason. The home's embedder is identified by the
|
|
378
423
|
`model_sha256` and `dimension` of its `/info`; a home that answers without them is reported as an error, never
|
|
379
424
|
replaced silently by lexical search. Rerank goes through the home's connector to the rerank host configured in it;
|
|
380
425
|
without one, results keep the hybrid order and say so. Switching the embedder re-embeds each project in the
|
|
@@ -437,7 +482,7 @@ fails to load is listed in the setup screen with its error and does not affect t
|
|
|
437
482
|
## Uninstall
|
|
438
483
|
|
|
439
484
|
```powershell
|
|
440
|
-
npx @allansantos-dev/smart-tool@0.9.
|
|
485
|
+
npx @allansantos-dev/smart-tool@0.9.82 uninstall [--target DIR] [--keep-data]
|
|
441
486
|
```
|
|
442
487
|
|
|
443
488
|
It asks nothing and opens no window. It stops the tray and the daemon, removes the logon task, the hook entries of Smart
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
"""PreToolUse tip for a subagent launch (Claude Code `Agent`/`Task`): a launch of a search-only subagent for a
|
|
2
|
+
targeted question carries the Smart Tool call that answers it, and every other launch (coding, whole-product
|
|
3
|
+
reviews, web research, custom or ambiguous types) gets nothing. The launch itself is never denied."""
|
|
4
|
+
import re
|
|
5
|
+
|
|
6
|
+
LAUNCH_TOOLS = frozenset({"Agent", "Task"})
|
|
7
|
+
SEARCH_ONLY_TYPES = frozenset({"Explore"})
|
|
8
|
+
MAX_PROMPT_CHARS = 1500
|
|
9
|
+
BROAD_SCOPE = re.compile(
|
|
10
|
+
r"\b(review|audit|assess|inventory|survey|broad|whole|entire|every|each file|all files|all the|across the "
|
|
11
|
+
r"(?:repo|repository|product|codebase|project)|revis\w*|audit\w*|invent[aá]rio|inteir[oa]|todos os|todas as|"
|
|
12
|
+
r"produto todo|em todo)\b", re.I)
|
|
13
|
+
WEB_SCOPE = re.compile(r"https?://|\b(web|internet|online|documenta[cç][aã]o oficial|official docs)\b", re.I)
|
|
14
|
+
|
|
15
|
+
LAUNCH_TIP = (
|
|
16
|
+
"for a search like this, call "
|
|
17
|
+
"mcp__smart-tool__smart_scout(project_root, question) yourself (project_root is your working directory). It reads "
|
|
18
|
+
"the files inside Smart Tool and returns only the lines that answer, at a fraction of the cost of a subagent.")
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def reason(payload):
|
|
22
|
+
"""The tip for a launch of a search-only subagent with a short, targeted prompt, or None when the
|
|
23
|
+
launch should run: another tool, another subagent type, a long prompt, a broad-scope or web-research wording."""
|
|
24
|
+
if not isinstance(payload, dict) or payload.get("tool_name") not in LAUNCH_TOOLS:
|
|
25
|
+
return None
|
|
26
|
+
tool_input = payload.get("tool_input") if isinstance(payload.get("tool_input"), dict) else {}
|
|
27
|
+
prompt = str(tool_input.get("prompt") or "")
|
|
28
|
+
if tool_input.get("subagent_type") not in SEARCH_ONLY_TYPES or not prompt.strip():
|
|
29
|
+
return None
|
|
30
|
+
if len(prompt) > MAX_PROMPT_CHARS or BROAD_SCOPE.search(prompt) or WEB_SCOPE.search(prompt):
|
|
31
|
+
return None
|
|
32
|
+
return LAUNCH_TIP
|
package/autostart.py
CHANGED
|
@@ -1,17 +1,20 @@
|
|
|
1
1
|
#!/usr/bin/env python3
|
|
2
2
|
"""Autostart do Smart Tool no logon do Windows — Tarefa Agendada por usuário (sem
|
|
3
|
-
admin)
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
3
|
+
admin). `schtasks /Create` pode ser bloqueado por política de grupo corporativa
|
|
4
|
+
(máquina AD-joined); nesse caso cai automaticamente para um script na pasta Startup
|
|
5
|
+
do usuário. Os dois rodam o mesmo VBScript, que sobe o `tray.py` no Python base com
|
|
6
|
+
a venv (`venv_launch`): a Tarefa Agendada não passa variável de ambiente, e o
|
|
7
|
+
redirecionador da venv deixaria dois processos por bandeja. O loop de polling do
|
|
8
|
+
próprio `tray.py` cobre "se o daemon cair, sobe de novo".
|
|
8
9
|
"""
|
|
9
10
|
import os
|
|
10
11
|
import subprocess
|
|
11
12
|
import sys
|
|
12
13
|
import tempfile
|
|
13
14
|
|
|
15
|
+
import paths
|
|
14
16
|
import toast_notice
|
|
17
|
+
import venv_launch
|
|
15
18
|
|
|
16
19
|
TASK_NAME = os.environ.get("SMART_TOOL_TASK_NAME", "SmartTool-Tray")
|
|
17
20
|
# The tray runs under pythonw (no console): schtasks without this flag flashed a console each time its menu was drawn.
|
|
@@ -52,8 +55,8 @@ def _current_user_id():
|
|
|
52
55
|
|
|
53
56
|
def _task_xml():
|
|
54
57
|
user_id = _xml_escape(_current_user_id())
|
|
55
|
-
|
|
56
|
-
|
|
58
|
+
wscript = _xml_escape(_wscript_path())
|
|
59
|
+
script = _xml_escape(_write_launch_script(_task_script_path()))
|
|
57
60
|
workdir = _xml_escape(_tool_dir())
|
|
58
61
|
return (
|
|
59
62
|
'<?xml version="1.0" encoding="UTF-16"?>\r\n'
|
|
@@ -84,15 +87,11 @@ def _task_xml():
|
|
|
84
87
|
' <Enabled>true</Enabled>\r\n'
|
|
85
88
|
' <Hidden>false</Hidden>\r\n'
|
|
86
89
|
' <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>\r\n'
|
|
87
|
-
' <RestartOnFailure>\r\n'
|
|
88
|
-
' <Interval>PT1M</Interval>\r\n'
|
|
89
|
-
' <Count>999</Count>\r\n'
|
|
90
|
-
' </RestartOnFailure>\r\n'
|
|
91
90
|
' </Settings>\r\n'
|
|
92
91
|
' <Actions Context="Author">\r\n'
|
|
93
92
|
' <Exec>\r\n'
|
|
94
|
-
f' <Command>{
|
|
95
|
-
f' <Arguments
|
|
93
|
+
f' <Command>{wscript}</Command>\r\n'
|
|
94
|
+
f' <Arguments>//B //NoLogo "{script}"</Arguments>\r\n'
|
|
96
95
|
f' <WorkingDirectory>{workdir}</WorkingDirectory>\r\n'
|
|
97
96
|
' </Exec>\r\n'
|
|
98
97
|
' </Actions>\r\n'
|
|
@@ -111,20 +110,24 @@ def _startup_script_path():
|
|
|
111
110
|
return os.path.join(_startup_dir(), "SmartTool-Tray.vbs")
|
|
112
111
|
|
|
113
112
|
|
|
114
|
-
def
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
113
|
+
def _task_script_path():
|
|
114
|
+
return os.path.join(paths.DATA_DIR, "tray-start.vbs")
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def _wscript_path():
|
|
118
|
+
return os.path.join(os.environ.get("SystemRoot", r"C:\Windows"), "System32", "wscript.exe")
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def _write_launch_script(path):
|
|
122
|
+
"""Writes the VBScript that starts the tray hidden in one process and returns its path."""
|
|
123
|
+
os.makedirs(os.path.dirname(path), exist_ok=True)
|
|
124
|
+
with open(path, "w", encoding="utf-16") as f:
|
|
125
|
+
f.write(venv_launch.hidden_run_vbs(_pythonw_path(), _tray_path(), _tool_dir()))
|
|
126
|
+
return path
|
|
118
127
|
|
|
119
128
|
|
|
120
129
|
def _install_startup_shortcut():
|
|
121
|
-
|
|
122
|
-
vbs = (
|
|
123
|
-
'Set shell = CreateObject("WScript.Shell")\r\n'
|
|
124
|
-
f'shell.Run {_vbs_quoted_run(_pythonw_path(), _tray_path())}, 0, False\r\n'
|
|
125
|
-
)
|
|
126
|
-
with open(_startup_script_path(), "w", encoding="utf-8") as f:
|
|
127
|
-
f.write(vbs)
|
|
130
|
+
_write_launch_script(_startup_script_path())
|
|
128
131
|
return {"ok": True, "method": "startup_folder"}
|
|
129
132
|
|
|
130
133
|
|
|
@@ -148,7 +151,7 @@ def _task_installed():
|
|
|
148
151
|
|
|
149
152
|
|
|
150
153
|
def install():
|
|
151
|
-
"""Tenta a Tarefa Agendada primeiro
|
|
154
|
+
"""Tenta a Tarefa Agendada primeiro; se
|
|
152
155
|
`schtasks /Create` falhar por qualquer motivo (ex.: bloqueado por politica de
|
|
153
156
|
grupo corporativa, `schtasks` fora do PATH, timeout), cai para o atalho de
|
|
154
157
|
Startup em vez de propagar o erro."""
|
|
@@ -192,6 +195,10 @@ def remove():
|
|
|
192
195
|
pass
|
|
193
196
|
if _remove_startup_shortcut():
|
|
194
197
|
removed.append("startup_folder")
|
|
198
|
+
try:
|
|
199
|
+
os.remove(_task_script_path())
|
|
200
|
+
except FileNotFoundError:
|
|
201
|
+
pass
|
|
195
202
|
if sys.platform == "win32" and toast_notice.unregister():
|
|
196
203
|
removed.append("toast_registry")
|
|
197
204
|
return {"ok": True, "removed": removed}
|