opencode-llmstack 0.6.0__py3-none-any.whl

llmstack/commands/start.py

@@ -0,0 +1,360 @@
+"""``llmstack start`` -- bring up the stack and enter the env-prepared subshell.
+
+The channel is **decided at install time** and persisted to
+``.llmstack/default-channel`` -- ``start`` reads that marker and never
+re-derives the channel from the environment. Three channels exist:
+
+  *Local* (``current`` / ``next``)
+    Generate ``llama-swap.yaml`` for the chosen channel, launch
+    llama-swap + the FastAPI router locally, and drop into a subshell
+    with ``OPENCODE_CONFIG`` exported. The yaml is regenerated on every
+    fresh launch so it always reflects the live ``models.ini``; if the
+    daemons are already up under our pid files we leave the loaded yaml
+    alone. The ``--current`` / ``--next`` flags pick which of the two
+    local channels to launch *for this run* (without rewriting the
+    marker -- only ``install`` does that).
+
+    Daemon state has two branches:
+      (a) local pid file says daemons are up   -> idempotent, channel-checked,
+                                                  no yaml regeneration
+      (b) nothing in the pid file              -> regenerate yaml, launch
+                                                  fresh. If port :10102 is
+                                                  already in use by *another*
+                                                  process (typically another
+                                                  project on this host) we
+                                                  refuse: the user should
+                                                  ``llmstack install --external``
+                                                  to wire this project as a
+                                                  thin client of those
+                                                  daemons, or stop them
+                                                  first.
+
+  *External* (``external``)
+    Don't launch anything; verify the marker's ``/health`` endpoint is
+    reachable and drop into the subshell with ``LLMSTACK_CHANNEL=external``.
+    The URL was pinned by ``llmstack install --external [URL]``; an
+    external install with no URL defaults to the local router
+    (``http://127.0.0.1:10101``), which is the laptop-with-N-projects
+    case where one project owns the daemons and the others are clients.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from pathlib import Path
+
+from llmstack.commands._helpers import (
+    is_running,
+    port_responds,
+    read_pid,
+    spawn_daemon,
+)
+from llmstack.generators import render_to
+from llmstack.generators.llama_swap import render as render_yaml
+from llmstack.generators.llama_swap import validate as validate_yaml
+from llmstack.paths import (
+    DEFAULT_REMOTE_URL,
+    ROUTER_PORT,
+    SWAP_PORT,
+    ChannelMark,
+    ensure_state_dirs,
+    read_marker,
+    write_marker,
+)
+from llmstack.shell_env import spawn_subshell
+from llmstack.tiers import load_tiers
+
+
+def _print_help() -> None:
+    print("usage: llmstack start [--current | --next] [--detach]")
+
+
+def _queued_next_tiers() -> list[str]:
+    """Names of every tier that has *some* queued upgrade target.
+
+    Backend-aware: gguf tiers with ``hf_file_next`` qualify, and so do
+    bedrock tiers with ``aws_model_id_next``. Used to short-circuit
+    ``--next`` when nothing's queued.
+    """
+    return sorted(t.name for t in load_tiers().values() if t.has_next)
+
+
+def _start_remote(detach: bool, url: str) -> int:
+    """Client-mode start: just verify the remote and drop into the shell.
+
+    ``url`` is the remote-router base URL pinned by ``install --external``
+    into ``default-channel``. It is *not* re-derived from the environment
+    here -- the marker is canonical post-install, and silently following
+    a stale env var would lie to the user about which remote opencode is
+    actually wired to (the URL is baked into ``opencode.json`` at install
+    time).
+
+    The reachability probe hits ``GET /models.ini`` rather than a
+    dedicated ``/health`` endpoint -- a 200 there proves both that the
+    router is up and that it actually has a config worth talking to,
+    which is what the thin client needs. The router has no separate
+    ``/health`` route.
+    """
+    paths = ensure_state_dirs()
+
+    if not paths.opencode_json.is_file():
+        raise SystemExit(
+            f"no .llmstack/opencode.json in {paths.work_dir} -- run: llmstack install --external\n"
+            f"    (or `llmstack install --external {url}` to keep this remote URL)"
+        )
+
+    print(f"[*] external llmstack: {url}")
+    probe_url = f"{url}/models.ini"
+    if port_responds(probe_url, timeout=5.0):
+        print(f"[OK] {probe_url} responds.")
+    else:
+        print(f"[!] {probe_url} did not respond -- is the remote stack up?", file=sys.stderr)
+        print("    proceeding anyway; opencode will surface the error on first request.", file=sys.stderr)
+
+    write_marker(paths.active_marker, ChannelMark("external", url))
+
+    print()
+    print("[OK] client mode (channel: external).")
+    print()
+    print(f"  router       {url}     (external)")
+    print()
+    print("Try:")
+    print(f"  curl -s {url}/v1/models | jq '.data[].id'")
+    print(f"  curl -s {url}/models.ini | head")
+    print()
+    print("Disconnect:")
+    print("  exit                # leave the subshell (daemons are external, nothing to stop)")
+
+    if detach:
+        return 0
+
+    # Same "spawn only when no active env" rule as the local-mode path.
+    if os.environ.get("LLMSTACK_ACTIVE") == "1":
+        cur_chan = os.environ.get("LLMSTACK_CHANNEL", "?")
+        if cur_chan == "external":
+            print("[=] already active as external client -- env is up to date.")
+        else:
+            print(
+                f"[*] switching to external client ({cur_chan} -> external); env in "
+                "this shell is now stale."
+            )
+            print("    refresh prompt + env in this shell:")
+            print('        eval "$(llmstack reload)"')
+        return 0
+
+    spawn_subshell("external")
+    return 0  # unreachable
+
+
+def run(args: list[str]) -> int:
+    requested: str | None = None
+    detach = False
+    for arg in args:
+        if arg == "--next":
+            requested = "next"
+        elif arg == "--current":
+            requested = "current"
+        elif arg in ("--detach", "--no-shell"):
+            detach = True
+        elif arg in ("-h", "--help"):
+            _print_help()
+            return 0
+        else:
+            print(f"[!] unknown arg to start: {arg} (try --next, --current, --detach, -h)")
+            return 2
+
+    paths = ensure_state_dirs()
+    default = read_marker(paths.default_marker)
+
+    # External installs short-circuit to the thin-client path. The URL
+    # is taken from the marker (set by ``install --external``); we
+    # never re-derive it from the env.
+    if default and default.channel == "external":
+        if requested is not None:
+            print(
+                "[!] --current / --next have no effect for external installs "
+                "(no daemons to launch).",
+                file=sys.stderr,
+            )
+        url = (default.url or "").rstrip("/") or DEFAULT_REMOTE_URL
+        return _start_remote(detach, url)
+
+    # Local mode -- decide which of current/next to launch.
+    if requested is not None:
+        channel = requested
+    elif default and default.channel in ("current", "next"):
+        channel = default.channel
+    else:
+        channel = "current"
+
+    if not paths.llama_swap_bin.exists() or not os.access(paths.llama_swap_bin, os.X_OK):
+        raise SystemExit(f"missing {paths.llama_swap_bin} (run: llmstack setup)")
+    if not paths.opencode_json.is_file():
+        raise SystemExit(f"no .llmstack/opencode.json in {paths.work_dir} -- run: llmstack install")
+
+    if is_running(paths.swap_pid):
+        launch_daemons = False
+        live_mark = read_marker(paths.active_marker)
+        live = live_mark.channel if live_mark else channel
+        if live != channel:
+            print(
+                f"[!] llama-swap is already running in '{live}' channel; "
+                f"refusing to also start '{channel}'. Stop the stack first:",
+                file=sys.stderr,
+            )
+            print("\n      llmstack stop", file=sys.stderr)
+            print(f"      llmstack start --{channel}\n", file=sys.stderr)
+            return 1
+    elif port_responds(f"http://127.0.0.1:{SWAP_PORT}/health"):
+        # Something is already listening on :10102, but it isn't ours
+        # (no pid file in this project's state dir). The pre-flag flow
+        # silently joined as "shared", which was a footgun: a `stop`
+        # from this project would tear down the other project's
+        # daemons and we couldn't bring them back without local
+        # tooling. Instead, refuse and tell the user how to wire this
+        # project as a proper thin client.
+        print(
+            f"[!] port :{SWAP_PORT} is already in use (daemons started by "
+            "another project on this host).",
+            file=sys.stderr,
+        )
+        print("    This project is installed for local mode -- it expects to own", file=sys.stderr)
+        print("    those daemons. To run as a thin client of the running stack:", file=sys.stderr)
+        print("", file=sys.stderr)
+        print("        llmstack install --external", file=sys.stderr)
+        print("", file=sys.stderr)
+        print("    (--external defaults to http://127.0.0.1:10101, the local router.)", file=sys.stderr)
+        print("    To take over instead, stop the running daemons first:", file=sys.stderr)
+        print("", file=sys.stderr)
+        print("        llmstack stop && llmstack start", file=sys.stderr)
+        return 1
+    else:
+        launch_daemons = True
+
+    if launch_daemons:
+        if channel == "next":
+            queued = _queued_next_tiers()
+            if not queued:
+                print(
+                    "[!] no tiers have hf_file_next or aws_model_id_next set in models.ini -- "
+                    "nothing to do.",
+                    file=sys.stderr,
+                )
+                print(
+                    "    add a *_next line to a tier and re-run, or use --current.",
+                    file=sys.stderr,
+                )
+                return 1
+            print(f"[*] generating next-channel yaml -> {paths.llama_swap_yaml}")
+            print(f"    queued upgrade tiers: {' '.join(queued)}")
+        else:
+            print(f"[*] generating yaml -> {paths.llama_swap_yaml}")
+        render_to(
+            paths.llama_swap_yaml,
+            render=lambda p: Path(p).write_text(render_yaml(use_next=(channel == "next"))),
+            validate=validate_yaml,
+        )
+
+    print(f"[*] channel: {channel}  ({paths.llama_swap_yaml.name})")
+
+    if launch_daemons:
+        print(f"[*] starting llama-swap on :{SWAP_PORT}")
+        spawn_daemon(
+            [
+                str(paths.llama_swap_bin),
+                "--config", str(paths.llama_swap_yaml),
+                "--listen", f"127.0.0.1:{SWAP_PORT}",
+            ],
+            log=paths.log_dir / "llama-swap.log",
+            pid_file=paths.swap_pid,
+        )
+        write_marker(paths.active_marker, ChannelMark(channel))
+        time.sleep(1)
+        if not is_running(paths.swap_pid):
+            print(f"[!] llama-swap failed to start. Check {paths.log_dir}/llama-swap.log")
+            paths.swap_pid.unlink(missing_ok=True)
+            paths.active_marker.unlink(missing_ok=True)
+            return 1
+        print(f"    pid {read_pid(paths.swap_pid)}")
+
+        print(f"[*] starting router on :{ROUTER_PORT}")
+        env = os.environ.copy()
+        env.setdefault("LLAMA_SWAP_URL", f"http://127.0.0.1:{SWAP_PORT}")
+        env.setdefault("ROUTER_HOST", "127.0.0.1")
+        env.setdefault("ROUTER_PORT", str(ROUTER_PORT))
+        # Lock-step with the gguf --use-next swap: bedrock tiers in the
+        # router pick aws_model_id_next when this flag is set.
+        if channel == "next":
+            env["LLMSTACK_USE_NEXT"] = "1"
+        else:
+            env.pop("LLMSTACK_USE_NEXT", None)
+        spawn_daemon(
+            [sys.executable, "-m", "llmstack.app"],
+            log=paths.log_dir / "router.log",
+            pid_file=paths.router_pid,
+            env=env,
+        )
+        time.sleep(1)
+        if not is_running(paths.router_pid):
+            print(f"[!] router failed to start. Check {paths.log_dir}/router.log")
+            paths.router_pid.unlink(missing_ok=True)
+            return 1
+        print(f"    pid {read_pid(paths.router_pid)}")
+    else:
+        print(f"[=] llama-swap already running (pid {read_pid(paths.swap_pid)}, channel {channel})")
+        if is_running(paths.router_pid):
+            print(f"[=] router already running (pid {read_pid(paths.router_pid)})")
+
+    other = "next" if channel == "current" else "current"
+    print()
+    print(f"[OK] stack is up (channel: {channel}).")
+    print()
+    print(f'  router       http://127.0.0.1:{ROUTER_PORT}     (OpenAI-compatible, "auto" routing)')
+    print(f"  llama-swap   http://127.0.0.1:{SWAP_PORT}     (raw model endpoints + UI)")
+    print()
+    print("Try:")
+    print(f"  curl -s http://127.0.0.1:{ROUTER_PORT}/v1/models | jq '.data[].id'")
+    print(f"  curl -s http://127.0.0.1:{ROUTER_PORT}/models.ini | head")
+    print()
+    print("Logs:")
+    print(f"  tail -f {paths.log_dir}/llama-swap.log")
+    print(f"  tail -f {paths.log_dir}/router.log")
+    print()
+    print("Switch channel (requires stop first):")
+    print(f"  llmstack restart --{other}")
+    print()
+    print("Stop:")
+    print("  llmstack stop")
+
+    if detach:
+        return 0
+
+    # Only spawn a subshell when the env isn't already wired up. Two cases:
+    #   - Hook installed + sourced: cd-ing into a project sets
+    #     LLMSTACK_ACTIVE=1 and friends. start just brings up daemons --
+    #     no need to nest another shell.
+    #   - Inside a previously-spawned llmstack shell: same deal.
+    # For users who haven't run `eval "$(llmstack activate <shell>)"`,
+    # spawn so they at least get OPENCODE_CONFIG / channel exports for
+    # this terminal.
+    if os.environ.get("LLMSTACK_ACTIVE") == "1":
+        cur_chan = os.environ.get("LLMSTACK_CHANNEL", "?")
+        if cur_chan == channel:
+            print(f"[=] already active in '{channel}' -- env is up to date.")
+        else:
+            # Daemons + active-channel marker are already on the new
+            # channel. The current shell's env + PROMPT lag behind --
+            # `llmstack reload` emits the eval-able snippet to fix that
+            # without nesting a subshell.
+            print(
+                f"[*] channel switched ({cur_chan} -> {channel}); env in this shell "
+                "is now stale."
+            )
+            print("    refresh prompt + env in this shell:")
+            print('        eval "$(llmstack reload)"')
+        return 0
+
+    spawn_subshell(channel)
+    return 0  # unreachable: spawn_subshell execvps

llmstack/commands/status.py

@@ -0,0 +1,260 @@
+"""``llmstack status`` -- show channel, pids, ``/v1/models``, llama-server load.
+
+The channel comes from ``.llmstack/default-channel`` (pinned by
+``install``). Two top-level reporting paths:
+
+  * ``current`` / ``next``  -- local install. Check pid files + port
+                               probes for our daemons. If port :10102
+                               responds without a pid file in *this*
+                               project's ``.llmstack/``, the daemons
+                               belong to another project on this host;
+                               we report that as "(other)" so the user
+                               knows the local daemons aren't ours --
+                               it's not an error, but also not
+                               something this project can ``stop``
+                               cleanly.
+  * ``external``            -- thin-client install. Skip all local
+                               checks; probe the remote-router URL
+                               from the marker.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import urllib.error
+import urllib.request
+
+import yaml
+
+from llmstack._platform import IS_WINDOWS
+from llmstack.commands._helpers import is_running, pgrep, port_responds, read_pid
+from llmstack.paths import (
+    DEFAULT_REMOTE_URL,
+    ROUTER_PORT,
+    SWAP_PORT,
+    read_marker,
+    resolve,
+)
+
+
+def _print_help() -> None:
+    print("usage: llmstack status")
+
+
+def _check_local(name: str, url: str) -> None:
+    """Report on a local daemon (router/llama-swap).
+
+    ``alive`` (we own the process via pid file) is the happy path.
+    ``responds`` without ``alive`` means the port is in use but the
+    process isn't ours -- another project on this host owns it. We
+    surface that as ``(other)`` rather than ``shared`` because there's
+    no special "shared" mode anymore: a local install can't manage
+    daemons it didn't spawn. ``llmstack install --external`` is the
+    documented way to consume those daemons cleanly.
+    """
+    paths = resolve()
+    pid_file = paths.state_dir / f"{name}.pid"
+    pid = read_pid(pid_file) if pid_file.is_file() else None
+    alive = pid is not None and is_running(pid_file)
+    responds = port_responds(url, timeout=3.0)
+
+    if alive:
+        status = f"pid {pid:<7}"
+    elif responds:
+        status = "(other)"
+    else:
+        status = "DOWN"
+    suffix = f"OK {url}" if responds else f"no response @ {url}"
+    print(f"  {name:<12} {status:<11}  {suffix}")
+
+
+def _print_process_table(pids: list[int]) -> None:
+    """Render ``pid / rss_mb / command`` for each pid (cross-OS).
+
+    POSIX: ``ps -o pid,rss,command`` (rss is in KB, we humanise to MB).
+    Windows: ``tasklist /FI "PID eq ..." /FO CSV`` (image name + memory
+    usage). Both branches print a header row.
+    """
+    if IS_WINDOWS:
+        rows: list[tuple[str, str, str]] = []
+        for pid in pids:
+            try:
+                proc = subprocess.run(
+                    ["tasklist", "/FI", f"PID eq {pid}", "/FO", "CSV", "/NH"],
+                    check=False,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.DEVNULL,
+                    text=True,
+                    timeout=10,
+                )
+            except (OSError, subprocess.SubprocessError):
+                continue
+            if proc.returncode != 0 or not proc.stdout.strip():
+                continue
+            import csv
+            for fields in csv.reader(proc.stdout.splitlines()):
+                if len(fields) < 5:
+                    continue
+                image, pid_str, _session, _sid, mem = fields[0], fields[1], fields[2], fields[3], fields[4]
+                if not pid_str.isdigit():
+                    continue
+                rss_mb = mem.replace(",", "").replace(" K", "").strip()
+                try:
+                    rss_mb = f"{int(rss_mb) // 1024} MB"
+                except ValueError:
+                    pass
+                rows.append((pid_str, rss_mb, image))
+        if not rows:
+            print("  (tasklist returned nothing)")
+            return
+        print(f"  {'PID':<8} {'RSS':<10} COMMAND")
+        for pid_str, rss, cmd in rows:
+            print(f"  {pid_str:<8} {rss:<10} {cmd}")
+        return
+
+    try:
+        ps = subprocess.run(
+            ["ps", "-o", "pid,rss,command", "-p", ",".join(str(p) for p in pids)],
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        )
+    except (OSError, subprocess.SubprocessError):
+        print("  (ps failed)")
+        return
+    for i, line in enumerate(ps.stdout.splitlines()):
+        if i == 0:
+            print(line)
+            continue
+        cols = line.split()
+        if len(cols) >= 3:
+            try:
+                rss_mb = int(cols[1]) // 1024
+                cols[1] = f"{rss_mb} MB"
+            except ValueError:
+                pass
+        print(" ".join(cols))
+
+
+def _list_models(base: str) -> None:
+    print()
+    print("current models in /v1/models:")
+    try:
+        with urllib.request.urlopen(f"{base}/v1/models", timeout=5) as resp:
+            data = json.load(resp)
+        for m in data.get("data", []):
+            print(f"  - {m.get('id')}")
+    except (urllib.error.URLError, ConnectionError, TimeoutError, OSError, json.JSONDecodeError):
+        print(f"  (no response @ {base}/v1/models)")
+
+
+def _print_remote_status(paths, url: str) -> int:
+    print(f"stack status (channel: external -- remote {url}):")
+    print(f"  work dir      {paths.work_dir}")
+    probe = f"{url}/models.ini"
+    responds = port_responds(probe, timeout=3.0)
+    suffix = f"OK {probe}" if responds else f"no response @ {probe}"
+    status = "external" if responds else "DOWN"
+    print(f"  {'router':<12} {status:<11}  {suffix}")
+
+    print()
+    if paths.opencode_json.is_file():
+        print(f"  opencode      {paths.opencode_json}")
+        if paths.agents_local.is_file():
+            print(f"  instructions  {paths.agents_local}")
+    else:
+        print("  opencode      (not generated for this work dir; run: llmstack install)")
+
+    if os.environ.get("LLMSTACK_ACTIVE") == "1":
+        cfg = os.environ.get("OPENCODE_CONFIG", "?")
+        chan = os.environ.get("LLMSTACK_CHANNEL", "?")
+        print(f"  in-shell      OPENCODE_CONFIG={cfg}, LLMSTACK_CHANNEL={chan}")
+
+    if responds:
+        _list_models(url)
+    return 0
+
+
+def run(args: list[str]) -> int:
+    for arg in args:
+        if arg in ("-h", "--help"):
+            _print_help()
+            return 0
+        print(f"[!] unknown arg to status: {arg}")
+        return 2
+
+    paths = resolve()
+
+    # Channel decision is pinned at install time; status just reads it.
+    # active-channel (set by `start`) takes precedence over default-channel
+    # (set by `install`) so a `start --next` run is reflected immediately.
+    default = read_marker(paths.default_marker)
+    active = read_marker(paths.active_marker)
+    persisted = active or default
+
+    if persisted and persisted.channel == "external":
+        url = (persisted.url or "").rstrip("/") or DEFAULT_REMOTE_URL
+        return _print_remote_status(paths, url)
+
+    if active:
+        channel = active.channel
+    elif default and default.channel in ("current", "next"):
+        channel = f"{default.channel} (or stopped)"
+    elif port_responds(f"http://127.0.0.1:{SWAP_PORT}/health"):
+        channel = "(other) -- daemons running on :10102 are not ours"
+    else:
+        channel = "current (or stopped)"
+
+    print(f"stack status (channel: {channel}):")
+    print(f"  work dir      {paths.work_dir}")
+    # Router has no /health route (dropped in v3.x); /v1/models always
+    # 200s on a live router. llama-swap is a separate binary with its
+    # own /health endpoint -- leave that one alone.
+    _check_local("router", f"http://127.0.0.1:{ROUTER_PORT}/v1/models")
+    _check_local("llama-swap", f"http://127.0.0.1:{SWAP_PORT}/health")
+
+    print()
+    if paths.opencode_json.is_file():
+        print(f"  opencode      {paths.opencode_json}")
+        if paths.agents_local.is_file():
+            print(f"  instructions  {paths.agents_local}")
+    else:
+        print("  opencode      (not generated for this work dir; run: llmstack install)")
+
+    if os.environ.get("LLMSTACK_ACTIVE") == "1":
+        cfg = os.environ.get("OPENCODE_CONFIG", "?")
+        chan = os.environ.get("LLMSTACK_CHANNEL", "?")
+        print(f"  in-shell      OPENCODE_CONFIG={cfg}, LLMSTACK_CHANNEL={chan}")
+
+    _list_models(f"http://127.0.0.1:{ROUTER_PORT}")
+
+    print()
+    print("loaded llama-server processes:")
+    pids = pgrep(r"llama-server.*--alias")
+    if pids:
+        _print_process_table(pids)
+    else:
+        print("  (none loaded)")
+
+    if channel.split()[0] == "next" and paths.llama_swap_yaml.is_file():
+        print()
+        print(f"next-channel swaps (from {paths.llama_swap_yaml.name}):")
+        try:
+            cfg = yaml.safe_load(paths.llama_swap_yaml.read_text())
+            for name, m in (cfg.get("models") or {}).items():
+                md = m.get("metadata") or {}
+                if md.get("channel") != "next":
+                    continue
+                hff = "?"
+                for line in (m.get("cmd") or "").splitlines():
+                    s = line.strip()
+                    if s.startswith("-hff ") and not s.lstrip().startswith("#"):
+                        hff = s[len("-hff "):].strip()
+                        break
+                print(f"  {name:<18}  -> {hff}  ({md.get('quant', '?')}, {md.get('size_gb', '?')} GB)")
+        except (OSError, yaml.YAMLError):
+            pass
+    return 0

llmstack/commands/stop.py

@@ -0,0 +1,73 @@
+"""``llmstack stop`` -- tear down the singleton router + llama-swap daemons.
+
+Three layers, in order:
+
+  1. SIGTERM/SIGKILL the pids in ``<state>/router.pid`` and
+     ``<state>/llama-swap.pid`` (if any).
+  2. ``pkill`` by pattern as a cross-project safety net for daemons that
+     were started from another project's ``.llmstack/``.
+  3. ``pkill`` any orphaned ``llama-server`` children spawned by
+     llama-swap.
+
+In **external mode** (channel pinned to ``external`` by ``install``)
+there are no local daemons to tear down -- we just clear the
+active-channel marker so ``status`` no longer reports the connection.
+"""
+
+from __future__ import annotations
+
+from llmstack.commands._helpers import (
+    kill_pid,
+    pgrep_describe,
+    pkill,
+    read_pid,
+)
+from llmstack.paths import is_remote, remote_url, resolve
+
+
+def _print_help() -> None:
+    print("usage: llmstack stop")
+
+
+def run(args: list[str]) -> int:
+    for arg in args:
+        if arg in ("-h", "--help"):
+            _print_help()
+            return 0
+        print(f"[!] unknown arg to stop: {arg}")
+        return 2
+
+    paths = resolve()
+
+    if is_remote():
+        url = remote_url()
+        if paths.active_marker.is_file():
+            paths.active_marker.unlink(missing_ok=True)
+            print(f"[OK] disconnected from {url} (active-channel cleared).")
+        else:
+            print(f"[=] not connected to any remote llmstack. (external URL: {url})")
+        print("    note: nothing local was running. To stop the *remote* daemons, run")
+        print("          'llmstack stop' on the host that started them.")
+        return 0
+
+    for name, pid_file in (("router", paths.router_pid), ("llama-swap", paths.swap_pid)):
+        pid = read_pid(pid_file)
+        if pid is not None:
+            print(f"[*] stopping {name} (pid {pid})")
+            kill_pid(pid)
+        pid_file.unlink(missing_ok=True)
+
+    cross_project = pgrep_describe(r"llama-swap --config|llmstack\.app")
+    if cross_project.strip():
+        print("[*] stopping daemons by name (no local pid files, started elsewhere):")
+        for line in cross_project.splitlines():
+            print(f"    {line}")
+        pkill(r"llama-swap --config")
+        pkill(r"llmstack\.app")
+
+    # Orphaned llama-server children (shouldn't happen, but cheap insurance)
+    pkill(r"llama-server.*--alias (code-fast|code-smart|plan|plan-uncensored)")
+
+    paths.active_marker.unlink(missing_ok=True)
+    print("[OK] stopped.")
+    return 0