@andespindola/crow-skills 0.12.2 → 0.13.0

package/skills/crow-behaviour/scripts/lc_proxy.py

@@ -0,0 +1,627 @@
+#!/usr/bin/env python3
+"""lean-context proxy: detecta, configura com segurança e verifica os proxies de compressão de API
+(caveman-proxy e rtk-proxy), apontando o agente para eles só por processo, sem editar arquivos globais.
+
+Subcomandos:
+  detect [--json]                          o que está instalado, rodando e para onde o agente aponta
+  check  caveman|rtk                       verifica identidade e postura da instância em execução
+  start  caveman|rtk [--mode record|compress] [--accept-user-text-compression] [--dry-run]
+                                           sobe o proxy com a configuração segura (daemon, loopback)
+  stop   caveman|rtk [--purge]             para só a instância que este script subiu (identidade conferida)
+  launch caveman|rtk -- claude [args]      roda o agente apontado para o proxy (só neste processo)
+  env    caveman|rtk                       imprime os exports, sem expor o token
+
+Regras:
+- só IP literal de loopback (127.0.0.0/8, ::1) ou "localhost"; nomes DNS são recusados;
+- a identidade da instância é provada antes de qualquer token sair: manifesto deste script, mesmo endereço,
+  pid vivo com o mesmo executável e horário de início, dono da porta (lsof) e, no caveman, o header
+  X-Caveman-Instance igual ao run-state privado; launch exige identidade provada e zero falhas;
+- caveman: token obrigatório também em loopback; modo record por padrão; compress só com
+  --accept-user-text-compression (CAV-01 não tem configuração que o feche); warm cache, nuvem,
+  telemetria e captura desligados; upstream conferido no run-state;
+- rtk: sem empréstimo de credencial, upstream oficial e bind conferidos em execução;
+- ambiente do proxy por lista de permissão (nada de CAVE_UPSTREAM_PROXY, CAVEMAN_CONFIG, ALL_PROXY...);
+- estado isolado num diretório 0700; token em arquivo 0600; nunca imprime o token;
+- nunca edita ~/.claude/settings.json nem instala binários. Só stdlib, macOS e Linux.
+"""
+from __future__ import annotations
+
+import argparse
+import http.client as httpclient
+import ipaddress
+import json
+import os
+import re
+import secrets
+import shlex
+import shutil
+import signal
+import stat
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+TAG = "[lean-context proxy]"
+OFFICIAL_ANTHROPIC = "https://api.anthropic.com"
+
+PROXIES = {
+    "caveman": {"binary": "caveman-proxy", "default": "127.0.0.1:8787", "listen_env": "CAVEMAN_LISTEN",
+                "health": "/health/live", "service": "caveman-proxy"},
+    "rtk": {"binary": "rtk-proxy", "default": "127.0.0.1:8080", "listen_env": "RTK_PROXY_BIND",
+            "health": "/health", "service": "rtk-proxy"},
+}
+# ambiente que o proxy herda (lista de permissão); o resto é descartado
+ENV_ALLOW = {"PATH", "HOME", "USER", "LOGNAME", "LANG", "TMPDIR", "TZ", "TERM",
+             "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY",
+             "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN", "AWS_REGION", "AWS_DEFAULT_REGION",
+             "AWS_BEARER_TOKEN_BEDROCK"}
+
+
+# ---------------------------------------------------------------- endereços
+def split_hostport(hp: str):
+    m = re.fullmatch(r"\[([0-9a-fA-F:]+)\]:(\d{1,5})|([^:\[\]]+):(\d{1,5})", hp.strip())
+    if not m:
+        return None, None
+    host = m.group(1) or m.group(3)
+    port = int(m.group(2) or m.group(4))
+    return (host, port) if 0 < port < 65536 else (None, None)
+
+
+def loopback_ip(hp: str) -> str | None:
+    """IP literal de loopback para o endereço, ou None. 'localhost' vira 127.0.0.1; nomes DNS são recusados."""
+    host, port = split_hostport(hp)
+    if host is None:
+        return None
+    if host == "localhost":
+        return "127.0.0.1"
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        return None
+    return str(ip) if ip.is_loopback else None
+
+
+def is_loopback(hp: str) -> bool:
+    return loopback_ip(hp) is not None
+
+
+def url_for(hp: str, path: str) -> str:
+    ip = loopback_ip(hp)
+    if ip is None:
+        raise SystemExit(f"{TAG} recusado: {hp!r} não é IP de loopback; só consulto 127.0.0.0/8, ::1 ou localhost")
+    port = split_hostport(hp)[1]
+    host = f"[{ip}]" if ":" in ip else ip
+    return f"http://{host}:{port}{path}"
+
+
+def addr(name: str) -> str:
+    return os.environ.get(PROXIES[name]["listen_env"]) or PROXIES[name]["default"]
+
+
+def call(method: str, hp: str, path: str, headers: dict | None = None, body: bytes | None = None, timeout=2.0):
+    req = urllib.request.Request(url_for(hp, path), data=body, method=method, headers=headers or {})
+    opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))  # ignora HTTP(S)_PROXY/ALL_PROXY
+    try:
+        with opener.open(req, timeout=timeout) as r:
+            return r.status, {k.lower(): v for k, v in r.headers.items()}, r.read(65536)
+    except urllib.error.HTTPError as e:
+        try:
+            raw = e.read(65536)
+        except Exception:
+            raw = b""
+        return e.code, {k.lower(): v for k, v in (e.headers or {}).items()}, raw
+    except (urllib.error.URLError, OSError, TimeoutError, httpclient.HTTPException, ValueError):
+        return None, {}, b""
+
+
+# ---------------------------------------------------------------- estado privado
+def state_dir() -> Path:
+    base = os.environ.get("LEAN_CONTEXT_DIR")
+    if not base:
+        base = os.path.join(os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache"), "lean-context")
+    p = Path(base) / "proxy"
+    p.mkdir(parents=True, exist_ok=True, mode=0o700)
+    for d in (p.parent, p):
+        st = os.lstat(d)
+        if stat.S_ISLNK(st.st_mode) or st.st_uid != os.getuid():
+            raise SystemExit(f"{TAG} recusado: {d} não é um diretório privado deste usuário")
+        if stat.S_IMODE(st.st_mode) & 0o077:
+            os.chmod(d, 0o700)
+    return p
+
+
+def write_private(path: Path, data: str) -> None:
+    tmp = path.with_name(path.name + f".tmp{os.getpid()}")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    with os.fdopen(fd, "w") as f:
+        f.write(data)
+    os.replace(tmp, path)
+
+
+def read_private_json(path: Path) -> dict | None:
+    try:
+        st = os.lstat(path)
+        if stat.S_ISLNK(st.st_mode) or st.st_uid != os.getuid() or stat.S_IMODE(st.st_mode) & 0o077:
+            return None
+        d = json.loads(path.read_text())
+        return d if isinstance(d, dict) else None
+    except (OSError, ValueError):
+        return None
+
+
+def token_path() -> Path:
+    return state_dir() / "caveman-token"
+
+
+def get_token(create: bool) -> str | None:
+    p = token_path()
+    if p.exists():
+        st = os.lstat(p)
+        if stat.S_ISLNK(st.st_mode) or stat.S_IMODE(st.st_mode) & 0o077 or st.st_uid != os.getuid():
+            raise SystemExit(f"{TAG} recusado: {p} precisa ser arquivo comum 0600 deste usuário")
+        return p.read_text().strip()
+    if not create:
+        return None
+    tok = secrets.token_hex(32)
+    write_private(p, tok + "\n")
+    return tok
+
+
+def manifest_path(name: str) -> Path:
+    return state_dir() / f"{name}.json"
+
+
+def read_manifest(name: str) -> dict | None:
+    return read_private_json(manifest_path(name))
+
+
+# ---------------------------------------------------------------- identidade de processo
+def proc_identity(pid) -> dict | None:
+    """Executável e horário de início do processo (ps), para não confundir pid reutilizado."""
+    try:
+        pid = int(pid)
+        out = subprocess.run(["ps", "-o", "lstart=", "-o", "comm=", "-p", str(pid)], capture_output=True,
+                             text=True, timeout=5).stdout.strip()
+    except (TypeError, ValueError, OSError, subprocess.SubprocessError):
+        return None
+    if not out:
+        return None
+    parts = out.split()
+    return {"start": " ".join(parts[:5]), "comm": os.path.basename(" ".join(parts[5:]))}
+
+
+def port_owners(port: int) -> set | None:
+    """PIDs escutando na porta (lsof). None quando lsof não está disponível."""
+    lsof = shutil.which("lsof")
+    if not lsof:
+        return None
+    try:
+        out = subprocess.run([lsof, "-nP", f"-iTCP:{port}", "-sTCP:LISTEN", "-t"], capture_output=True,
+                             text=True, timeout=5).stdout
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return {int(x) for x in out.split() if x.isdigit()}
+
+
+def same_process(m: dict) -> bool:
+    ident = proc_identity(m.get("pid"))
+    return bool(ident and m.get("identity") and ident == m["identity"])
+
+
+# ---------------------------------------------------------------- consultas aos proxies
+def health(name: str, hp: str | None = None):
+    hp = hp or addr(name)
+    code, hdrs, body = call("GET", hp, PROXIES[name]["health"])
+    if code != 200:
+        return None, {}
+    try:
+        data = json.loads(body)
+    except ValueError:
+        return None, {}
+    if not isinstance(data, dict) or data.get("service") != PROXIES[name]["service"]:
+        return None, {}  # outra coisa na porta: não é o proxy
+    return data, hdrs
+
+
+def caveman_runstate(m: dict | None, hp: str) -> dict:
+    """Run-state do home isolado da instância deste script (contém instance_token; nunca é impresso)."""
+    port = split_hostport(hp)[1]
+    home = (m or {}).get("caveman_home")
+    if not home:
+        return {}
+    return read_private_json(Path(home) / "run" / f"{port}.json") or {}
+
+
+# ---------------------------------------------------------------- detect
+def settings_base_url() -> str | None:
+    cfg = Path(os.environ.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude") / "settings.json"
+    try:
+        env = json.loads(cfg.read_text()).get("env") or {}
+        return env.get("ANTHROPIC_BASE_URL") if isinstance(env, dict) else None
+    except (OSError, ValueError, AttributeError):
+        return None
+
+
+def detect() -> dict:
+    out = {"agent": {"ANTHROPIC_BASE_URL (ambiente)": os.environ.get("ANTHROPIC_BASE_URL"),
+                     "ANTHROPIC_BASE_URL (~/.claude/settings.json)": settings_base_url()},
+           "proxies": {}}
+    for name, spec in PROXIES.items():
+        hp = addr(name)
+        info = {"binário": shutil.which(spec["binary"]), "endereço": hp, "rodando": False, "versão": None,
+                "iniciado por este script": bool(read_manifest(name))}
+        if not is_loopback(hp):
+            info["erro"] = "endereço configurado não é IP de loopback; não consultado"
+        else:
+            h, _ = health(name, hp)
+            info["rodando"] = bool(h)
+            info["versão"] = (h or {}).get("version")
+        out["proxies"][name] = info
+    return out
+
+
+def print_detect(d: dict) -> None:
+    for k, v in d["agent"].items():
+        print(f"{TAG} agente · {k}: {v or 'não definido'}")
+    for name, i in d["proxies"].items():
+        bits = [f"binário {'em ' + i['binário'] if i['binário'] else 'não instalado'}",
+                f"{'rodando' if i['rodando'] else 'parado'} em {i['endereço']}"]
+        if i.get("versão"):
+            bits.append(f"versão {i['versão']}")
+        if i.get("erro"):
+            bits.append(i["erro"])
+        bits.append("subido por este script" if i["iniciado por este script"] else "não subido por este script")
+        print(f"{TAG} {name}: " + " · ".join(bits))
+    for name, i in d["proxies"].items():
+        host, port = split_hostport(i["endereço"])
+        for k, v in d["agent"].items():
+            if v and port and re.match(rf"https?://(127\.[\d.]+|localhost|\[::1\]):{port}(/|$)", v.strip()):
+                print(f"{TAG} o agente já aponta para a porta do {name} via {k}")
+
+
+# ---------------------------------------------------------------- check
+class Report:
+    def __init__(self, quiet=False):
+        self.fails = 0
+        self.unknown = 0
+        self.quiet = quiet
+
+    def _p(self, s):
+        if not self.quiet:
+            print(s)
+
+    def ok(self, msg):
+        self._p(f"  PASSA   {msg}")
+
+    def fail(self, msg):
+        self.fails += 1
+        self._p(f"  FALHA   {msg}")
+
+    def unk(self, msg):
+        self.unknown += 1
+        self._p(f"  ?       {msg}")
+
+
+def verify_identity(name: str, hp: str, r: Report, hdrs: dict) -> tuple[bool, dict | None]:
+    """Prova que quem responde em hp é a instância que este script subiu. Nada de token antes disso."""
+    m = read_manifest(name)
+    if not m:
+        r.unk(f"instância não foi subida por este script: identidade e configuração não confirmadas; "
+              f"para usar com segurança, pare-a e rode `lc_proxy.py start {name}`")
+        return False, None
+    if m.get("address") != hp:
+        r.fail(f"o manifesto é de {m.get('address')}, mas a consulta é em {hp}: outra instância")
+        return False, m
+    if not same_process(m):
+        r.fail("o processo do manifesto não existe mais (ou o pid foi reutilizado): quem responde na porta é outro")
+        return False, m
+    owners = port_owners(split_hostport(hp)[1])
+    if owners is None:
+        r.unk("lsof indisponível: não deu para confirmar o dono da porta")
+    elif int(m["pid"]) not in owners:
+        r.fail(f"a porta é ouvida por outro processo ({sorted(owners)}), não pelo pid {m['pid']} do manifesto")
+        return False, m
+    if name == "caveman":
+        rs = caveman_runstate(m, hp)
+        tok, live = rs.get("instance_token"), hdrs.get("x-caveman-instance")
+        if not tok or not live:
+            r.unk("caveman sem X-Caveman-Instance/run-state para conferir (versão antiga?)")
+        elif not secrets.compare_digest(str(tok), str(live)):
+            r.fail("X-Caveman-Instance não bate com o run-state privado: outra instância responde na porta")
+            return False, m
+        else:
+            r.ok("X-Caveman-Instance confere com o run-state privado da instância")
+    r.ok(f"identidade provada: pid {m['pid']} ({m['identity']['comm']}) subido por este script, dono da porta")
+    return True, m
+
+
+def check(name: str, quiet=False) -> tuple[int, bool]:
+    hp = addr(name)
+    r = Report(quiet)
+    r._p(f"{TAG} postura de {name} em {hp}")
+    if not is_loopback(hp):
+        r.fail(f"{hp!r} não é IP de loopback (só 127.0.0.0/8, ::1 ou localhost)")
+        r._p(f"{TAG} resultado: {r.fails} falha(s), {r.unknown} ponto(s) não confirmados")
+        return 1, False
+    h, hdrs = health(name, hp)
+    if not h:
+        r.fail(f"nenhum {PROXIES[name]['service']} respondendo em {hp}")
+        r._p(f"{TAG} resultado: {r.fails} falha(s), {r.unknown} ponto(s) não confirmados")
+        return 1, False
+    r.ok(f"{PROXIES[name]['service']} respondendo em loopback (versão {h.get('version', '?')})")
+    verified, m = verify_identity(name, hp, r, hdrs)
+    body, hdr = b"{}", {"content-type": "application/json"}
+    if name == "caveman":
+        code, _, _ = call("POST", hp, "/v1/messages", hdr, body)
+        (r.ok if code == 401 else r.fail)(f"requisição sem token é recusada (HTTP {code}; esperado 401)")
+        if verified:
+            tok = get_token(create=False)
+            if tok:
+                code2, _, _ = call("POST", hp, "/v1/messages", dict(hdr, **{"x-cave-api-key": tok}), body)
+                (r.ok if code2 not in (None, 401) else r.fail)(f"requisição com o token passa (HTTP {code2})")
+            else:
+                r.fail("sem token salvo por este script; o agente não terá como se autenticar")
+            rs = caveman_runstate(m, hp)
+            mode = rs.get("mode")
+            if mode == "record":
+                r.ok("modo record (lido da instância): bytes intactos, inclusive o texto do usuário; só medição")
+            elif mode == "compress":
+                if m.get("accepted_user_text_compression"):
+                    r.unk("modo compress aceito explicitamente: o texto do usuário PODE ser comprimido (CAV-01)")
+                else:
+                    r.fail("modo compress sem aceite explícito: o texto do usuário pode ser comprimido (CAV-01)")
+            else:
+                r.unk(f"modo não identificado no run-state ({mode})")
+            up = (rs.get("provider_upstreams") or {}).get("anthropic")
+            if up is None:
+                r.unk("run-state sem provider_upstreams.anthropic para conferir o upstream")
+            else:
+                (r.ok if str(up).rstrip("/") == OFFICIAL_ANTHROPIC else r.fail)(f"upstream Anthropic é a API oficial ({up})")
+        else:
+            r.unk("token não enviado: a instância não teve a identidade provada")
+    else:
+        code, _, raw = call("GET", hp, "/admin/settings")
+        try:
+            s = json.loads(raw) if code == 200 else {}
+        except ValueError:
+            s = {}
+        s = s if isinstance(s, dict) else {}
+        up = s.get("anthropic_upstream")
+        if up is None:
+            r.fail("não consegui ler o upstream em /admin/settings")
+        else:
+            (r.ok if str(up).rstrip("/") == OFFICIAL_ANTHROPIC else r.fail)(
+                f"upstream Anthropic é a API oficial ({up}) — um upstream trocado receberia suas chaves")
+        bind = s.get("bind")
+        if bind is None:
+            r.unk("o proxy não informou o bind")
+        else:
+            (r.ok if str(bind) == hp else r.fail)(f"bind informado pelo proxy ({bind}) é o endereço consultado ({hp})")
+        if verified and (m.get("env") or {}).get("RTK_PROXY_RELAY_BORROWING") == "false":
+            r.ok("empréstimo de credencial desligado nesta instância (RTK-10)")
+        else:
+            code3, _, raw3 = call("POST", hp, "/v1/messages", hdr, body)
+            if b"invalid_request_error" in raw3:
+                r.fail("pedido sem credencial foi aceito com credencial emprestada (RTK-10)")
+            else:
+                r.unk("empréstimo de credencial não confirmado (o rtk só empresta depois do primeiro uso)")
+        if Path("/etc/rtk-proxy/rtk-proxy.toml").exists():
+            r.unk("/etc/rtk-proxy/rtk-proxy.toml existe e pode mudar a configuração; revise-o")
+        r.unk("rtk-proxy não tem autenticação de entrada: qualquer processo local pode usá-lo (sem a sua credencial)")
+    r._p(f"{TAG} resultado: {r.fails} falha(s), {r.unknown} ponto(s) não confirmados")
+    return (1 if r.fails else 0), verified
+
+
+# ---------------------------------------------------------------- start / stop
+def secure_env(name: str, mode: str) -> tuple[dict, dict]:
+    """(env do processo do proxy, parte visível para o manifesto, sem segredos)."""
+    sd = state_dir()
+    env = {k: v for k, v in os.environ.items() if k in ENV_ALLOW or k.startswith("LC_")}
+    hp = addr(name)
+    if name == "caveman":
+        home = sd / "caveman-home"
+        home.mkdir(mode=0o700, exist_ok=True)
+        visible = {"CAVEMAN_LISTEN": hp, "CAVEMAN_MODE": mode, "CAVEMAN_CACHE_WARM": "off",
+                   "CAVEMAN_OFFLINE": "1", "DO_NOT_TRACK": "1", "CAVEMAN_TELEMETRY": "0", "CAVE_NO_KEYCHAIN": "1",
+                   "CAVEMAN_SUBSCRIPTION_COMPRESS": "off", "CAVEMAN_HOME": str(home)}
+        env.update(visible)
+        tok = get_token(create=True)
+        env["CAVEMAN_AUTH_TOKEN"] = tok
+        env["CAVEMAN_METRICS_TOKEN"] = tok
+        visible = dict(visible, CAVEMAN_AUTH_TOKEN=f"<arquivo {token_path()}>", CAVEMAN_METRICS_TOKEN="<mesmo token>")
+    else:
+        visible = {"RTK_PROXY_BIND": hp, "RTK_PROXY_RELAY_BORROWING": "false",
+                   "RTK_PROXY_ANTHROPIC_UPSTREAM": OFFICIAL_ANTHROPIC, "RTK_PROXY_ICM_TTL_SECS": "86400",
+                   "RTK_PROXY_DB": str(sd / "rtk-proxy.db"), "RTK_PROXY_ICM_DB": str(sd / "rtk-proxy-memory.db")}
+        env.update(visible)
+    return env, visible
+
+
+def start(name: str, mode: str, accept: bool, dry: bool) -> int:
+    spec = PROXIES[name]
+    hp = addr(name)
+    if not is_loopback(hp):
+        print(f"{TAG} recusado: {hp!r} não é IP de loopback; esta skill só sobe o proxy em 127.0.0.1")
+        return 2
+    if name == "caveman" and mode == "compress" and not accept:
+        print(f"{TAG} recusado: no modo compress o caveman-proxy comprime também o texto que o usuário digita "
+              "(CAV-01) e não há opção que evite isso. Só use com --accept-user-text-compression, depois de o usuário aceitar.")
+        return 2
+    binary = shutil.which(spec["binary"])
+    if not binary and not dry:
+        print(f"{TAG} {spec['binary']} não está instalado. Esta skill não instala binários: peça ao usuário "
+              "para instalar pela fonte oficial, numa versão fixa.")
+        return 3
+    if not dry and health(name, hp)[0]:
+        print(f"{TAG} já existe um {spec['service']} em {hp}. Variáveis novas não valem para uma instância "
+              f"rodando: rode `lc_proxy.py check {name}` e, se precisar, pare a instância atual antes.")
+        return 4
+    env, visible = secure_env(name, mode)
+    argv = [binary or spec["binary"]] + (["start"] if name == "rtk" else [])
+    print(f"{TAG} comando: {' '.join(argv)} (ambiente por lista de permissão)")
+    for k, v in visible.items():
+        print(f"{TAG}   {k}={v}")
+    if dry:
+        print(f"{TAG} --dry-run: nada foi iniciado")
+        return 0
+    sd = state_dir()
+    log = sd / f"{name}.log"
+    fd = os.open(log, os.O_WRONLY | os.O_CREAT | os.O_APPEND | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    proc = subprocess.Popen(argv, env=env, cwd=str(sd), stdin=subprocess.DEVNULL, stdout=fd, stderr=fd,
+                            start_new_session=True)
+    os.close(fd)
+    ident = None
+    for _ in range(30):
+        ident = proc_identity(proc.pid)
+        if ident:
+            break
+        time.sleep(0.05)
+    write_private(manifest_path(name), json.dumps({
+        "pid": proc.pid, "identity": ident, "binary": binary, "started": int(time.time()), "address": hp,
+        "mode": mode if name == "caveman" else "tool-output", "accepted_user_text_compression": bool(accept),
+        "caveman_home": visible.get("CAVEMAN_HOME"), "env": visible, "log": str(log)}, indent=1))
+    for _ in range(50):
+        if health(name, hp)[0]:
+            break
+        if proc.poll() is not None:
+            print(f"{TAG} o proxy saiu com código {proc.returncode}; veja {log}")
+            manifest_path(name).unlink(missing_ok=True)
+            return 5
+        time.sleep(0.1)
+    # a identidade pode mudar se um wrapper fizer exec: regrava com o processo final
+    final = proc_identity(proc.pid)
+    if final and final != ident:
+        m = read_manifest(name) or {}
+        m["identity"] = final
+        write_private(manifest_path(name), json.dumps(m, indent=1))
+    print(f"{TAG} iniciado (pid {proc.pid}); log em {log}")
+    return check(name)[0]
+
+
+def stop(name: str, purge: bool) -> int:
+    m = read_manifest(name)
+    if not m:
+        print(f"{TAG} nenhuma instância de {name} subida por este script; não paro processos que não iniciei")
+        return 1
+    pid = m.get("pid")
+    if proc_identity(pid) is None:
+        print(f"{TAG} o processo {pid} já não existe")
+    elif not same_process(m):
+        print(f"{TAG} recusado: o pid {pid} agora é outro processo (executável ou início diferentes); não vou pará-lo")
+        manifest_path(name).unlink(missing_ok=True)
+        return 1
+    else:
+        try:
+            os.kill(int(pid), signal.SIGTERM)
+        except ProcessLookupError:
+            pass
+        except PermissionError:
+            print(f"{TAG} recusado: sem permissão para sinalizar o pid {pid}")
+            return 1
+        for _ in range(50):
+            if proc_identity(pid) is None:
+                break
+            time.sleep(0.1)
+        print(f"{TAG} {name} parado (pid {pid})")
+    manifest_path(name).unlink(missing_ok=True)
+    if purge:
+        sd = state_dir()
+        targets = [sd / "caveman-home"] if name == "caveman" else [sd / "rtk-proxy.db", sd / "rtk-proxy-memory.db"]
+        for t in targets:
+            if t.is_dir() and not t.is_symlink():
+                shutil.rmtree(t, ignore_errors=True)
+            else:
+                for f in t.parent.glob(t.name + "*"):
+                    f.unlink(missing_ok=True)
+        print(f"{TAG} dados locais apagados (originais guardados pelo proxy e estatísticas)")
+    return 0
+
+
+# ---------------------------------------------------------------- launch / env
+def agent_env(name: str) -> dict:
+    hp = addr(name)
+    base = url_for(hp, "").rstrip("/")
+    env = {"ANTHROPIC_BASE_URL": base, "ENABLE_TOOL_SEARCH": "true"}
+    no_proxy = [x for x in (os.environ.get("NO_PROXY") or os.environ.get("no_proxy") or "").split(",") if x]
+    for h in ("127.0.0.1", "localhost", "::1"):
+        if h not in no_proxy:
+            no_proxy.append(h)
+    env["NO_PROXY"] = env["no_proxy"] = ",".join(no_proxy)  # nunca passar o tráfego local por proxy corporativo
+    if name == "caveman":
+        tok = get_token(create=False)
+        if not tok:
+            raise SystemExit(f"{TAG} sem token: suba o proxy com `lc_proxy.py start caveman` primeiro")
+        cur = [l for l in (os.environ.get("ANTHROPIC_CUSTOM_HEADERS") or "").splitlines()
+               if l.strip() and not l.lower().lstrip().startswith("x-cave-api-key")]
+        env["ANTHROPIC_CUSTOM_HEADERS"] = "\n".join(cur + [f"x-cave-api-key: {tok}"])
+    return env
+
+
+def launch(name: str, cmd: list[str]) -> int:
+    if not cmd:
+        raise SystemExit(f"{TAG} informe o comando do agente depois de --")
+    print(f"{TAG} conferindo identidade e postura antes de apontar o agente…")
+    rc, verified = check(name)
+    if rc != 0 or not verified:
+        why = "há falhas acima" if rc != 0 else "a instância não teve a identidade provada (suba-a com `start`)"
+        print(f"{TAG} recusado: {why}. O tráfego e as credenciais da API não serão apontados para ela.")
+        return 1
+    env = dict(os.environ, **agent_env(name))
+    print(f"{TAG} iniciando {cmd[0]} com ANTHROPIC_BASE_URL={env['ANTHROPIC_BASE_URL']} (só neste processo)")
+    sys.stdout.flush()
+    os.execvpe(cmd[0], cmd, env)
+    return 0
+
+
+def print_env(name: str) -> int:
+    hp = addr(name)
+    print(f"export ANTHROPIC_BASE_URL={shlex.quote(url_for(hp, '').rstrip('/'))}")
+    print("export ENABLE_TOOL_SEARCH=true")
+    print("export NO_PROXY=\"${NO_PROXY:+$NO_PROXY,}127.0.0.1,localhost,::1\"")
+    if name == "caveman":
+        print(f'export ANTHROPIC_CUSTOM_HEADERS="x-cave-api-key: $(cat {shlex.quote(str(token_path()))})"')
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    cmd = []
+    if "--" in argv:
+        i = argv.index("--")
+        argv, cmd = argv[:i], argv[i + 1:]
+    ap = argparse.ArgumentParser(prog="lc_proxy.py")
+    sub = ap.add_subparsers(dest="op", required=True)
+    d = sub.add_parser("detect")
+    d.add_argument("--json", action="store_true")
+    for op in ("check", "start", "stop", "launch", "env"):
+        p = sub.add_parser(op)
+        p.add_argument("name", choices=sorted(PROXIES))
+        if op == "start":
+            p.add_argument("--mode", choices=("record", "compress"), default="record")
+            p.add_argument("--accept-user-text-compression", action="store_true")
+            p.add_argument("--dry-run", action="store_true")
+        if op == "stop":
+            p.add_argument("--purge", action="store_true")
+    a = ap.parse_args(argv)
+    if a.op == "detect":
+        d = detect()
+        if a.json:
+            print(json.dumps(d, ensure_ascii=False, indent=1))
+        else:
+            print_detect(d)
+        return 0
+    if a.op == "check":
+        return check(a.name)[0]
+    if a.op == "start":
+        return start(a.name, a.mode, a.accept_user_text_compression, a.dry_run)
+    if a.op == "stop":
+        return stop(a.name, a.purge)
+    if a.op == "launch":
+        return launch(a.name, cmd)
+    return print_env(a.name)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))