@allansantos-dev/smart-tool 0.0.0-stage → 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.9.0 - beta
+
+First release for beta testers. Windows only.
+
+- `smart_search`: semantic + lexical search (Weaviate-style relative score fusion), results split into code, tests and
+  docs, likeliest functions per chunk, per-project language profile; asks the calling agent to define the scope when no
+  scope model is configured.
+- `web_search`: parallel sources (DuckDuckGo, Yahoo, Wikipedia, Exa, Parallel, Keenable, Google and Startpage through a
+  resident browser), bilingual queries, cache shared across sessions with volatility checks, research mode.
+- `web_fetch`: reads a known URL and returns only the answer to the prompt, 24 h page cache, browser rendering for
+  JavaScript pages.
+- Model gateway through adapters: built-in OpenAI-compatible adapter; user adapters as Python files in
+  `~/.smart-tool/adapters`.
+- Optional local embedder through the mcp-memory sidecar when the gateway has no embedding model.
+- PreToolUse hook for Claude Code (HTTP to the daemon) and Codex (thin command), with Redirect, Advise only and Off modes.
+- Setup screen: model gateway, models, agents (MCP registration, hook install, hook behavior), web provider keys,
+  contact for public APIs, local models, start at logon.
+- The daemon owns its port: falls back to a free port and rewrites the smart-tool URLs the clients keep.
+- Install and update with `npx @allansantos-dev/smart-tool@latest install`: the package brings uv (checksum verified)
+  and a private Python 3.12 in `~/.smart-tool/runtime`, so only Node.js is required. The tray offers the update command
+  when npm has a newer version. Product page on GitHub Pages.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,32 @@
+Smart Tool
+Copyright 2026 Allan Santos
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Smart Tool does not bundle third-party code. The installer downloads the components below from their official
+sources into the installation folder or the user's profile; each keeps its own license.
+
+Python packages (installation venv, from PyPI)
+- ddgs (MIT)
+- trafilatura (Apache-2.0)
+- pystray (LGPL-3.0; used unmodified as a library)
+- Pillow (MIT-CMU)
+- PyYAML (MIT)
+
+Browser runtime (web_adapters/browser/.venv, from PyPI and the projects' download servers)
+- camoufox Python package (MIT) and the Camoufox browser, a Firefox fork (MPL-2.0), fetched by `camoufox fetch`
+- crawl4ai (Apache-2.0), https://github.com/unclecode/crawl4ai: page rendering is powered by Crawl4AI
+- Playwright (Apache-2.0) and the Chromium build it installs (BSD-style, see https://www.chromium.org)
+
+Node runtime and packages (web_adapters/node, from nodejs.org and npm)
+- Node.js, downloaded only when no supported Node is installed (MIT and bundled licenses)
+- open-websearch (Apache-2.0)
+- typescript (Apache-2.0)
+- java-parser (Apache-2.0)
+- @angular/compiler (MIT)
+- their dependencies as pinned in web_adapters/node/package-lock.json (MIT, ISC, BSD and Apache-2.0)
+
+Web search sources
+Smart Tool queries public search engines and APIs (DuckDuckGo, Yahoo, Wikipedia, Exa, Parallel, Keenable, Google and
+Startpage through a local browser, and optionally Tavily and Firecrawl with your own key). Using them is subject to
+each service's terms of use; free tiers are rate limited per IP address.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Smart Tool
+
+A local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharper tools than their built-in search:
+
+| Tool | What it does |
+|---|---|
+| `smart_search` / `smart_search_result` | Semantic + lexical search over an indexed project, results split into code, tests and docs, with the likeliest functions per chunk |
+| `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 |
+| `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 |
+| `project_manage` | Registers and indexes projects, shows coverage, code maps, duplicated functions and index storage |
+
+An optional hook routes the agent's native Grep/Glob/Read/Bash/WebSearch/WebFetch calls to these tools when they
+are cheaper, or just tells the agent what Smart Tool would do.
+
+**Status:** 0.9.0 beta. Windows only.
+
+## Requirements
+
+- Windows 10 or 11 (x64) and Node.js 18 or newer for `npx`. Python is not needed: the installer brings its own.
+- About 1 GB of downloads on first install (Python 3.12 and its packages, Node.js when no supported version is
+  installed, the Camoufox and Chromium browsers used for pages that need JavaScript).
+- An OpenAI-compatible model API for embeddings and small chat calls (OpenAI, OpenRouter, a LiteLLM proxy, Ollama...).
+  Web search works without it; smart_search falls back to lexical search.
+
+## Install
+
+```powershell
+npx @allansantos-dev/smart-tool@latest install
+```
+
+Run the same command to update; `~/.smart-tool` is kept. It downloads [uv](https://docs.astral.sh/uv/) (checksum
+verified) and a private Python 3.12 into `~/.smart-tool/runtime`, with nothing added to `PATH` or the registry, then
+copies Smart Tool to `%LOCALAPPDATA%\Programs\SmartTool` with its own virtual environment,
+installs the web runtime, registers a per-user Scheduled Task that starts the tray at logon and starts the daemon on
+`http://127.0.0.1:8765` (another free port is used, and announced, if 8765 is taken).
+
+State lives in `~/.smart-tool`: `config.json`, your model adapters in `adapters/` and indexes, caches and logs in
+`data/`. Secrets (API keys) are encrypted with Windows DPAPI for your user.
+
+## Set up
+
+Open the setup screen from the tray icon ("Open settings") or at `http://127.0.0.1:8765/setup`.
+
+1. **Model gateway**: pick an adapter and fill its fields. The built-in **OpenAI-compatible** adapter takes a base
+   URL ending where the API starts, like the OpenAI SDK `base_url` (`https://api.openai.com/v1`,
+   `https://openrouter.ai/api/v1`, `http://localhost:11434/v1`), and an optional API key. Saving tests `/models` first.
+2. **Models**: embedding, rerank (optional; without it results use the hybrid order), the router model (small, no
+   reasoning: it decides before tool calls), the index classification model and the research model. Any id the gateway
+   accepts works; the catalog is shown as suggestions.
+3. **Agents**: register the MCP server in Claude Code or Codex (runs their official `mcp add` command), install the
+   hook and choose its behavior:
+   - **Redirect** (default): the native tool is denied with the reason and the Smart Tool tool to use.
+   - **Advise only**: the native tool runs; the agent receives the same advice next to the result and decides.
+   - **Off**: no routing.
+4. **Local models** (optional): if the mcp-memory embedding sidecar is installed on the machine, its local embedder
+   can serve as a fallback (or preferred) embedding model.
+5. **Web search providers** work without keys on their free public tiers; add your own key for more volume. Set your
+   own contact (e-mail or URL) if you want public APIs such as Wikimedia to see it in the User-Agent.
+
+## Writing a model adapter
+
+An adapter is a Python file in `~/.smart-tool/adapters/`. It appears in the setup screen next to the built-in one.
+
+```python
+import json
+import urllib.request
+
+NAME = "my_gateway"            # unique id
+LABEL = "My gateway"           # shown in the setup screen
+FIELDS = (                     # rendered as inputs; secret values are stored with DPAPI
+    {"name": "url", "label": "Address", "required": True, "placeholder": "http://10.0.0.5"},
+    {"name": "token", "label": "Token", "secret": True},
+)
+
+
+def request(options, route, body=None, timeout=15):
+    """route is OpenAI-style: models, model/info, embeddings, chat/completions, rerank. body None means GET.
+    Return (parsed JSON, response headers); let urllib.error.HTTPError propagate."""
+    data = json.dumps(body).encode() if body is not None else None
+    headers = {"Content-Type": "application/json"}
+    if options.get("token"):
+        headers["Authorization"] = "Bearer " + options["token"]
+    req = urllib.request.Request(f"{options['url']}/v1/{route}", data=data, headers=headers)
+    with urllib.request.urlopen(req, timeout=timeout) as response:
+        return json.load(response), response.headers
+
+
+def verify(options):
+    """Raise RuntimeError with a reason a person can act on."""
+    request(options, "models", timeout=10)
+```
+
+Embeddings and chat use the OpenAI request and response formats; rerank uses the Cohere/Jina format served by
+LiteLLM (`{"model", "query", "documents", "top_n"}` returning `results[].index` and `relevance_score`). A file that
+fails to load is listed in the setup screen with its error and does not affect the others.
+
+## Data and privacy
+
+- Indexed code stays on your machine. Chunks are sent to your model gateway to compute embeddings, and small excerpts
+  go to its chat models (scope, profile, routing, web_fetch answers). Use a local gateway (Ollama, LiteLLM) to keep
+  everything local.
+- Web queries go to the search sources listed in `NOTICE`. Their free tiers are rate limited per IP address; respect
+  each service's terms of use.
+- Logs and metrics are written to `~/.smart-tool/data` and never leave the machine.
+
+## Uninstall
+
+Turn off "Start automatically" in the setup screen, quit from the tray, remove the hook entries from
+`~/.claude/settings.json` / `~/.codex/hooks.json` (the setup screen shows them), run `claude mcp remove smart-tool -s
+user` / `codex mcp remove smart-tool`, then delete `%LOCALAPPDATA%\Programs\SmartTool` and `~/.smart-tool`.
+
+## License
+
+Apache License 2.0. See `LICENSE` and `NOTICE` for third-party components.
+
+Page rendering is powered by [Crawl4AI](https://github.com/unclecode/crawl4ai) (Apache-2.0).

package/atomic_io.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Gravação atômica de arquivo pequeno de estado/credencial, compartilhada pelos módulos
+do Smart Tool."""
+import glob
+import os
+import time
+import uuid
+
+_REPLACE_ATTEMPTS = 4
+_REPLACE_BACKOFF_S = 0.05
+TMP_SUFFIX = ".tmp."
+ORPHAN_AGE_S = 300
+
+
+def rotate(path, max_bytes):
+    """Keeps one previous generation (`path.1`) once an append-only log reaches max_bytes. Best effort: a log
+    locked by another process is rotated on a later append, and the append itself still happens."""
+    try:
+        if os.path.getsize(path) >= max_bytes:
+            os.replace(path, path + ".1")
+    except OSError:
+        pass
+
+
+def atomic_replace(tmp_path, final_path):
+    """`os.replace` com retry curto: no Windows, `MoveFileEx` falha com `PermissionError`
+    enquanto outro processo mantém o destino aberto — e estes arquivos têm vários leitores
+    concorrentes (hook do router, tray, configure.py). A janela é de
+    milissegundos, então insistir resolve; a exceção só sobe na última tentativa."""
+    for attempt in range(_REPLACE_ATTEMPTS):
+        try:
+            os.replace(tmp_path, final_path)
+            return
+        except PermissionError:
+            if attempt == _REPLACE_ATTEMPTS - 1:
+                raise
+            time.sleep(_REPLACE_BACKOFF_S)
+
+
+def tmp_path_for(final_path):
+    """Sufixo único por chamada (não por pid): duas threads/processos podem gravar o mesmo
+    arquivo quase ao mesmo tempo."""
+    return final_path + TMP_SUFFIX + uuid.uuid4().hex
+
+
+def sweep_orphans(final_path, max_age_s=ORPHAN_AGE_S):
+    """Remove tmp de gravação interrompida (kill -9, queda de energia) do mesmo arquivo.
+    Esses tmp carregam o mesmo conteúdo do destino — credencial, no caso — com nome
+    aleatório e ninguém mais os apagaria. Best-effort: nunca impede a gravação em curso."""
+    limite = time.time() - max_age_s
+    for candidate in glob.glob(glob.escape(final_path) + TMP_SUFFIX + "*"):
+        try:
+            if os.path.getmtime(candidate) < limite:
+                os.remove(candidate)
+        except OSError:
+            pass
+
+
+def _write_and_replace(final_path, data, encoding=None):
+    sweep_orphans(final_path)
+    tmp_path = tmp_path_for(final_path)
+    try:
+        # `O_EXCL` garante tmp novo (nunca aproveita um abandonado, que pode ser de outro
+        # conteúdo); `0o600` é o pedido de permissão restrita onde o SO honra (no Windows
+        # só liga o atributo read-only — lá a confidencialidade vem da ACL do diretório).
+        flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_BINARY", 0)
+        fd = os.open(tmp_path, flags, 0o600)
+        mode = "wb" if encoding is None else "w"
+        extra = {} if encoding is None else {"encoding": encoding, "newline": ""}
+        with os.fdopen(fd, mode, **extra) as f:
+            f.write(data)
+            # `os.replace` só garante que o nome aparece inteiro; sem o flush+fsync uma
+            # queda de energia pode persistir o rename sem os dados e deixar o destino —
+            # que era o único lugar com o conteúdo anterior — vazio ou com lixo.
+            f.flush()
+            os.fsync(f.fileno())
+        atomic_replace(tmp_path, final_path)
+    except Exception:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def write_secret_bytes(final_path, data):
+    """Grava bytes em `final_path` com o tmp restrito, `fsync` dos dados antes do rename
+    (a durabilidade da entrada de diretório fica com o SO) e replace atômico."""
+    _write_and_replace(final_path, data)
+
+
+def write_secret_text(final_path, text, encoding="utf-8"):
+    """Mesmo contrato de `write_secret_bytes`, para conteúdo textual (JSON de token)."""
+    _write_and_replace(final_path, text, encoding=encoding)

package/autostart.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Autostart do Smart Tool no logon do Windows — Tarefa Agendada por usuário (sem
+admin), com política `RestartOnFailure` cobrindo o SO reiniciar o processo se ele
+morrer. `schtasks /Create` pode ser bloqueado por política de grupo corporativa
+(máquina AD-joined); nesse caso cai automaticamente para um atalho na pasta Startup
+do usuário — sem a política de restart do Task Scheduler, mas o loop de polling do
+próprio `tray.py` já cobre "se cair, sobe de novo" independente do mecanismo de boot.
+"""
+import os
+import subprocess
+import sys
+import tempfile
+
+TASK_NAME = os.environ.get("SMART_TOOL_TASK_NAME", "SmartTool-Tray")
+
+
+class AutostartError(Exception):
+    """Mensagem já pronta pra exibir ao usuário — sem stack trace nem caminho interno."""
+
+
+def _xml_escape(text):
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def _tool_dir():
+    return os.path.dirname(os.path.abspath(__file__))
+
+
+def _tray_path():
+    return os.path.join(_tool_dir(), "tray.py")
+
+
+def _pythonw_path():
+    exe = sys.executable
+    base, name = os.path.split(exe)
+    if name.lower() == "python.exe":
+        candidate = os.path.join(base, "pythonw.exe")
+        if os.path.isfile(candidate):
+            return candidate
+    return exe
+
+
+def _current_user_id():
+    domain = os.environ.get("USERDOMAIN", "")
+    user = os.environ.get("USERNAME", "")
+    return f"{domain}\\{user}" if domain else user
+
+
+def _task_xml():
+    user_id = _xml_escape(_current_user_id())
+    pythonw = _xml_escape(_pythonw_path())
+    tray = _xml_escape(_tray_path())
+    workdir = _xml_escape(_tool_dir())
+    return (
+        '<?xml version="1.0" encoding="UTF-16"?>\r\n'
+        '<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">\r\n'
+        '  <RegistrationInfo>\r\n'
+        '    <Description>Smart Tool - MCP daemon + tray icon, starts at user sign-in.</Description>\r\n'
+        '  </RegistrationInfo>\r\n'
+        '  <Triggers>\r\n'
+        '    <LogonTrigger>\r\n'
+        '      <Enabled>true</Enabled>\r\n'
+        f'      <UserId>{user_id}</UserId>\r\n'
+        '    </LogonTrigger>\r\n'
+        '  </Triggers>\r\n'
+        '  <Principals>\r\n'
+        '    <Principal id="Author">\r\n'
+        f'      <UserId>{user_id}</UserId>\r\n'
+        '      <LogonType>InteractiveToken</LogonType>\r\n'
+        '      <RunLevel>LeastPrivilege</RunLevel>\r\n'
+        '    </Principal>\r\n'
+        '  </Principals>\r\n'
+        '  <Settings>\r\n'
+        '    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>\r\n'
+        '    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>\r\n'
+        '    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>\r\n'
+        '    <AllowHardTerminate>true</AllowHardTerminate>\r\n'
+        '    <StartWhenAvailable>true</StartWhenAvailable>\r\n'
+        '    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>\r\n'
+        '    <Enabled>true</Enabled>\r\n'
+        '    <Hidden>false</Hidden>\r\n'
+        '    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>\r\n'
+        '    <RestartOnFailure>\r\n'
+        '      <Interval>PT1M</Interval>\r\n'
+        '      <Count>999</Count>\r\n'
+        '    </RestartOnFailure>\r\n'
+        '  </Settings>\r\n'
+        '  <Actions Context="Author">\r\n'
+        '    <Exec>\r\n'
+        f'      <Command>{pythonw}</Command>\r\n'
+        f'      <Arguments>"{tray}"</Arguments>\r\n'
+        f'      <WorkingDirectory>{workdir}</WorkingDirectory>\r\n'
+        '    </Exec>\r\n'
+        '  </Actions>\r\n'
+        '</Task>\r\n'
+    )
+
+
+def _startup_dir():
+    appdata = os.environ.get("APPDATA", "")
+    if not appdata:
+        raise AutostartError("APPDATA environment variable not set; could not find the user Startup folder.")
+    return os.path.join(appdata, "Microsoft", "Windows", "Start Menu", "Programs", "Startup")
+
+
+def _startup_script_path():
+    return os.path.join(_startup_dir(), "SmartTool-Tray.vbs")
+
+
+def _vbs_quoted_run(pythonw, tray):
+    # WshShell.Run monta a linha de comando com Chr(34) em vez de aspas literais —
+    # evita ter que escapar aspas dentro de aspas tanto em Python quanto em VBScript.
+    return f'Chr(34) & "{pythonw}" & Chr(34) & " " & Chr(34) & "{tray}" & Chr(34)'
+
+
+def _install_startup_shortcut():
+    os.makedirs(_startup_dir(), exist_ok=True)
+    vbs = (
+        'Set shell = CreateObject("WScript.Shell")\r\n'
+        f'shell.Run {_vbs_quoted_run(_pythonw_path(), _tray_path())}, 0, False\r\n'
+    )
+    with open(_startup_script_path(), "w", encoding="utf-8") as f:
+        f.write(vbs)
+    return {"ok": True, "method": "startup_folder"}
+
+
+def _remove_startup_shortcut():
+    try:
+        os.remove(_startup_script_path())
+        return True
+    except OSError:
+        return False
+
+
+def _task_installed():
+    try:
+        result = subprocess.run(
+            ["schtasks", "/Query", "/TN", TASK_NAME],
+            capture_output=True, text=True, timeout=20,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return result.returncode == 0
+
+
+def install():
+    """Tenta a Tarefa Agendada primeiro (cobre restart automático pelo SO); se
+    `schtasks /Create` falhar por qualquer motivo (ex.: bloqueado por politica de
+    grupo corporativa, `schtasks` fora do PATH, timeout), cai para o atalho de
+    Startup em vez de propagar o erro."""
+    fallback_reason = None
+    try:
+        xml = _task_xml()
+        fd, tmp_path = tempfile.mkstemp(suffix=".xml")
+        try:
+            with os.fdopen(fd, "wb") as f:
+                f.write(xml.encode("utf-16"))
+            result = subprocess.run(
+                ["schtasks", "/Create", "/TN", TASK_NAME, "/XML", tmp_path, "/F"],
+                capture_output=True, text=True, timeout=20,
+            )
+        finally:
+            try:
+                os.remove(tmp_path)
+            except OSError:
+                pass
+        if result.returncode == 0:
+            return {"ok": True, "method": "task"}
+        fallback_reason = (result.stderr or result.stdout or "").strip()
+    except (OSError, subprocess.SubprocessError) as exc:
+        fallback_reason = str(exc)
+
+    fallback = _install_startup_shortcut()
+    fallback["fallback_reason"] = fallback_reason
+    return fallback
+
+
+def remove():
+    removed = []
+    try:
+        result = subprocess.run(
+            ["schtasks", "/Delete", "/TN", TASK_NAME, "/F"],
+            capture_output=True, text=True, timeout=20,
+        )
+        if result.returncode == 0:
+            removed.append("task")
+    except (OSError, subprocess.SubprocessError):
+        pass
+    if _remove_startup_shortcut():
+        removed.append("startup_folder")
+    return {"ok": True, "removed": removed}
+
+
+def status():
+    if _task_installed():
+        return {"installed": True, "method": "task"}
+    if os.path.isfile(_startup_script_path()):
+        return {"installed": True, "method": "startup_folder"}
+    return {"installed": False, "method": None}