opencode-llmstack 0.6.0__py3-none-any.whl

llmstack/shell_env.py

@@ -0,0 +1,927 @@
+"""Spawn the env-prepared subshell + emit shell activation hooks.
+
+Two distinct UX surfaces live here:
+
+  :func:`spawn_subshell`
+    Fallback path used by ``llmstack start`` when ``LLMSTACK_ACTIVE`` is
+    *not* already set (i.e. the user hasn't installed/sourced the
+    activate hook yet). ``execvp``s into the user's ``$SHELL`` with
+    ``OPENCODE_CONFIG`` + ``LLMSTACK_WORK_DIR`` + friends exported so
+    ``opencode`` picks up our local stack inside that one terminal
+    only. For zsh and bash we also write a transient rcfile that
+    sources the user's normal rc and prefixes the prompt with
+    ``[llmstack:<channel>]``.
+
+  :func:`activate_hook`
+    Used by ``llmstack activate <shell>``. Emits a self-contained
+    snippet that ``llmstack activate`` writes to
+    ``~/.<shell>_llmstack_hook`` and prints a ``source`` line for, so
+    ``eval "$(llmstack activate zsh)"`` regenerates and turns the hook
+    on in the current shell. The hook walks up from ``$PWD`` on every
+    prompt to find the nearest ``.llmstack/opencode.json`` and toggles
+    the env vars + prompt prefix accordingly. With the hook installed
+    the spawn fallback above is unused.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from llmstack._platform import IS_WINDOWS, default_shell, shell_family
+from llmstack.paths import PACKAGE_DIR, remote_url, resolve
+
+# 256-colour palette:
+#   current  = steel-blue    (38)   -- local stack, canonical channel
+#   next     = orange        (208)  -- local stack, queued-upgrade channel
+#   external = medium-purple (135)  -- thin client of a remote (or
+#                                      same-host) llmstack router. URL
+#                                      is pinned at install time and
+#                                      re-exported as LLMSTACK_REMOTE_URL.
+COLOR_CODE = {"current": 38, "next": 208, "external": 135}
+
+
+def _user_shell() -> tuple[str, str]:
+    """Return ``(absolute path to shell, basename like ``zsh`` / ``pwsh``)``.
+
+    Resolution lives in :func:`llmstack._platform.default_shell` so the
+    POSIX vs Windows differences (``$SHELL`` vs ``$ComSpec``,
+    ``/bin/bash`` vs ``pwsh.exe`` fallback) stay in one place.
+    """
+    return default_shell()
+
+
+def _llmstack_alias_target() -> str:
+    """Best path to invoke ``llmstack`` from inside the spawned shell.
+
+    Prefers the console-script on ``PATH`` (``pip install`` provides one);
+    falls back to ``python -m llmstack`` so an editable / non-console
+    install still works.
+    """
+    found = shutil.which("llmstack")
+    if found:
+        return found
+    return f"{sys.executable} -m llmstack"
+
+
+def _prompt_label(channel: str, url: str | None) -> str:
+    """Text inside ``[llmstack:...]`` -- ``external`` keeps the URL visible."""
+    if channel == "external" and url:
+        return f"{channel} {url}"
+    return channel
+
+
+def _write_bash_rcfile(rcfile: Path, channel: str, color: int, alias_target: str, label: str) -> None:
+    rcfile.write_text(
+        "# AUTO-GENERATED by llmstack; sourced by the spawned subshell.\n"
+        '[ -f "$HOME/.bashrc" ] && source "$HOME/.bashrc"\n'
+        f"alias llmstack='{alias_target}'\n"
+        f'PS1="\\[\\033[38;5;{color}m\\][llmstack:{label}]\\[\\033[0m\\] ${{PS1:-\\$ }}"\n'
+    )
+
+
+def _write_zsh_rcfile(zdotdir: Path, channel: str, color: int, alias_target: str, label: str) -> None:
+    zdotdir.mkdir(parents=True, exist_ok=True)
+    (zdotdir / ".zshrc").write_text(
+        "# AUTO-GENERATED by llmstack; sourced by the spawned subshell.\n"
+        '[ -f "$HOME/.zshrc" ] && source "$HOME/.zshrc"\n'
+        f"alias llmstack='{alias_target}'\n"
+        f'PROMPT="%F{{{color}}}[llmstack:{label}]%f ${{PROMPT:-%# }}"\n'
+    )
+
+
+# --- Windows: PowerShell host file + a tiny cmd batch wrapper -------------
+#
+# PowerShell wants a $PROFILE-shaped script to run on startup; we point
+# the host's ``-NoExit -File`` at our generated profile so the user's
+# normal $PROFILE still runs first, then we layer our prompt + alias on
+# top. cmd.exe gets a much simpler treatment via ``/k`` + a one-shot
+# batch script.
+
+_POWERSHELL_PROFILE_TEMPLATE = """\
+# AUTO-GENERATED by llmstack; loaded by the spawned subshell.
+# Run the user's normal profile first so their aliases survive.
+foreach ($p in @($PROFILE.AllUsersAllHosts, $PROFILE.AllUsersCurrentHost,
+                  $PROFILE.CurrentUserAllHosts, $PROFILE.CurrentUserCurrentHost)) {{
+    if ($p -and (Test-Path $p)) {{ . $p }}
+}}
+
+function global:llmstack {{ {alias_invocation} }}
+
+function global:prompt {{
+    $esc = [char]27
+    Write-Host -NoNewline "${{esc}}[38;5;{color}m[llmstack:{label}]${{esc}}[0m "
+    "PS " + (Get-Location) + "> "
+}}
+"""
+
+
+_CMD_BATCH_TEMPLATE = """\
+@echo off
+REM AUTO-GENERATED by llmstack; loaded by the spawned subshell.
+doskey llmstack={alias_invocation} $*
+prompt [llmstack:{label}] $P$G
+"""
+
+
+def _alias_invocation_powershell(alias_target: str) -> str:
+    """Build the body of the PowerShell ``llmstack`` function."""
+    if alias_target.startswith(sys.executable):
+        # ``python -m llmstack`` -- pass through unchanged, args are forwarded.
+        return f"& '{sys.executable}' -m llmstack @args"
+    return f"& '{alias_target}' @args"
+
+
+def _alias_invocation_cmd(alias_target: str) -> str:
+    """``doskey`` macro body. Quote the executable, strip the args sentinel."""
+    if alias_target.startswith(sys.executable):
+        return f'"{sys.executable}" -m llmstack'
+    return f'"{alias_target}"'
+
+
+def _write_powershell_profile(target: Path, color: int, alias_target: str, label: str) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(_POWERSHELL_PROFILE_TEMPLATE.format(
+        color=color,
+        label=label,
+        alias_invocation=_alias_invocation_powershell(alias_target),
+    ))
+
+
+def _write_cmd_batch(target: Path, alias_target: str, label: str) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(_CMD_BATCH_TEMPLATE.format(
+        label=label,
+        alias_invocation=_alias_invocation_cmd(alias_target),
+    ))
+
+
+def spawn_subshell(channel: str) -> None:
+    """Replace the current process with an interactive shell carrying our env.
+
+    Only invoked by ``start`` when ``LLMSTACK_ACTIVE`` is *not* already
+    set; if a nested invocation does sneak in we still refuse rather
+    than silently stack subshells.
+    """
+    paths = resolve()
+    if not paths.opencode_json.is_file():
+        raise SystemExit(f"missing {paths.opencode_json} (run: llmstack install)")
+
+    if os.environ.get("LLMSTACK_ACTIVE") == "1":
+        print(
+            f"[!] already inside an llmstack-aware shell (channel: "
+            f"{os.environ.get('LLMSTACK_CHANNEL', '?')}); refusing to nest a subshell.",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+
+    user_shell, shell_name = _user_shell()
+    family = shell_family(shell_name)
+    color = COLOR_CODE.get(channel, COLOR_CODE["current"])
+    alias_target = _llmstack_alias_target()
+
+    rurl = remote_url()
+    label = _prompt_label(channel, rurl)
+    print()
+    print(f"[*] entering llmstack subshell (channel: {channel}, shell: {shell_name})")
+    print(f"    OPENCODE_CONFIG -> {paths.opencode_json}")
+    if rurl:
+        print(f"    remote          -> {rurl}")
+    print(f"    alias 'llmstack' -> {alias_target}")
+    if channel == "external":
+        print("    remote daemons keep running on exit; nothing local to stop.")
+    else:
+        print("    daemons keep running on exit; stop them with: llmstack stop")
+    print('    open more terminals: install the activate hook once with')
+    print(f'        eval "$(llmstack activate {shell_name})"')
+    print()
+
+    env = {**os.environ}
+    if family == "bash":
+        rcfile = paths.state_dir / "llmstack.bashrc"
+        _write_bash_rcfile(rcfile, channel, color, alias_target, label)
+        argv = [user_shell, "--rcfile", str(rcfile), "-i"]
+    elif family == "zsh":
+        zdotdir = paths.state_dir / "zdotdir"
+        _write_zsh_rcfile(zdotdir, channel, color, alias_target, label)
+        argv = [user_shell, "-i"]
+        env["ZDOTDIR"] = str(zdotdir)
+    elif family == "powershell":
+        profile = paths.state_dir / "llmstack.profile.ps1"
+        _write_powershell_profile(profile, color, alias_target, label)
+        argv = [
+            user_shell,
+            "-NoLogo",
+            "-NoExit",
+            "-ExecutionPolicy", "Bypass",
+            "-File", str(profile),
+        ]
+    elif family == "cmd":
+        batch = paths.state_dir / "llmstack.cmd"
+        _write_cmd_batch(batch, alias_target, label)
+        argv = [user_shell, "/k", str(batch)]
+    else:
+        # Unknown POSIX-shaped shell -- best-effort: just ``-i``, no prompt.
+        argv = [user_shell, "-i"]
+
+    env.update({
+        "OPENCODE_CONFIG": str(paths.opencode_json),
+        "LLMSTACK_WORK_DIR": str(paths.work_dir),
+        "LLMSTACK_CHANNEL": channel,
+        "LLMSTACK_ACTIVE": "1",
+        "LLMSTACK_ROOT": str(PACKAGE_DIR),
+    })
+    if rurl:
+        env["LLMSTACK_REMOTE_URL"] = rurl
+
+    if IS_WINDOWS:
+        # ``execvpe`` is emulated on Windows and behaves oddly when the
+        # parent is a non-console process; ``subprocess.run`` is more
+        # predictable and lets the user actually exit back to the
+        # parent shell.
+        import subprocess
+        rc = subprocess.run(argv, env=env).returncode
+        raise SystemExit(rc)
+    os.execvpe(argv[0], argv, env)
+
+
+# --- activate hooks -------------------------------------------------------
+
+_ZSH_HOOK = r"""# --- llmstack auto-activation hook (zsh) -----------------------------------
+# Generated by `llmstack activate zsh`. Walks up from $PWD on each
+# directory change to find the nearest .llmstack/opencode.json. Reads the
+# project's channel marker (active-channel, falling back to
+# default-channel) and exports OPENCODE_CONFIG, LLMSTACK_WORK_DIR,
+# LLMSTACK_CHANNEL, and -- when channel == external -- LLMSTACK_REMOTE_URL.
+# LLMSTACK_WORK_DIR is what `llmstack <action>` keys off, so commands work
+# from any subdirectory of an installed project. Reverses everything when
+# you step out.
+#
+# Tool-availability gate: before activating, we verify the tools needed
+# for this channel are present:
+#   - `llmstack` (always required)
+#   - `llama-swap`     (only for local channels: current / next)
+#   - `llama-server` or `llama-cli` (likewise local-only)
+# external-mode projects skip the local-tool checks because llama-swap
+# and llama-server live on the remote. If any required tool is missing
+# we print "folder detected but tool not available" + install hints and
+# DON'T activate -- the env stays clean so opencode keeps using the
+# user's global config until they install the missing piece.
+#
+# Marker file format (one line):
+#   <channel>[ <url>]
+#
+# Prompt colour by channel:
+#   current  -> steel-blue    (local stack, canonical)
+#   next     -> orange        (local stack, queued upgrade)
+#   external -> medium-purple (thin client; URL pinned at install time)
+# In external mode the URL is appended to the prompt label so you always
+# see which router you're talking to: [llmstack:<project> <url>]
+
+_llmstack_find_root() {
+    local dir="${1:-$PWD}"
+    while [[ "$dir" != "/" && -n "$dir" ]]; do
+        if [[ -f "$dir/.llmstack/opencode.json" ]]; then
+            print -r -- "$dir"
+            return 0
+        fi
+        dir="${dir:h}"
+    done
+    return 1
+}
+
+_llmstack_color() {
+    case "${1:-current}" in
+        next)     print -r -- 208 ;;
+        external) print -r -- 135 ;;
+        *)        print -r -- 38  ;;
+    esac
+}
+
+_llmstack_read_marker() {
+    # Read "<channel> [url]" from $1 into _ch / _url. Sets _ch="" on failure.
+    _ch=""; _url=""
+    [[ -f "$1" ]] || return 0
+    read -r _ch _url < "$1" || true
+}
+
+_llmstack_find_swap() {
+    # Mirror of llmstack.paths.bin_dir(): $LLMSTACK_BIN_DIR > $LLMSTACK_DATA_DIR/bin
+    # > $XDG_DATA_HOME/llmstack/bin (default ~/.local/share/llmstack/bin), then PATH.
+    local cands=()
+    [[ -n "${LLMSTACK_BIN_DIR:-}" ]]  && cands+=("$LLMSTACK_BIN_DIR/llama-swap")
+    [[ -n "${LLMSTACK_DATA_DIR:-}" ]] && cands+=("$LLMSTACK_DATA_DIR/bin/llama-swap")
+    cands+=("${XDG_DATA_HOME:-$HOME/.local/share}/llmstack/bin/llama-swap")
+    local p
+    for p in "${cands[@]}"; do
+        [[ -x "$p" ]] && return 0
+    done
+    command -v llama-swap >/dev/null 2>&1
+}
+
+_llmstack_check_tools() {
+    # Populates _llmstack_missing array. Returns 0 iff nothing is missing.
+    _llmstack_missing=()
+    command -v llmstack >/dev/null 2>&1 || _llmstack_missing+=("llmstack")
+    if [[ "${1:-current}" != "external" ]]; then
+        _llmstack_find_swap || _llmstack_missing+=("llama-swap")
+        if ! command -v llama-server >/dev/null 2>&1 && ! command -v llama-cli >/dev/null 2>&1; then
+            _llmstack_missing+=("llama-server")
+        fi
+    fi
+    (( ${#_llmstack_missing[@]} == 0 ))
+}
+
+_llmstack_install_hint() {
+    case "$1" in
+        llmstack)     print -r -- "      llmstack       pip install -e <repo>   (or: pipx install llmstack)" ;;
+        llama-swap)   print -r -- "      llama-swap     llmstack install-llama-swap" ;;
+        llama-server) print -r -- "      llama-server   brew install llama.cpp  (or download from https://github.com/ggml-org/llama.cpp/releases)" ;;
+    esac
+}
+
+_llmstack_warn_missing() {
+    # $1 = project root; uses _llmstack_missing.
+    print -r -- ""
+    print -P -- "%F{220}[llmstack]%f detected $1/.llmstack but missing local tool(s):"
+    local t
+    for t in "${_llmstack_missing[@]}"; do
+        _llmstack_install_hint "$t"
+    done
+    print -r -- "    not activating. install the missing tool(s) and \`cd\` back in to retry."
+    print -r -- ""
+}
+
+_llmstack_deactivate() {
+    if [[ -n "${LLMSTACK_WORK_DIR:-}" ]]; then
+        unset OPENCODE_CONFIG LLMSTACK_WORK_DIR LLMSTACK_ACTIVE LLMSTACK_CHANNEL LLMSTACK_REMOTE_URL
+        if [[ -n "${_LLMSTACK_PS1_BACKUP:-}" ]]; then
+            PROMPT="$_LLMSTACK_PS1_BACKUP"
+            unset _LLMSTACK_PS1_BACKUP
+        fi
+    fi
+    unset _LLMSTACK_WARNED_FOR
+}
+
+_llmstack_activate() {
+    local found
+    found="$(_llmstack_find_root)" || found=""
+
+    if [[ -z "$found" ]]; then
+        _llmstack_deactivate
+        return 0
+    fi
+    # Idempotency guards: same project, no re-work.
+    if [[ "${LLMSTACK_WORK_DIR:-}" == "$found" ]]; then
+        return 0
+    fi
+    if [[ "${_LLMSTACK_WARNED_FOR:-}" == "$found" ]]; then
+        return 0
+    fi
+    # Switching projects (or entering fresh) -- drop any prior activation first.
+    _llmstack_deactivate
+
+    local _ch _url
+    # Channel resolution: live (active-channel, written by `start`)
+    # > intent (default-channel, written by `install`) > "current".
+    if [[ -f "$found/.llmstack/active-channel" ]]; then
+        _llmstack_read_marker "$found/.llmstack/active-channel"
+    else
+        _llmstack_read_marker "$found/.llmstack/default-channel"
+    fi
+    : "${_ch:=current}"
+
+    # Tool gate -- bail before exporting anything if requirements aren't met.
+    if ! _llmstack_check_tools "$_ch"; then
+        _llmstack_warn_missing "$found"
+        export _LLMSTACK_WARNED_FOR="$found"
+        return 0
+    fi
+
+    export OPENCODE_CONFIG="$found/.llmstack/opencode.json"
+    export LLMSTACK_WORK_DIR="$found"
+    export LLMSTACK_ACTIVE="1"
+    export LLMSTACK_CHANNEL="$_ch"
+    if [[ "$_ch" == "external" && -n "$_url" ]]; then
+        export LLMSTACK_REMOTE_URL="$_url"
+    else
+        unset LLMSTACK_REMOTE_URL
+    fi
+
+    : "${_LLMSTACK_PS1_BACKUP:=$PROMPT}"
+    export _LLMSTACK_PS1_BACKUP
+    local label color suffix
+    label="${found:t}"
+    color="$(_llmstack_color "$_ch")"
+    if [[ "$_ch" == "external" && -n "$_url" ]]; then
+        suffix=" $_url"
+    else
+        suffix=""
+    fi
+    PROMPT="%F{${color}}[llmstack:${label}${suffix}]%f $_LLMSTACK_PS1_BACKUP"
+}
+
+# Hook on every directory change AND once for the current shell.
+autoload -U add-zsh-hook
+add-zsh-hook chpwd _llmstack_activate
+_llmstack_activate
+# --- end llmstack hook -----------------------------------------------------
+"""
+
+_BASH_HOOK = r"""# --- llmstack auto-activation hook (bash) ----------------------------------
+# Generated by `llmstack activate bash`. Walks up from $PWD on each prompt
+# to find the nearest .llmstack/opencode.json. Reads the project's channel
+# marker (active-channel, falling back to default-channel) and exports
+# OPENCODE_CONFIG, LLMSTACK_WORK_DIR, LLMSTACK_CHANNEL, and -- when
+# channel == external -- LLMSTACK_REMOTE_URL. LLMSTACK_WORK_DIR is what
+# `llmstack <action>` keys off, so commands work from any subdirectory of
+# an installed project. Reverses everything when you step out.
+#
+# Tool-availability gate: before activating we verify the tools needed
+# for this channel are present:
+#   - `llmstack` (always required)
+#   - `llama-swap`     (only for local channels: current / next)
+#   - `llama-server` or `llama-cli` (likewise local-only)
+# If any required tool is missing we print a one-shot "folder detected
+# but tool not available" warning + install hints and DON'T activate
+# (env stays clean). The warning is suppressed on subsequent prompts in
+# the same project via the _LLMSTACK_WARNED_FOR guard so we don't spam
+# every PROMPT_COMMAND tick.
+#
+# Marker file format (one line):
+#   <channel>[ <url>]
+#
+# Prompt colour by channel:
+#   current  -> steel-blue    (local stack, canonical)
+#   next     -> orange        (local stack, queued upgrade)
+#   external -> medium-purple (thin client; URL pinned at install time)
+# In external mode the URL is appended to the prompt label so you always
+# see which router you're talking to: [llmstack:<project> <url>]
+
+_llmstack_find_root() {
+    local dir="${1:-$PWD}"
+    while [[ "$dir" != "/" && -n "$dir" ]]; do
+        if [[ -f "$dir/.llmstack/opencode.json" ]]; then
+            printf '%s\n' "$dir"
+            return 0
+        fi
+        dir="$(dirname "$dir")"
+    done
+    return 1
+}
+
+_llmstack_color() {
+    case "${1:-current}" in
+        next)     printf '%s' 208 ;;
+        external) printf '%s' 135 ;;
+        *)        printf '%s' 38  ;;
+    esac
+}
+
+_llmstack_read_marker() {
+    _ch=""; _url=""
+    [[ -f "$1" ]] || return 0
+    read -r _ch _url < "$1" || true
+}
+
+_llmstack_find_swap() {
+    # Mirror of llmstack.paths.bin_dir(): $LLMSTACK_BIN_DIR > $LLMSTACK_DATA_DIR/bin
+    # > $XDG_DATA_HOME/llmstack/bin (default ~/.local/share/llmstack/bin), then PATH.
+    local cands=()
+    [[ -n "${LLMSTACK_BIN_DIR:-}" ]]  && cands+=("$LLMSTACK_BIN_DIR/llama-swap")
+    [[ -n "${LLMSTACK_DATA_DIR:-}" ]] && cands+=("$LLMSTACK_DATA_DIR/bin/llama-swap")
+    cands+=("${XDG_DATA_HOME:-$HOME/.local/share}/llmstack/bin/llama-swap")
+    local p
+    for p in "${cands[@]}"; do
+        [[ -x "$p" ]] && return 0
+    done
+    command -v llama-swap >/dev/null 2>&1
+}
+
+_llmstack_check_tools() {
+    _llmstack_missing=()
+    command -v llmstack >/dev/null 2>&1 || _llmstack_missing+=("llmstack")
+    if [[ "${1:-current}" != "external" ]]; then
+        _llmstack_find_swap || _llmstack_missing+=("llama-swap")
+        if ! command -v llama-server >/dev/null 2>&1 && ! command -v llama-cli >/dev/null 2>&1; then
+            _llmstack_missing+=("llama-server")
+        fi
+    fi
+    [[ ${#_llmstack_missing[@]} -eq 0 ]]
+}
+
+_llmstack_install_hint() {
+    case "$1" in
+        llmstack)     printf '%s\n' "      llmstack       pip install -e <repo>   (or: pipx install llmstack)" ;;
+        llama-swap)   printf '%s\n' "      llama-swap     llmstack install-llama-swap" ;;
+        llama-server) printf '%s\n' "      llama-server   brew install llama.cpp  (or download from https://github.com/ggml-org/llama.cpp/releases)" ;;
+    esac
+}
+
+_llmstack_warn_missing() {
+    printf '\n'
+    printf '\033[38;5;220m[llmstack]\033[0m detected %s/.llmstack but missing local tool(s):\n' "$1"
+    local t
+    for t in "${_llmstack_missing[@]}"; do
+        _llmstack_install_hint "$t"
+    done
+    printf '    not activating. install the missing tool(s) and `cd` back in to retry.\n\n'
+}
+
+_llmstack_deactivate() {
+    if [[ -n "${LLMSTACK_WORK_DIR:-}" ]]; then
+        unset OPENCODE_CONFIG LLMSTACK_WORK_DIR LLMSTACK_ACTIVE LLMSTACK_CHANNEL LLMSTACK_REMOTE_URL
+        if [[ -n "${_LLMSTACK_PS1_BACKUP:-}" ]]; then
+            PS1="$_LLMSTACK_PS1_BACKUP"
+            unset _LLMSTACK_PS1_BACKUP
+        fi
+    fi
+    unset _LLMSTACK_WARNED_FOR
+}
+
+_llmstack_activate() {
+    local found
+    found="$(_llmstack_find_root)" || found=""
+
+    if [[ -z "$found" ]]; then
+        _llmstack_deactivate
+        return 0
+    fi
+    if [[ "${LLMSTACK_WORK_DIR:-}" == "$found" ]]; then
+        return 0
+    fi
+    if [[ "${_LLMSTACK_WARNED_FOR:-}" == "$found" ]]; then
+        return 0
+    fi
+    _llmstack_deactivate
+
+    local _ch _url
+    if [[ -f "$found/.llmstack/active-channel" ]]; then
+        _llmstack_read_marker "$found/.llmstack/active-channel"
+    else
+        _llmstack_read_marker "$found/.llmstack/default-channel"
+    fi
+    : "${_ch:=current}"
+
+    if ! _llmstack_check_tools "$_ch"; then
+        _llmstack_warn_missing "$found"
+        export _LLMSTACK_WARNED_FOR="$found"
+        return 0
+    fi
+
+    export OPENCODE_CONFIG="$found/.llmstack/opencode.json"
+    export LLMSTACK_WORK_DIR="$found"
+    export LLMSTACK_ACTIVE="1"
+    export LLMSTACK_CHANNEL="$_ch"
+    if [[ "$_ch" == "external" && -n "$_url" ]]; then
+        export LLMSTACK_REMOTE_URL="$_url"
+    else
+        unset LLMSTACK_REMOTE_URL
+    fi
+
+    : "${_LLMSTACK_PS1_BACKUP:=$PS1}"
+    export _LLMSTACK_PS1_BACKUP
+    local label color suffix
+    label="$(basename "$found")"
+    color="$(_llmstack_color "$_ch")"
+    if [[ "$_ch" == "external" && -n "$_url" ]]; then
+        suffix=" $_url"
+    else
+        suffix=""
+    fi
+    PS1="\[\033[38;5;${color}m\][llmstack:${label}${suffix}]\[\033[0m\] $_LLMSTACK_PS1_BACKUP"
+}
+
+# Bash has no chpwd hook, so we run on every prompt. Idempotent: the
+# guards above (LLMSTACK_WORK_DIR or _LLMSTACK_WARNED_FOR matching
+# $found) make repeated calls a no-op.
+case ";${PROMPT_COMMAND:-};" in
+    *";_llmstack_activate;"*) ;;
+    *) PROMPT_COMMAND="_llmstack_activate;${PROMPT_COMMAND:-}" ;;
+esac
+_llmstack_activate
+# --- end llmstack hook -----------------------------------------------------
+"""
+
+
+_POWERSHELL_HOOK = r"""# --- llmstack auto-activation hook (PowerShell) ----------------------------
+# Generated by `llmstack activate powershell`. Walks up from $PWD on each
+# prompt to find the nearest .llmstack/opencode.json. Reads the project's
+# channel marker (active-channel, falling back to default-channel) and
+# exports OPENCODE_CONFIG, LLMSTACK_WORK_DIR, LLMSTACK_CHANNEL, and --
+# when channel == external -- LLMSTACK_REMOTE_URL. LLMSTACK_WORK_DIR is
+# what `llmstack <action>` keys off, so commands work from any
+# subdirectory of an installed project. Reverses everything when you cd
+# out of the project.
+#
+# Tool-availability gate: before activating we verify the tools needed
+# for this channel are present:
+#   - llmstack (always required)
+#   - llama-swap (only for local channels: current / next)
+#   - llama-server or llama-cli (likewise local-only)
+# If any required tool is missing we print a one-shot warning + install
+# hints and DON'T activate. The _LLMSTACK_WARNED_FOR guard suppresses
+# the warning on subsequent prompts in the same project.
+#
+# Add to your $PROFILE (one time):
+#     llmstack activate powershell | Out-String | Invoke-Expression
+# or, to persist across sessions:
+#     "Invoke-Expression (& llmstack activate powershell | Out-String)" | Add-Content $PROFILE
+#
+# Marker file format (one line):
+#   <channel>[ <url>]
+#
+# Prompt colour by channel:
+#   current  -> steel-blue    (38)
+#   next     -> orange        (208)
+#   external -> medium-purple (135)
+
+function global:_LlmstackFindRoot {
+    param([string]$Start = (Get-Location).Path)
+    $dir = $Start
+    while ($dir -and (Test-Path $dir)) {
+        if (Test-Path -LiteralPath (Join-Path $dir ".llmstack/opencode.json")) {
+            return $dir
+        }
+        $parent = Split-Path -Parent $dir
+        if ($parent -eq $dir) { break }
+        $dir = $parent
+    }
+    return $null
+}
+
+function global:_LlmstackChannelColor {
+    param([string]$Channel)
+    switch ($Channel) {
+        "next"     { 208 }
+        "external" { 135 }
+        default    { 38  }
+    }
+}
+
+function global:_LlmstackReadMarker {
+    param([string]$Path)
+    if (-not (Test-Path -LiteralPath $Path)) { return @{ channel = ""; url = "" } }
+    $line = (Get-Content -LiteralPath $Path -TotalCount 1) -as [string]
+    if (-not $line) { return @{ channel = ""; url = "" } }
+    $parts = $line.Trim() -split '\s+', 2
+    return @{
+        channel = $parts[0]
+        url     = if ($parts.Length -gt 1) { $parts[1] } else { "" }
+    }
+}
+
+function global:_LlmstackFindSwap {
+    # Mirror of llmstack.paths.bin_dir(): $LLMSTACK_BIN_DIR > $LLMSTACK_DATA_DIR\bin
+    # > $LOCALAPPDATA\llmstack\bin (Windows) or $XDG_DATA_HOME/llmstack/bin (POSIX),
+    # then PATH.
+    $cands = @()
+    if ($env:LLMSTACK_BIN_DIR)  { $cands += (Join-Path $env:LLMSTACK_BIN_DIR  "llama-swap.exe") }
+    if ($env:LLMSTACK_DATA_DIR) { $cands += (Join-Path $env:LLMSTACK_DATA_DIR "bin\llama-swap.exe") }
+    if ($env:LOCALAPPDATA)      { $cands += (Join-Path $env:LOCALAPPDATA      "llmstack\bin\llama-swap.exe") }
+    if ($env:XDG_DATA_HOME)     { $cands += (Join-Path $env:XDG_DATA_HOME     "llmstack/bin/llama-swap") }
+    if ($env:HOME)              { $cands += (Join-Path $env:HOME              ".local/share/llmstack/bin/llama-swap") }
+    foreach ($p in $cands) {
+        if (Test-Path -LiteralPath $p) { return $true }
+    }
+    return [bool](Get-Command llama-swap -ErrorAction SilentlyContinue)
+}
+
+function global:_LlmstackCheckTools {
+    param([string]$Channel)
+    $missing = @()
+    if (-not (Get-Command llmstack -ErrorAction SilentlyContinue)) { $missing += "llmstack" }
+    if ($Channel -ne "external") {
+        if (-not (_LlmstackFindSwap)) { $missing += "llama-swap" }
+        if (-not (Get-Command llama-server -ErrorAction SilentlyContinue) -and `
+            -not (Get-Command llama-cli    -ErrorAction SilentlyContinue)) {
+            $missing += "llama-server"
+        }
+    }
+    return ,$missing
+}
+
+function global:_LlmstackInstallHint {
+    param([string]$Tool)
+    switch ($Tool) {
+        "llmstack"     { "      llmstack       pip install -e <repo>   (or: pipx install llmstack)" }
+        "llama-swap"   { "      llama-swap     llmstack install-llama-swap" }
+        "llama-server" { "      llama-server   download from https://github.com/ggml-org/llama.cpp/releases" }
+    }
+}
+
+function global:_LlmstackWarnMissing {
+    param([string]$Found, [string[]]$Missing)
+    Write-Host ""
+    $esc = [char]27
+    Write-Host -NoNewline "${esc}[38;5;220m[llmstack]${esc}[0m "
+    Write-Host "detected $Found\.llmstack but missing local tool(s):"
+    foreach ($t in $Missing) { Write-Host (_LlmstackInstallHint $t) }
+    Write-Host "    not activating. install the missing tool(s) and cd back in to retry."
+    Write-Host ""
+}
+
+function global:_LlmstackDeactivate {
+    if ($env:LLMSTACK_WORK_DIR) {
+        Remove-Item Env:OPENCODE_CONFIG     -ErrorAction SilentlyContinue
+        Remove-Item Env:LLMSTACK_WORK_DIR   -ErrorAction SilentlyContinue
+        Remove-Item Env:LLMSTACK_ACTIVE     -ErrorAction SilentlyContinue
+        Remove-Item Env:LLMSTACK_CHANNEL    -ErrorAction SilentlyContinue
+        Remove-Item Env:LLMSTACK_REMOTE_URL -ErrorAction SilentlyContinue
+        $global:_LLMSTACK_PROMPT_ON = $false
+    }
+    Remove-Item Env:_LLMSTACK_WARNED_FOR -ErrorAction SilentlyContinue
+}
+
+function global:_LlmstackActivate {
+    $found = _LlmstackFindRoot
+    if (-not $found) {
+        _LlmstackDeactivate
+        return
+    }
+    if ($env:LLMSTACK_WORK_DIR -eq $found) { return }
+    if ($env:_LLMSTACK_WARNED_FOR -eq $found) { return }
+
+    _LlmstackDeactivate
+
+    $live    = Join-Path $found ".llmstack/active-channel"
+    $intent  = Join-Path $found ".llmstack/default-channel"
+    $marker  = if (Test-Path -LiteralPath $live) { _LlmstackReadMarker $live } else { _LlmstackReadMarker $intent }
+    $channel = if ($marker.channel) { $marker.channel } else { "current" }
+
+    $missing = _LlmstackCheckTools $channel
+    if ($missing.Count -gt 0) {
+        _LlmstackWarnMissing $found $missing
+        $env:_LLMSTACK_WARNED_FOR = $found
+        return
+    }
+
+    $env:OPENCODE_CONFIG   = Join-Path $found ".llmstack/opencode.json"
+    $env:LLMSTACK_WORK_DIR = $found
+    $env:LLMSTACK_ACTIVE   = "1"
+    $env:LLMSTACK_CHANNEL  = $channel
+    if ($channel -eq "external" -and $marker.url) {
+        $env:LLMSTACK_REMOTE_URL = $marker.url
+    } else {
+        Remove-Item Env:LLMSTACK_REMOTE_URL -ErrorAction SilentlyContinue
+    }
+
+    $global:_LLMSTACK_PROMPT_COLOR  = _LlmstackChannelColor $channel
+    $global:_LLMSTACK_PROMPT_LABEL  = Split-Path $found -Leaf
+    $global:_LLMSTACK_PROMPT_SUFFIX = if ($channel -eq "external" -and $marker.url) { " " + $marker.url } else { "" }
+    $global:_LLMSTACK_PROMPT_ON     = $true
+}
+
+# Wrap the existing prompt once so every prompt cycle re-runs the
+# activator and (when inside a project) prefixes the prompt. Idempotent
+# via the _LLMSTACK_PROMPT_WRAPPED guard.
+if (-not (Get-Variable -Name _LLMSTACK_PROMPT_WRAPPED -Scope Global -ErrorAction SilentlyContinue)) {
+    $global:_LLMSTACK_PROMPT_WRAPPED = $true
+    $global:_LLMSTACK_ORIG_PROMPT = (Get-Item Function:prompt).ScriptBlock
+    function global:prompt {
+        _LlmstackActivate
+        if ($global:_LLMSTACK_PROMPT_ON) {
+            $esc = [char]27
+            $color  = $global:_LLMSTACK_PROMPT_COLOR
+            $label  = $global:_LLMSTACK_PROMPT_LABEL
+            $suffix = $global:_LLMSTACK_PROMPT_SUFFIX
+            Write-Host -NoNewline "$esc[38;5;${color}m[llmstack:$label$suffix]$esc[0m "
+        }
+        & $global:_LLMSTACK_ORIG_PROMPT
+    }
+}
+_LlmstackActivate
+# --- end llmstack hook -----------------------------------------------------
+"""
+
+
+def activate_hook(shell: str) -> str:
+    """Return the shell-rc snippet for ``shell``.
+
+    Supported: ``zsh``, ``bash``, ``powershell`` / ``pwsh``.
+    """
+    if shell == "zsh":
+        return _ZSH_HOOK
+    if shell == "bash":
+        return _BASH_HOOK
+    if shell in ("powershell", "pwsh"):
+        return _POWERSHELL_HOOK
+    raise SystemExit(
+        f"activate: unknown shell '{shell}' (supported: zsh, bash, powershell)"
+    )
+
+
+# --- in-shell channel/prompt refresh -------------------------------------
+#
+# Used by ``llmstack reload`` (and pointed at by ``start`` when it
+# detects a channel switch inside an already-active shell). The activate
+# hook normally re-evaluates env + PROMPT on every chpwd / prompt cycle,
+# but a mid-shell `start --next` doesn't trigger that, so the prompt
+# would otherwise stay on the old channel until the next cd. This
+# function emits shell commands the user pipes through ``eval`` to apply
+# the channel switch in-place, no nested subshell.
+#
+# We mirror the activate hook's PS1 format so the prompt looks identical
+# to a fresh chpwd-driven re-render. ``_LLMSTACK_PS1_BACKUP`` is set by
+# the hook on first activation; if it isn't (the user never sourced the
+# hook, e.g. inside a ``start``-spawned subshell), we fall back to the
+# current PROMPT/PS1 so we don't clobber their setup.
+
+
+def _refresh_zsh(channel: str, color: int, label: str, project: str) -> None:
+    print(f'export LLMSTACK_CHANNEL="{channel}"')
+    rurl = remote_url()
+    if channel == "external" and rurl:
+        print(f'export LLMSTACK_REMOTE_URL="{rurl}"')
+    else:
+        print("unset LLMSTACK_REMOTE_URL")
+    suffix = f" {rurl}" if (channel == "external" and rurl) else ""
+    print(
+        f'PROMPT="%F{{{color}}}[llmstack:{project}{suffix}]%f '
+        f'${{_LLMSTACK_PS1_BACKUP:-$PROMPT}}"'
+    )
+    # Update LLMSTACK_WORK_DIR even though work_dir doesn't change here --
+    # if the user reloaded outside any cd-driven activation it ensures
+    # downstream commands see a consistent env.
+    print(f'export LLMSTACK_WORK_DIR="{label}"')
+    print('export LLMSTACK_ACTIVE="1"')
+
+
+def _refresh_bash(channel: str, color: int, label: str, project: str) -> None:
+    print(f'export LLMSTACK_CHANNEL="{channel}"')
+    rurl = remote_url()
+    if channel == "external" and rurl:
+        print(f'export LLMSTACK_REMOTE_URL="{rurl}"')
+    else:
+        print("unset LLMSTACK_REMOTE_URL")
+    suffix = f" {rurl}" if (channel == "external" and rurl) else ""
+    print(
+        f'PS1="\\[\\033[38;5;{color}m\\][llmstack:{project}{suffix}]\\[\\033[0m\\] '
+        f'${{_LLMSTACK_PS1_BACKUP:-$PS1}}"'
+    )
+    print(f'export LLMSTACK_WORK_DIR="{label}"')
+    print('export LLMSTACK_ACTIVE="1"')
+
+
+def _refresh_powershell(channel: str, color: int, label: str, project: str) -> None:
+    print(f'$env:LLMSTACK_CHANNEL = "{channel}"')
+    rurl = remote_url()
+    if channel == "external" and rurl:
+        print(f'$env:LLMSTACK_REMOTE_URL = "{rurl}"')
+    else:
+        print("Remove-Item Env:LLMSTACK_REMOTE_URL -ErrorAction SilentlyContinue")
+    suffix = f" {rurl}" if (channel == "external" and rurl) else ""
+    # Powershell's prompt() wrapper from the activate hook reads these
+    # globals on each render; setting them here is enough.
+    print(f"$global:_LLMSTACK_PROMPT_COLOR = {color}")
+    print(f'$global:_LLMSTACK_PROMPT_LABEL = "{project}"')
+    print(f'$global:_LLMSTACK_PROMPT_SUFFIX = "{suffix}"')
+    print("$global:_LLMSTACK_PROMPT_ON = $true")
+    print(f'$env:LLMSTACK_WORK_DIR = "{label}"')
+    print('$env:LLMSTACK_ACTIVE = "1"')
+
+
+def emit_shell_refresh(channel: str) -> None:
+    """Print eval-able shell commands that apply ``channel`` to the
+    current interactive shell (env exports + PS1 update).
+
+    Detects the user's shell family via ``$SHELL`` and dispatches to a
+    family-specific emitter; ``cmd.exe`` only gets env exports because
+    its prompt model can't be redefined cleanly mid-session.
+
+    Output goes to ``sys.stdout`` so callers piped through ``eval`` /
+    ``Invoke-Expression`` apply the change in-place. All other output
+    (errors, hints) should go to ``stderr`` to keep stdout
+    eval-clean.
+    """
+    paths = resolve()
+    _, shell_name = _user_shell()
+    family = shell_family(shell_name)
+    color = COLOR_CODE.get(channel, COLOR_CODE["current"])
+    project = paths.work_dir.name
+    work_dir_str = str(paths.work_dir)
+
+    if family == "zsh":
+        _refresh_zsh(channel, color, work_dir_str, project)
+    elif family == "bash":
+        _refresh_bash(channel, color, work_dir_str, project)
+    elif family == "powershell":
+        _refresh_powershell(channel, color, work_dir_str, project)
+    elif family == "cmd":
+        # cmd.exe: env-only; the doskey-driven prompt from spawn_subshell
+        # isn't reachable from outside that one-shot session.
+        print(f'set "LLMSTACK_CHANNEL={channel}"')
+        rurl = remote_url()
+        if channel == "external" and rurl:
+            print(f'set "LLMSTACK_REMOTE_URL={rurl}"')
+        else:
+            print('set "LLMSTACK_REMOTE_URL="')
+        print(f'set "LLMSTACK_WORK_DIR={work_dir_str}"')
+        print('set "LLMSTACK_ACTIVE=1"')
+    else:
+        # Unknown shell -- emit POSIX-shaped exports so something useful
+        # comes out, but skip the prompt update.
+        print(f'export LLMSTACK_CHANNEL="{channel}"')
+        print(f'export LLMSTACK_WORK_DIR="{work_dir_str}"')