lingling 2.0.0__py3-none-any.whl

lingling/__init__.py

@@ -0,0 +1,21 @@
+"""Lingling -- official OpenCode, but your requests ride rotating Tor lanes."""
+
+import os
+import sys
+from pathlib import Path
+
+__version__ = "2.0.0"
+
+
+def data_dir() -> Path:
+    """Per-user runtime state (tor, lanes, proof log). Lives outside the
+    package -- a pip install must never write into site-packages."""
+    override = os.environ.get("LINGLING_DATA_DIR")
+    if override:
+        return Path(override)
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+        return Path(base) / "lingling"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "lingling"
+    return Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share")) / "lingling"

lingling/__main__.py

@@ -0,0 +1,4 @@
+from .cli import entry
+
+if __name__ == "__main__":
+    entry()

lingling/cli.py

@@ -0,0 +1,277 @@
+"""lingling -- official OpenCode, riding rotating Tor lanes.
+
+CLI entrypoint: boots Tor lanes, starts the local relay, then execs opencode
+with HTTPS_PROXY pointed at it; all other args pass through untouched.
+"""
+
+from __future__ import annotations
+
+import itertools
+import os
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+from . import __version__, data_dir, proof
+from .health import HealthDaemon
+from .lanes import TorManager
+from .relay import Relay
+
+DATA_DIR = data_dir()
+PROOF_LOG = DATA_DIR / "proof.log"
+
+DEFAULT_COUNTRIES = ["us", "de", "nl", "fr", "ro", "gb", "ca", "se", "pl", "ch"]
+
+_KITCHEN_LINES = [
+    "cooking the lanes", "baking it", "warming the exits",
+    "glazing the tunnel", "seasoning the circuits", "proofing the dough",
+    "preheating the relays", "tasting the traffic",
+]
+
+_SPIN = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+_PHRASE_COLORS = ["38;5;215", "38;5;222", "38;5;180", "38;5;173",
+                  "38;5;114", "38;5;109", "38;5;139", "38;5;175"]
+
+
+def _c(text: str, code: str) -> str:
+    if os.environ.get("NO_COLOR") or not sys.stdout.isatty():
+        return text
+    return f"\x1b[{code}m{text}\x1b[0m"
+
+
+class _Loader:
+    """Self-rewriting status line; deliberately vibe-only, no lane counts or progress bar."""
+
+    def __init__(self) -> None:
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def set(self, detail: str = "") -> None:
+        # Kept for API compatibility; details are intentionally not shown.
+        pass
+
+    def start(self) -> None:
+        if not sys.stdout.isatty():
+            return
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def _run(self) -> None:
+        tick = itertools.count()
+        while not self._stop.is_set():
+            t = next(tick)
+            spin = _c(_SPIN[t % len(_SPIN)], "1;38;5;220")
+            idx = (t // 24) % len(_KITCHEN_LINES)
+            msg = _c(_KITCHEN_LINES[idx], _PHRASE_COLORS[idx])
+            sys.stdout.write(f"\r\x1b[K {spin} {msg}")
+            sys.stdout.flush()
+            time.sleep(0.09)
+
+    def stop(self, final: str = "") -> None:
+        self._stop.set()
+        if self._thread:
+            self._thread.join(timeout=2)
+            self._thread = None
+        if sys.stdout.isatty():
+            sys.stdout.write("\r\x1b[K")
+            if final:
+                sys.stdout.write(final + "\n")
+            sys.stdout.flush()
+
+
+def _parse_args(argv: list[str]) -> dict:
+    """Split lingling's own flags from args passed through to opencode."""
+    opts = {
+        "lanes": int(os.environ.get("LINGLING_TOR_COUNT", "5") or 5),
+        "no_tor": False,
+        "no_proof": False,
+        "proof_tail": None,
+        "demo": False,
+        "passthrough": [],
+    }
+    skip = False
+    for i, a in enumerate(argv):
+        if skip:
+            skip = False
+            continue
+        if a == "--proof":
+            opts["proof_tail"] = argv[i + 1] if i + 1 < len(argv) else ""
+            skip = True
+        elif a == "--demo":
+            opts["demo"] = True
+        elif a == "--lanes":
+            try:
+                opts["lanes"] = max(1, int(argv[i + 1]))
+                opts["lanes_explicit"] = True
+            except (IndexError, ValueError):
+                pass
+            skip = True
+        elif a == "--no-tor":
+            opts["no_tor"] = True
+        elif a == "--no-proof":
+            opts["no_proof"] = True
+        else:
+            opts["passthrough"].append(a)
+    return opts
+
+
+def main(argv: list[str]) -> int:
+    opts = _parse_args(argv)
+
+    if opts["proof_tail"] is not None:
+        return proof.tail(Path(opts["proof_tail"] or str(PROOF_LOG)))
+
+    if opts["demo"]:
+        from .demo import run_demo
+        question = " ".join(opts["passthrough"]).strip() or (
+            "In one sentence: who are you, and what exit node do you think "
+            "this request came from?")
+        lanes = opts["lanes"] if opts.get("lanes_explicit") else 2
+        return run_demo(question, lanes=lanes)
+
+    if "--version" in opts["passthrough"] or "-v" in opts["passthrough"]:
+        print(f"lingling {__version__} (wraps opencode)")
+        return 0
+
+    opencode = shutil.which("opencode")
+    if opencode is None:
+        print("lingling: couldn't find `opencode` on your PATH.")
+        print("Install it first (https://opencode.ai) and re-run.")
+        return 1
+
+    loader = _Loader()
+    loader.start()
+    manager: TorManager | None = None
+    daemon: HealthDaemon | None = None
+    relay: Relay | None = None
+    direct = opts["no_tor"]
+
+    try:
+        if not direct:
+            manager = TorManager(
+                DATA_DIR, count=opts["lanes"],
+                exit_countries=DEFAULT_COUNTRIES,
+                tor_exe=os.environ.get("LINGLING_TOR_EXE", ""),
+                log=lambda *a: None,
+            )
+            loader.set()
+            err = manager.setup_lanes()
+            if err:
+                loader.stop(_c(f" !! tor unavailable ({err}) -- going direct",
+                               "33"))
+                direct = True
+            else:
+                emit = proof.make_emitter(PROOF_LOG)
+                daemon = HealthDaemon(manager, event=emit,
+                                      log=lambda *a: None)
+
+                # Boot order: only lane 1 cooks in the foreground; the rest follow in background.
+                first = manager.lanes[0]
+                manager.start_lanes([first])
+
+                # Block until lane 1 provably carries traffic, else the user's first prompt dies.
+                deadline = time.time() + 150
+                while time.time() < deadline:
+                    verdict = daemon.probe_lane(first)
+                    if verdict == "healthy":
+                        first.healthy = True
+                        first.unhealthy_cycles = 0
+                        break
+                    if verdict == "burned":
+                        first.burned_cycles += 1
+                        daemon._heal_burn(first)
+                    time.sleep(2)
+                if first.healthy is not True:
+                    loader.stop(_c(" !! the kitchen stayed cold -- "
+                                   "going direct", "31"))
+                    direct = True
+                    manager.stop_all()
+                daemon.start()
+
+        if direct:
+            loader.stop()
+            print(_c("lingling: no lanes -- opencode rides your own IP.\n",
+                     "33"))
+            return _run_opencode(opencode, opts["passthrough"], None)
+
+        emit = proof.make_emitter(PROOF_LOG)
+        relay = Relay(manager, event=emit)
+        port = relay.start()
+
+        # Per-request proof via local TLS termination; best-effort, falls back to blind tunnels.
+        ca_pem = None
+        if os.environ.get("LINGLING_NO_MITM", "").lower() not in ("1", "true"):
+            try:
+                from . import mitm
+                relay.cert_shop = mitm.CertShop(DATA_DIR / "mitm")
+                ca_pem = relay.cert_shop.ca_pem_path
+            except Exception:  # noqa: BLE001
+                pass
+
+        loader.stop(_c(" served! lanes are hot -- proof is in the other "
+                       "window.", "1;32"))
+        if not opts["no_proof"]:
+            proof.spawn_proof_window(PROOF_LOG)
+
+        # Remaining lanes bootstrap in background; health probes join them to rotation as they come up.
+        rest = manager.lanes[1:]
+        if rest:
+            def _cook_rest() -> None:
+                for lane in rest:
+                    emit({"type": "lane", "kind": "heal", "t": time.time(),
+                          "lane": lane.index, "cc": lane.exit_country,
+                          "ip": "",
+                          "msg": f"lane {lane.index} {{{lane.exit_country}}} "
+                                 f"registering in the background ..."})
+                manager.start_lanes(rest)
+
+            threading.Thread(target=_cook_rest, name="lane-cook",
+                             daemon=True).start()
+
+        env = dict(os.environ)
+        for var in ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"):
+            env[var] = f"http://127.0.0.1:{port}"
+        env["NO_PROXY"] = env["no_proxy"] = "localhost,127.0.0.1"
+        if ca_pem:
+            # Let opencode trust our local CA so we can log each model call.
+            env["NODE_EXTRA_CA_CERTS"] = str(ca_pem)
+        return _run_opencode(opencode, opts["passthrough"], env)
+    finally:
+        if daemon:
+            daemon.stop()
+        if relay:
+            relay.stop()
+        if manager and not direct:
+            manager.stop_all()
+        if not direct:
+            try:
+                proof.make_emitter(PROOF_LOG)(proof.DONE)
+            except Exception:  # noqa: BLE001
+                pass
+
+
+def _run_opencode(binary: str, args: list[str],
+                  env: dict | None) -> int:
+    """Exec opencode with stdio inherited so it owns the terminal."""
+    try:
+        proc = subprocess.Popen([binary, *args], env=env)
+    except OSError as exc:
+        print(f"lingling: couldn't launch opencode: {exc}")
+        return 1
+    try:
+        return proc.wait()
+    except KeyboardInterrupt:
+        try:
+            proc.terminate()
+            proc.wait(timeout=5)
+        except Exception:  # noqa: BLE001
+            pass
+        return 130
+
+
+def entry() -> None:
+    sys.exit(main(sys.argv[1:]))

lingling/demo.py

@@ -0,0 +1,134 @@
+"""``lingling --demo`` -- fire one real Muse Spark request through a real
+lane and show the receipts: which lane, which exit IP, and the reply.
+
+Muse Spark lives only on the Responses API (``POST /zen/v1/responses``), not chat/completions.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+
+from . import data_dir, netutil
+from .health import UPSTREAM_HOST, UPSTREAM_UA, HealthDaemon
+from .lanes import TorManager
+
+DEFAULT_COUNTRIES = ["us", "de", "nl", "fr", "ro", "gb", "ca", "se", "pl", "ch"]
+
+MODEL = "muse-spark-1.2-contributor-free"
+DATA_DIR = data_dir()
+
+
+def _say(msg: str) -> None:
+    print(msg, flush=True)
+
+
+def _extract_text(obj: dict) -> str:
+    """Pull the assistant text out of a Responses API reply."""
+    for item in obj.get("output") or []:
+        if not isinstance(item, dict):
+            continue
+        if item.get("type") == "message":
+            parts = []
+            for c in item.get("content") or []:
+                if isinstance(c, dict) and c.get("type") == "output_text":
+                    parts.append(c.get("text", ""))
+            if parts:
+                return "\n".join(parts)
+    if isinstance(obj.get("output_text"), str):
+        return obj["output_text"]
+    return ""
+
+
+def run_demo(question: str, lanes: int = 2) -> int:
+    manager = TorManager(DATA_DIR, count=lanes,
+                         exit_countries=DEFAULT_COUNTRIES, log=lambda *a: None)
+
+    _say("== cooking the lanes (first run downloads tor, ~1-2 min) ==")
+    err = manager.setup_lanes()
+    if err:
+        _say(f" !! tor unavailable: {err}")
+        return 1
+    manager.start_all(on_lane=lambda lane, status: _say(
+        f"    lane {lane.index} {{{lane.exit_country}}}: {status}"))
+
+    daemon = HealthDaemon(manager)
+    _say("\n== probing each lane against the real upstream ==")
+    deadline = time.time() + 150
+    ready = []
+    while time.time() < deadline:
+        for lane in manager.lanes:
+            if lane.healthy is not True:
+                verdict = daemon.probe_lane(lane)
+                lane.healthy = verdict == "healthy"
+                if verdict == "healthy":
+                    _say(f"    lane {lane.index} {{{lane.exit_country}}} up, "
+                         f"exit IP {lane.exit_ip or '?'}")
+                elif verdict == "burned":
+                    lane.burned_cycles += 1
+                    daemon._heal_burn(lane)
+        ready = manager.healthy_lanes()
+        if ready:
+            break
+        time.sleep(2)
+    if not ready:
+        _say(" !! no lane came up -- cannot run the demo")
+        manager.stop_all()
+        return 1
+
+    lane = ready[0]
+    _say(f"\n== firing the request through lane {lane.index} "
+         f"{{{lane.exit_country}}}, exit IP {lane.exit_ip or '?'} ==")
+    _say(f"    model: {MODEL}")
+    _say(f"    you:   {question}")
+
+    payload = {
+        "model": MODEL,
+        "input": [{
+            "role": "user",
+            "content": [{"type": "input_text", "text": question}],
+        }],
+        "stream": False,
+        "store": False,
+        "max_output_tokens": 4096,
+    }
+    t0 = time.time()
+    try:
+        code, body = netutil.https_via_socks(
+            lane.socks_port, UPSTREAM_HOST, "POST", "/zen/v1/responses",
+            UPSTREAM_UA, body=json.dumps(payload).encode(),
+            timeout=180.0)
+    except Exception as exc:  # noqa: BLE001
+        _say(f" !! the lane dropped the request: {exc}")
+        manager.stop_all()
+        return 1
+    dt = time.time() - t0
+
+    if code == 429:
+        _say(" !! 429 from upstream -- the lane would now be re-cooked "
+             "(that's the rotation working)")
+        manager.stop_all()
+        return 1
+    if code != 200:
+        _say(f" !! upstream answered HTTP {code}: {body[:400]!r}")
+        manager.stop_all()
+        return 1
+
+    try:
+        obj = json.loads(body)
+    except json.JSONDecodeError:
+        _say(f" !! non-JSON reply: {body[:400]!r}")
+        manager.stop_all()
+        return 1
+
+    text = _extract_text(obj)
+    usage = obj.get("usage") or {}
+    _say(f"\n== {MODEL} answered through lane {lane.index} in {dt:.1f}s ==")
+    _say(f"    exit IP seen by upstream: {lane.exit_ip or '?'}")
+    if usage:
+        _say(f"    tokens: {json.dumps(usage)}")
+    _say("")
+    _say(text or "(empty reply)")
+    _say("")
+    manager.stop_all()
+    return 0

lingling/health.py

@@ -0,0 +1,222 @@
+"""Lane health daemon -- this is what makes rate limits invisible.
+
+A TLS tunnel can't be inspected by the relay, so each lane periodically
+probes the real upstream through its own SOCKS port and is healed (restarted
+or regenerated from scratch) before your next request would have used it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from typing import Callable, Dict, Optional
+
+from . import netutil
+from .lanes import Lane, TorManager
+
+UPSTREAM_HOST = "opencode.ai"
+UPSTREAM_PROBE_PATH = "/zen/v1/models"
+# The free tier instantly 429s requests without this UA; a probe lacking it would call every lane burned.
+UPSTREAM_UA = os.environ.get("LINGLING_UPSTREAM_USER_AGENT", "opencode/1.0")
+
+PROBE_TIMEOUT = 15.0
+# Consecutive failed cycles before a dead lane escalates from restart to regenerate.
+_ESCALATE_AFTER = 2
+# Consecutive 429 probes before cheap heals give way to rotating the exit country + regenerating.
+_BURN_ESCALATE_AFTER = 3
+# Min gap between regenerates; Tor bootstrap is 30-90s and re-rolling faster just keeps the lane booting.
+_REGEN_COOLDOWN_S = 1200.0
+# A sidelined lane gets one re-probe after this long; blocks do lift.
+_SIDELINE_RECHECK_S = 3600.0
+_FAST_FAIL_CYCLES = 4
+
+
+class HealthDaemon:
+    def __init__(
+        self,
+        tor: TorManager,
+        check_interval: float = 45.0,
+        event: Optional[Callable[[Dict], None]] = None,
+        log: Optional[Callable[..., None]] = None,
+    ) -> None:
+        self.tor = tor
+        self.check_interval = check_interval
+        # ``event`` receives proof-log dicts ({"type": "lane", ...}).
+        self._emit = event or (lambda e: None)
+        self.log = log or (lambda *a, **k: None)
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._warmup = True
+
+    def start(self) -> None:
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(
+            target=self._loop, name="lane-health", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread:
+            self._thread.join(timeout=5)
+            self._thread = None
+
+    def _loop(self) -> None:
+        while not self._stop.is_set():
+            try:
+                self.check_once()
+            except Exception as exc:  # noqa: BLE001
+                self.log("health: cycle flamed out: %s", exc)
+            self._stop.wait(self.check_interval)
+
+    def probe_lane(self, lane: Lane) -> str:
+        """One probe round. Returns "healthy" | "burned" | "dead"."""
+        if not netutil.port_is_open("127.0.0.1", lane.socks_port,
+                                    timeout=netutil.PORT_CHECK_TIMEOUT):
+            return "dead"
+        try:
+            code, _ = netutil.https_get_via_socks(
+                lane.socks_port, UPSTREAM_HOST, UPSTREAM_PROBE_PATH,
+                UPSTREAM_UA, timeout=PROBE_TIMEOUT)
+            if code == 429:
+                return "burned"
+            if code == 0:
+                return "dead"
+        except Exception:  # noqa: BLE001
+            return "dead"
+        # Lane is carrying traffic; fingerprint its exit IP for the proof pane.
+        try:
+            code, body = netutil.https_get_via_socks(
+                lane.socks_port, "check.torproject.org", "/api/ip",
+                UPSTREAM_UA, timeout=PROBE_TIMEOUT)
+            if code == 200:
+                obj = json.loads(body.decode("utf-8", "replace"))
+                if obj.get("IsTor") and obj.get("IP"):
+                    lane.exit_ip = str(obj["IP"])
+        except Exception:  # noqa: BLE001
+            pass
+        return "healthy"
+
+    def check_once(self) -> None:
+        for lane in self.tor.lanes:
+            if self._stop.is_set():
+                return
+            if lane.healing:
+                continue
+            if lane.sidelined:
+                self._maybe_revive(lane)
+                continue
+
+            verdict = self.probe_lane(lane)
+            if verdict == "healthy":
+                was = lane.healthy
+                lane.healthy = True
+                lane.unhealthy_cycles = 0
+                lane.burned_cycles = 0
+                if was is not True:
+                    self._emit_lane(lane, "up",
+                                    f"lane {lane.index} {{{lane.exit_country}}} "
+                                    f"is cooking -- exit {lane.exit_ip or '?'}")
+                continue
+
+            lane.healthy = False
+            # Warmup grace: first failed probe on a live port means the first circuit is still building.
+            if self._warmup and netutil.port_is_open(
+                    "127.0.0.1", lane.socks_port, timeout=netutil.PORT_CHECK_TIMEOUT):
+                continue
+
+            if verdict == "burned":
+                lane.unhealthy_cycles = 0
+                lane.burned_cycles += 1
+                self._heal_burn(lane)
+            else:
+                lane.burned_cycles = 0
+                lane.unhealthy_cycles += 1
+                self._heal_dead(lane)
+        self._warmup = False
+
+    def _heal_burn(self, lane: Lane) -> None:
+        """429 from upstream: lane is already out of rotation (caller set
+        healthy=False); re-cook from scratch, rotating exit country on repeat burns."""
+        lane.healing = True
+        try:
+            cooldown_left = (_REGEN_COOLDOWN_S
+                             - (time.time() - lane.last_regenerate_at))
+            if lane.last_regenerate_at and cooldown_left > 0:
+                if lane.burned_cycles <= 1:
+                    self._emit_lane(
+                        lane, "burn",
+                        f"lane {lane.index} hit a hidden limit -- parked "
+                        f"while it cools, other lanes have your traffic")
+                return
+            self._emit_lane(
+                lane, "burn",
+                f"lane {lane.index} hit a hidden limit -- your traffic moved "
+                f"to a fresh lane; re-cooking this one from scratch")
+            if lane.burned_cycles >= _BURN_ESCALATE_AFTER:
+                new_cc = self.tor.rotate_exit_country(lane)
+                if new_cc:
+                    self._emit_lane(
+                        lane, "rotate",
+                        f"lane {lane.index} keeps burning -- re-cooking on a "
+                        f"new country {{{new_cc}}}")
+            lane.last_regenerate_at = time.time()
+            lane.burned_cycles = 0
+            self.tor.regenerate_lane(lane)
+        finally:
+            lane.healing = False
+
+    def _heal_dead(self, lane: Lane) -> None:
+        if lane.unhealthy_cycles >= _FAST_FAIL_CYCLES:
+            lane.sidelined = True
+            lane.last_sideline_at = time.time()
+            self._emit_lane(lane, "sidelined",
+                            f"lane {lane.index} sat out (blocked exit) -- "
+                            f"will retry later")
+            return
+        lane.healing = True
+        try:
+            if lane.unhealthy_cycles <= _ESCALATE_AFTER:
+                self._emit_lane(lane, "heal",
+                                f"lane {lane.index} dropped -- poking it")
+                if not self.tor.restart_lane(lane):
+                    self._emit_lane(
+                        lane, "fail",
+                        f"lane {lane.index} would not restart -- will "
+                        f"re-cook it from scratch if it stays down")
+                return
+            cooldown_left = (_REGEN_COOLDOWN_S
+                             - (time.time() - lane.last_regenerate_at))
+            if lane.last_regenerate_at and cooldown_left > 0:
+                return
+            lane.last_regenerate_at = time.time()
+            self._emit_lane(lane, "heal",
+                            f"lane {lane.index} stayed down -- re-cooking "
+                            f"from scratch")
+            if not self.tor.regenerate_lane(lane):
+                self._emit_lane(lane, "fail",
+                                f"lane {lane.index} refused to re-cook")
+        finally:
+            lane.healing = False
+
+    def _maybe_revive(self, lane: Lane) -> None:
+        if time.time() - lane.last_sideline_at < _SIDELINE_RECHECK_S:
+            return
+        if self.probe_lane(lane) == "healthy":
+            lane.sidelined = False
+            lane.unhealthy_cycles = 0
+            lane.healthy = True
+            self._emit_lane(lane, "up",
+                            f"lane {lane.index} revived -- back in the kitchen")
+        else:
+            lane.last_sideline_at = time.time()
+
+    def _emit_lane(self, lane: Lane, kind: str, message: str) -> None:
+        self._emit({
+            "type": "lane", "kind": kind, "t": time.time(),
+            "lane": lane.index, "cc": lane.exit_country,
+            "ip": lane.exit_ip, "msg": message,
+        })