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

package/config.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""Configuração de modelos do Smart Tool, compartilhada por todos os hosts MCP.
+
+Chaves de API ficam em `api_keys` sempre cifradas com DPAPI; texto em claro é recusado na gravação.
+"""
+import json
+import os
+import paths
+import threading
+
+import atomic_io
+import secret_store
+
+# Alias de compatibilidade: a implementação mora em `atomic_io`.
+atomic_replace = atomic_io.atomic_replace
+
+CONFIG_DIR = paths.HOME_DIR
+CONFIG_PATH = os.path.join(CONFIG_DIR, "config.json")
+
+# RLock: update_config() chama load/save sob o mesmo lock; Lock travaria a própria thread.
+_LOCK = threading.RLock()
+
+DEFAULT_CONFIG = {
+    "router_model": "",
+    "scope_model": "",
+    "embedding_model": "",
+    "rerank_model": "",
+    "research_model": "",
+    "research_max_iterations": 3,
+    "quick_search_timeout_s": 120,
+    "site_memory_similarity_threshold": 0.35,
+    "local_models": "fallback",
+    "hook_mode": "redirect",
+    "contact": "",
+    "model_adapter": "",
+    "model_adapter_options": {},
+}
+
+# Local models from the mcp-memory sidecar: fallback = only when the gateway has no model; off = never;
+# prefer = even when the gateway has one (embedding quality measured equal on the rerank gold set).
+LOCAL_MODEL_MODES = ("fallback", "off", "prefer")
+# PreToolUse hook: redirect = deny the native tool and point to Smart Tool; advise = let it run and add the tip to the
+# agent's context; off = no routing at all.
+HOOK_MODES = ("redirect", "advise", "off")
+
+
+def hook_mode(cfg=None):
+    value = (cfg if cfg is not None else load_config()).get("hook_mode") or DEFAULT_CONFIG["hook_mode"]
+    if value not in HOOK_MODES:
+        raise ValueError(f"Invalid hook_mode ({value!r}) in {CONFIG_PATH}: use redirect, advise or off.")
+    return value
+
+
+def local_models_mode(cfg=None):
+    value = (cfg if cfg is not None else load_config()).get("local_models") or DEFAULT_CONFIG["local_models"]
+    if value not in LOCAL_MODEL_MODES:
+        raise ValueError(f"Invalid local_models ({value!r}) in {CONFIG_PATH}: use fallback, off or prefer.")
+    return value
+
+
+# Único lugar com os limites/recomendados de research_max_iterations e
+# site_memory_similarity_threshold — configure.py, setup_ui.py e smart_tool_daemon.py leem
+# daqui em vez de cada um definir seu próprio intervalo (mesmo padrão de fonte única de
+# web_search_adapters.py pros tiers de busca).
+RESEARCH_MAX_ITERATIONS_RANGE = (1, 10)
+QUICK_SEARCH_TIMEOUT_RANGE = (30, 360)
+SITE_MEMORY_SIMILARITY_THRESHOLD_RANGE = (0.0, 1.0)
+WEB_PROVIDER_NAMES = ("exa", "parallel", "keenable", "tavily", "firecrawl")
+
+
+def _within(value, cast, bounds, key):
+    lo, hi = bounds
+    try:
+        n = cast(value)
+    except (TypeError, ValueError):
+        return DEFAULT_CONFIG[key]
+    return n if lo <= n <= hi else DEFAULT_CONFIG[key]
+
+
+def clamp_research_max_iterations(value):
+    return _within(value, int, RESEARCH_MAX_ITERATIONS_RANGE, "research_max_iterations")
+
+
+def clamp_quick_search_timeout(value):
+    return _within(value, int, QUICK_SEARCH_TIMEOUT_RANGE, "quick_search_timeout_s")
+
+
+def clamp_site_memory_similarity_threshold(value):
+    return _within(value, float, SITE_MEMORY_SIMILARITY_THRESHOLD_RANGE, "site_memory_similarity_threshold")
+
+
+class ConfigCorruptedError(Exception):
+    """O arquivo existe mas não é JSON de objeto legível. Distinto de "não existe":
+    `load_config()` pode cair pros defaults num arquivo ausente, mas gravar sobre
+    um arquivo ilegível apagaria configurações que ainda poderiam ser recuperadas."""
+
+
+def _read_stored():
+    try:
+        with open(CONFIG_PATH, "r", encoding="utf-8") as f:
+            stored = json.load(f)
+    except FileNotFoundError:
+        return None
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise ConfigCorruptedError(
+            f"{CONFIG_PATH} is not valid JSON ({exc}); fix or delete the file manually."
+        )
+    if not isinstance(stored, dict):
+        raise ConfigCorruptedError(f"{CONFIG_PATH} does not contain a JSON object; fix or delete the file manually.")
+    return stored
+
+
+def load_config():
+    """Defaults mesclados com o que está em disco. Um arquivo corrompido devolve os
+    defaults em vez de levantar: leitura é caminho quente (todo tool call passa por
+    aqui) e não pode derrubar o daemon — quem for gravar usa `update_config`, que
+    recusa escrever nesse estado."""
+    with _LOCK:
+        try:
+            stored = _read_stored() or {}
+        except ConfigCorruptedError:
+            stored = {}
+        merged = dict(DEFAULT_CONFIG)
+        if "web_provider_keys" in stored:
+            raise ConfigCorruptedError(f"{CONFIG_PATH} uses the old 'web_provider_keys' format: delete that field and "
+                                       "enter the keys again in the setup screen.")
+        merged.update(stored)
+        return merged
+
+
+def save_config(config):
+    with _LOCK:
+        os.makedirs(CONFIG_DIR, exist_ok=True)
+        # Mantém o gravador atômico: a instalação antiga guardava segredo aqui.
+        clean = dict(config)
+        provider_keys = clean.get("api_keys") or {}
+        if (not isinstance(provider_keys, dict) or any(
+            not _known_key(name) or not secret_store.is_protected(value)
+            for name, value in provider_keys.items()
+        )):
+            raise ValueError("Keys must be protected by DPAPI.")
+        atomic_io.write_secret_text(
+            CONFIG_PATH, json.dumps(clean, indent=2, ensure_ascii=False)
+        )
+
+
+def corrupted_reason():
+    """Motivo pelo qual o arquivo em disco é ilegível, ou `None` se está legível/ausente.
+    `load_config` cai nos defaults nesse caso, então sem isto uma config truncada é
+    indistinguível de uma config vazia na hora de explicar a falha ao usuário."""
+    with _LOCK:
+        try:
+            _read_stored()
+        except ConfigCorruptedError as exc:
+            return str(exc)
+        return None
+
+
+def update_config(mutate):
+    """Load + mutate + save como uma única seção crítica, pra dois handlers HTTP
+    concorrentes nunca perderem a escrita um do outro. Levanta `ConfigCorruptedError`
+    se o arquivo em disco estiver ilegível, em vez de substituí-lo pelos defaults."""
+    with _LOCK:
+        stored = _read_stored() or {}
+        cfg = dict(DEFAULT_CONFIG)
+        cfg.update(stored)
+        # Serializado (não `dict(cfg)`): a comparação tem que enxergar mutação in-place
+        # de um valor aninhado, que uma cópia rasa esconderia. Mesmo contrato de
+        # serialização de `save_config`, pra um valor que só a comparação aceitaria não
+        # passar da guarda e estourar na gravação.
+        before = json.dumps(cfg, sort_keys=True)
+        mutate(cfg)
+        # Mutação que não muda nada não regrava.
+        if json.dumps(cfg, sort_keys=True) == before and os.path.isfile(CONFIG_PATH):
+            return cfg
+        save_config(cfg)
+        return cfg
+
+
+def _known_key(name):
+    """Web providers by name; model adapter secrets as "adapter:<adapter>:<field>" (see gateway.py)."""
+    return name in WEB_PROVIDER_NAMES or (isinstance(name, str) and name.startswith("adapter:"))
+
+
+def _provider_name(name):
+    if not _known_key(name):
+        raise ValueError(f"Unknown key: {name!r}")
+    return name
+
+
+def get_provider_api_key(name):
+    """Devolve a chave opcional em claro só no processo que fará a chamada HTTP."""
+    name = _provider_name(name)
+    stored = (load_config().get("api_keys") or {}).get(name) or ""
+    if not stored:
+        return ""
+    if not secret_store.is_protected(stored):
+        raise secret_store.SecretProtectionError("Provider key is not protected by DPAPI.")
+    return secret_store.unprotect(stored)
+
+
+def provider_key_status(name):
+    """Estado para a UI, sem revelar a chave nem o blob DPAPI."""
+    name = _provider_name(name)
+    stored = (load_config().get("api_keys") or {}).get(name) or ""
+    if not stored:
+        return "keyless"
+    try:
+        get_provider_api_key(name)
+    except secret_store.SecretProtectionError:
+        return "unreadable"
+    return "configured"
+
+
+def check_provider_key_format(key):
+    if len(key) > 4096 or any(ord(char) < 33 for char in key) or secret_store.is_protected(key):
+        raise ValueError("Paste the provider's original API key, without spaces or line breaks.")
+
+
+def set_provider_api_key(name, key):
+    """Grava/remove chave externa sob DPAPI; nunca persiste texto puro."""
+    name = _provider_name(name)
+    if key is not None and not isinstance(key, str):
+        raise ValueError("API key must be text.")
+    key = (key or "").strip()
+    if key:
+        check_provider_key_format(key)
+    protected = secret_store.protect(key) if key else ""
+
+    def mutate(cfg):
+        keys = dict(cfg.get("api_keys") or {})
+        if protected:
+            keys[name] = protected
+        else:
+            keys.pop(name, None)
+        if keys:
+            cfg["api_keys"] = keys
+        else:
+            cfg.pop("api_keys", None)
+
+    update_config(mutate)

package/daemon_launcher.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Lifecycle do daemon HTTP do Smart Tool: self-start com lock. Ao contrário do Brain
+Server (client-pure, nunca spawna, depende de instalador externo — o daemon que está
+caído neste ambiente por isso mesmo), este cliente sobe o processo sozinho se estiver
+fora do ar, protegido por lockfile contra corrida entre sessões simultâneas.
+
+Contrato de registry (mesmo formato usado pelo probe de grafo em `capabilities.py`):
+`~/.smart-tool/data/daemon.json` = `{"url": "http://127.0.0.1:<porta>"}` —
+`url` é a base do daemon; o endpoint MCP em si é `<url>/mcp`.
+"""
+import json
+import os
+import paths
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+RUN_DIR = paths.DATA_DIR
+REGISTRY_PATH = os.path.join(RUN_DIR, "daemon.json")
+LOCK_PATH = os.path.join(RUN_DIR, "daemon.lock")
+LOCK_STALE_SECONDS = 30
+DEFAULT_PORT = int(os.environ.get("SMART_TOOL_PORT", "8765"))
+DAEMON_SCRIPT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "smart_tool_daemon.py")
+
+
+def read_registry():
+    try:
+        with open(REGISTRY_PATH, "r", encoding="utf-8") as f:
+            info = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+    if isinstance(info, dict) and info.get("url"):
+        return info
+    return None
+
+
+def health(url, timeout=1):
+    """Timeout curto porque só se fala com o loopback: um daemon vivo responde `/health`
+    em milissegundos (o servidor é multi-thread, indexação em curso não bloqueia), e o
+    caso lento é justamente o daemon morto cuja URL ainda está no registry — tempo que
+    toda tool call do agente paga antes de seguir."""
+    try:
+        with urllib.request.urlopen(url.rstrip("/") + "/health", timeout=timeout) as resp:
+            return resp.status == 200
+    except (urllib.error.URLError, OSError, ValueError):
+        return False
+
+
+def _acquire_lock():
+    os.makedirs(RUN_DIR, exist_ok=True)
+    try:
+        if time.time() - os.path.getmtime(LOCK_PATH) > LOCK_STALE_SECONDS:
+            os.remove(LOCK_PATH)
+    except OSError:
+        pass
+    try:
+        fd = os.open(LOCK_PATH, os.O_CREAT | os.O_EXCL | os.O_RDWR)
+        os.close(fd)
+        return True
+    except FileExistsError:
+        return False
+
+
+def _release_lock():
+    try:
+        os.remove(LOCK_PATH)
+    except OSError:
+        pass
+
+
+def _spawn_daemon():
+    executable = Path(sys.executable)
+    if sys.platform == "win32":
+        # O venv pythonw.exe pode morrer sem iniciar o daemon. O python.exe iniciado
+        # direto abre uma aba no Windows Terminal; fechá-la mata o serviço e o tray
+        # tenta subir outra a cada polling. WScript cria um processo independente com
+        # a janela oculta, como no Passtrough.
+        if executable.name.lower() == "pythonw.exe":
+            executable = executable.with_name("python.exe")
+        fd, launcher = tempfile.mkstemp(prefix="smart-tool-hidden-", suffix=".vbs")
+        try:
+            command = (f'Chr(34) & "{executable}" & Chr(34) & " " & '
+                       f'Chr(34) & "{DAEMON_SCRIPT}" & Chr(34)')
+            with os.fdopen(fd, "w", encoding="utf-16") as stream:
+                stream.write('Set sh = CreateObject("WScript.Shell")\n')
+                stream.write(f'sh.CurrentDirectory = "{Path(DAEMON_SCRIPT).parent}"\n')
+                stream.write(f'sh.Run {command}, 0, False\n')
+            result = subprocess.run(
+                ["wscript.exe", "//B", "//NoLogo", launcher],
+                stdin=subprocess.DEVNULL, capture_output=True, timeout=10,
+                creationflags=subprocess.CREATE_NO_WINDOW,
+            )
+            if result.returncode:
+                raise RuntimeError("Windows could not start the Smart Tool daemon without a window.")
+        finally:
+            Path(launcher).unlink(missing_ok=True)
+        return
+    subprocess.Popen(
+        [str(executable), DAEMON_SCRIPT],
+        stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL, close_fds=True, start_new_session=True,
+    )
+
+
+def ensure_daemon_running(wait_seconds=10):
+    """Retorna a URL base do daemon (sem `/mcp`), subindo o processo se necessário."""
+    info = read_registry()
+    if info and health(info["url"]):
+        return info["url"]
+
+    if not _acquire_lock():
+        url = _wait_for_daemon(wait_seconds)
+        if url:
+            return url
+        raise RuntimeError("Timed out waiting for another session to start the Smart Tool daemon")
+
+    try:
+        _spawn_daemon()
+        url = _wait_for_daemon(wait_seconds)
+        if url:
+            return url
+        raise RuntimeError("Timed out starting the Smart Tool daemon")
+    finally:
+        _release_lock()
+
+
+def daemon_url_if_up():
+    info = read_registry()
+    if info and health(info["url"], timeout=0.5):
+        return info["url"]
+    return None
+
+
+def start_daemon_if_down():
+    """`True` se o daemon já responde; `False` se acabou de disparar o start, sem esperar.
+
+    Para quem está num caminho sensível a latência (o hook PreToolUse roda antes de toda
+    Grep/Glob/Read/Bash): esperar o processo subir pode custar segundos — spawn de
+    processo em máquina com EDR varia muito — e quem chama tem um desfecho válido sem o
+    daemon. A garantia de daemon único não depende do lock ser mantido aqui: um segundo
+    processo falha no bind exclusivo da porta e morre sozinho."""
+    if daemon_url_if_up():
+        return True
+    if _acquire_lock():
+        # O lock NÃO é liberado aqui: ele é o freio de taxa. Expirando por idade
+        # (`LOCK_STALE_SECONDS`), um daemon que não consegue subir — porta tomada, import
+        # quebrado — resulta em uma tentativa a cada 30s, e não num processo órfão por
+        # tool call. Quem perde a corrida do bind morre sozinho (`allow_reuse_address`
+        # False), então soltar o lock não acrescentaria segurança nenhuma.
+        _spawn_daemon()
+    return False
+
+
+def _wait_for_daemon(wait_seconds, poll_interval=0.1):
+    deadline = time.time() + wait_seconds
+    while time.time() < deadline:
+        info = read_registry()
+        if info and health(info["url"], timeout=0.5):
+            return info["url"]
+        time.sleep(poll_interval)
+    return None

package/directory_watch.py

@@ -0,0 +1,131 @@
+"""ReadDirectoryChangesW assíncrono: eventos nativos com parada cooperativa."""
+import os
+import struct
+import threading
+
+
+class DirectoryWatcher:
+    def __init__(self, root, on_events, on_error):
+        self.root = root
+        self.on_events = on_events
+        self.on_error = on_error
+        self._stop = threading.Event()
+        self._thread = None
+        self.ready = threading.Event()
+
+    def start(self):
+        if self._thread and self._thread.is_alive():
+            return
+        self._thread = threading.Thread(target=self._run, name="directory-events", daemon=True)
+        self._thread.start()
+
+    @property
+    def alive(self):
+        return bool(self._thread and self._thread.is_alive())
+
+    def stop(self):
+        self._stop.set()
+        if self._thread and self._thread is not threading.current_thread():
+            self._thread.join(timeout=3)
+
+    @staticmethod
+    def decode(buffer, length):
+        rows, offset = [], 0
+        while offset < length:
+            if offset + 12 > length:
+                raise ValueError("Incomplete directory event.")
+            next_offset, action, size = struct.unpack_from("<III", buffer, offset)
+            if size % 2 or offset + 12 + size > length:
+                raise ValueError("Invalid file name in event.")
+            name = buffer[offset + 12:offset + 12 + size].decode("utf-16-le")
+            rows.append({"path": name.replace("\\", "/"), "action": action})
+            if not next_offset:
+                break
+            if next_offset < 12 or offset + next_offset >= length:
+                raise ValueError("Invalid event offset.")
+            offset += next_offset
+        return rows
+
+    def _run(self):
+        if os.name != "nt":
+            self.on_error("Native events unavailable on this platform; periodic reconciliation is active.")
+            return
+        import ctypes
+        from ctypes import wintypes
+
+        class Overlapped(ctypes.Structure):
+            _fields_ = [("Internal", ctypes.c_size_t), ("InternalHigh", ctypes.c_size_t),
+                        ("Offset", wintypes.DWORD), ("OffsetHigh", wintypes.DWORD),
+                        ("hEvent", wintypes.HANDLE)]
+
+        kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+        kernel.CreateFileW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD,
+                                      ctypes.c_void_p, wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE]
+        kernel.CreateFileW.restype = wintypes.HANDLE
+        kernel.CreateEventW.argtypes = [ctypes.c_void_p, wintypes.BOOL, wintypes.BOOL, wintypes.LPCWSTR]
+        kernel.CreateEventW.restype = wintypes.HANDLE
+        kernel.ReadDirectoryChangesW.argtypes = [wintypes.HANDLE, ctypes.c_void_p, wintypes.DWORD,
+            wintypes.BOOL, wintypes.DWORD, ctypes.POINTER(wintypes.DWORD), ctypes.POINTER(Overlapped), ctypes.c_void_p]
+        kernel.ReadDirectoryChangesW.restype = wintypes.BOOL
+        kernel.GetOverlappedResult.argtypes = [wintypes.HANDLE, ctypes.POINTER(Overlapped),
+                                              ctypes.POINTER(wintypes.DWORD), wintypes.BOOL]
+        kernel.GetOverlappedResult.restype = wintypes.BOOL
+        kernel.CancelIoEx.argtypes = [wintypes.HANDLE, ctypes.c_void_p]
+        kernel.CancelIoEx.restype = wintypes.BOOL
+        kernel.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]
+        kernel.WaitForSingleObject.restype = wintypes.DWORD
+        kernel.ResetEvent.argtypes = [wintypes.HANDLE]
+        kernel.CloseHandle.argtypes = [wintypes.HANDLE]
+        handle, event, operation = None, None, None
+        pending = False
+        try:
+            handle = kernel.CreateFileW(self.root, 0x0001, 0x0007, None, 3,
+                                        0x02000000 | 0x40000000, None)
+            if handle == ctypes.c_void_p(-1).value:
+                handle = None
+                raise OSError(ctypes.get_last_error(), "Could not watch the folder.")
+            event = kernel.CreateEventW(None, True, False, None)
+            if not event:
+                raise OSError(ctypes.get_last_error(), "Could not create the watch event.")
+            buffer = ctypes.create_string_buffer(64 * 1024)
+            count = wintypes.DWORD()
+            while not self._stop.is_set():
+                kernel.ResetEvent(event)
+                operation = Overlapped()
+                operation.hEvent = event
+                ok = kernel.ReadDirectoryChangesW(handle, buffer, len(buffer), True,
+                                                   0x0001 | 0x0002 | 0x0008 | 0x0010 | 0x0040,
+                                                   None, ctypes.byref(operation), None)
+                if not ok and ctypes.get_last_error() != 997:
+                    raise OSError(ctypes.get_last_error(), "Failed to receive folder changes.")
+                pending = True
+                self.ready.set()
+                while not self._stop.is_set():
+                    status = kernel.WaitForSingleObject(event, 250)
+                    if status == 0:
+                        break
+                    if status != 258:
+                        raise OSError(ctypes.get_last_error(), "Failed while waiting for folder events.")
+                if self._stop.is_set():
+                    break
+                ok = kernel.GetOverlappedResult(handle, ctypes.byref(operation), ctypes.byref(count), False)
+                pending = False
+                if not ok:
+                    raise OSError(ctypes.get_last_error(), "Folder event interrupted.")
+                try:
+                    rows = self.decode(buffer.raw, count.value) if count.value else []
+                except (ValueError, UnicodeError):
+                    rows = []
+                self.on_events(rows, not bool(rows))
+        except Exception as exc:
+            if not self._stop.is_set():
+                self.on_error(f"{type(exc).__name__}: {exc}")
+        finally:
+            if handle and pending and operation is not None:
+                kernel.CancelIoEx(handle, ctypes.byref(operation))
+                count = wintypes.DWORD()
+                kernel.GetOverlappedResult(handle, ctypes.byref(operation), ctypes.byref(count), True)
+            if handle:
+                kernel.CloseHandle(handle)
+            if event:
+                kernel.CloseHandle(event)

package/document_text.py

@@ -0,0 +1,69 @@
+"""Extração local de texto DOCX, sem Office, execução de macros ou acesso externo."""
+import io
+import re
+import zipfile
+import xml.etree.ElementTree as ET
+
+VERSION = 1
+MAX_ARCHIVE_BYTES = 10 * 1024 * 1024
+MAX_XML_BYTES = 8 * 1024 * 1024
+MAX_TEXT_BYTES = 1024 * 1024
+W = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+
+
+class DocumentError(ValueError):
+    pass
+
+
+class _DocumentTreeBuilder(ET.TreeBuilder):
+    def doctype(self, name, pubid, system):
+        # O callback também recusa DTD em XML UTF-16, antes de expandir entidades.
+        raise DocumentError('DOCX contains disallowed entities.')
+
+
+def extract_docx(data):
+    if len(data)>MAX_ARCHIVE_BYTES:
+        raise DocumentError('DOCX over the 10 MiB limit.')
+    try:
+        with zipfile.ZipFile(io.BytesIO(data)) as archive:
+            listing=archive.infolist()
+            entries={info.filename:info for info in listing}
+            if len(listing)>2000 or 'word/document.xml' not in entries:
+                raise DocumentError('Invalid DOCX or excessive structure.')
+            names=['word/document.xml']+sorted(name for name in entries if re.fullmatch(r'word/(?:header\d+|footer\d+|footnotes|endnotes)\.xml',name))
+            paragraphs=[];xml_bytes=0;text_bytes=0
+            for name in names:
+                info=entries[name]
+                if info.flag_bits&1 or info.compress_type not in (zipfile.ZIP_STORED,zipfile.ZIP_DEFLATED):
+                    raise DocumentError('Encrypted DOCX or unsupported compression.')
+                if info.file_size>MAX_XML_BYTES-xml_bytes:
+                    raise DocumentError('DOCX XML content over the limit.')
+                with archive.open(info) as stream:
+                    raw=stream.read(MAX_XML_BYTES-xml_bytes+1)
+                xml_bytes+=len(raw)
+                if xml_bytes>MAX_XML_BYTES or b'<!DOCTYPE' in raw.upper() or b'<!ENTITY' in raw.upper():
+                    raise DocumentError('DOCX contains excessive XML or disallowed entities.')
+                root=ET.fromstring(raw,parser=ET.XMLParser(target=_DocumentTreeBuilder()))
+                namespace=W if root.tag.startswith(W) else '{http://purl.oclc.org/ooxml/wordprocessingml/main}'
+                for paragraph in root.iter(namespace+'p'):
+                    def parts(node):
+                        pending=list(reversed(node))
+                        while pending:
+                            child=pending.pop()
+                            if child.tag==namespace+'p':continue
+                            if child.tag==namespace+'t':yield child.text or ''
+                            elif child.tag==namespace+'tab':yield '\t'
+                            elif child.tag in (namespace+'br',namespace+'cr'):yield '\n'
+                            else:pending.extend(reversed(child))
+                    text=''.join(parts(paragraph))
+                    if text.strip():
+                        text_bytes+=len(text.encode('utf-8'))+1
+                        if text_bytes>MAX_TEXT_BYTES:raise DocumentError('Text extracted from DOCX exceeds 1 MiB.')
+                        paragraphs.append(text)
+            return ('\n'.join(paragraphs)+'\n' if paragraphs else '').encode('utf-8')
+    except (zipfile.BadZipFile,ET.ParseError,RuntimeError,NotImplementedError,OSError) as exc:
+        raise DocumentError('Could not extract text from this DOCX.') from exc
+
+
+def location_kind(path):
+    return 'extracted_text_line' if str(path).lower().endswith('.docx') else 'source_line'