superlocalmemory 4.1.20 → 4.1.22

package/plugin/cursor-skills/slm-session/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: slm-session
+description: Manage SuperLocalMemory session lifecycle — call session_init once at the start of every fresh session to load relevant project context and get a session_id; call close_session when work is meaningfully complete to commit temporal summaries. Correct lifecycle hygiene is what makes SLM's learning loop work.
+when_to_use: |
+  - At the start of every session (auto-trigger on first user message in a project context)
+  - When the user says "start a new session" or "initialize memory"
+  - When meaningful work completes and context should be committed
+  - When the user says "close session" or "end session"
+allowed-tools: session_init, close_session, Bash
+---
+
+# slm-session — Session Lifecycle Hygiene
+
+Session lifecycle is the mechanism that makes SuperLocalMemory's learning loop
+work. Without it, recall signals are not attributed and temporal summaries are
+not written. This is not optional housekeeping — it is load-bearing.
+
+---
+
+## The lifecycle in one diagram
+
+```
+Session starts
+     |
+     v
+session_init(project_path, query)
+     |--- returns session_id, context, memories
+     |
+     v
+Use session_id in every recall() and remember() call
+     |
+     v
+Work completes
+     |
+     v
+close_session(session_id)
+     |--- writes temporal summaries to DB
+```
+
+---
+
+## session_init — call once per fresh session
+
+### When to call
+
+Call `session_init` exactly once at the start of every fresh session, before
+any `recall` or `remember`. Never call it twice in a session — the second call
+would generate a new `session_id` and break signal attribution for any prior
+recalls or remembers in that session.
+
+### Signature
+
+```
+session_init(
+  project_path: str = "",  # working directory path, e.g. "~/projects/foo"
+  query: str = "",         # topic override; if omitted, derived from project_path
+  max_results: int = 10,   # max memories to return (default: 10)
+  max_age_days: int = 30,  # suppress memories older than N days unless score >= 0.7
+                           # set to 0 to disable the age gate entirely
+)
+```
+
+### What it does
+
+1. Derives a search query from `project_path` (or uses your explicit `query`).
+2. Runs a 2-tier recall: full daemon retrieval (primary) or FTS5 BM25
+   (emergency fallback if daemon is unreachable).
+3. Merges any pinned "core memory" facts with the recall results.
+4. Applies an age gate — memories older than `max_age_days` are suppressed
+   unless their relevance score is 0.70 or above (architectural decisions that
+   remain permanently relevant still surface).
+5. Returns a pre-formatted `context` block and a structured `memories` array
+   for your session.
+6. Generates a stable `session_id` (`slm-YYYYMMDD-<8hex>`) and returns it.
+
+### Real response shape
+
+```json
+{
+  "success": true,
+  "session_id": "slm-20260616-a3f8c1d2",
+  "context": "# Relevant Memory Context\n\n- JWT tokens use 1h expiry ...",
+  "memories": [
+    {
+      "fact_id": "f8a2bc91",
+      "content": "JWT tokens use 1h expiry for API auth (2026-06-10)",
+      "score": 0.87,
+      "is_core": false
+    }
+  ],
+  "memory_count": 3,
+  "core_memory": [],
+  "degraded_mode": false,
+  "retrieval_mode": "full_6_channel",
+  "calibration_status": "uncalibrated",
+  "calibration_id": null,
+  "answer_confidence": null,
+  "abstained": false,
+  "abstention_reason": null,
+  "learning": {
+    "feedback_signals": 37,
+    "phase": 1,
+    "status": "collecting"
+  }
+}
+```
+
+**Check `degraded_mode`.** When `true`, the daemon was unreachable and only
+FTS5 BM25 was used — semantic, graph, temporal, and structural channels were
+unavailable. The context is still usable; note the degradation if relevant.
+
+**Check `abstained`.** If `true`, the memories returned in `context` and
+`memories` do not answer the query that seeded this session — say so, or
+ask, rather than presenting them as settled fact. This is most relevant
+when you passed an explicit `query`; the default project-context query
+rarely has a single "right answer" for a judge to evaluate.
+`answer_confidence` is a measurement, not a guarantee. `calibration_status:
+"uncalibrated"` means no judge is configured, and `abstained` then only
+reflects the older "nothing found" signal. See `slm-recall` for the full
+rule, which applies identically here.
+
+**Check `learning.phase`:**
+- Phase 1 (< 50 signals): collecting baseline feedback
+- Phase 2 (50–199 signals): active learning
+- Phase 3 (≥ 200 signals): full ML-driven ranking
+
+### How to use the returned session_id
+
+Store it and thread it into every `recall` and `remember` call in this session:
+
+```
+session_id = "<value from session_init>"
+
+recall(query="auth strategy", session_id=session_id, limit=10)
+remember(content="...", session_id=session_id, tags="auth,decision", project="myapp")
+```
+
+This attribution is what allows the ranker to learn which recalls led to useful
+outcomes for this project. It also gives the session a small working set, so
+successive recalls in one conversation build on what the earlier ones surfaced
+instead of each starting cold.
+
+**Do not synthesise a session id.** An id beginning `http:`, `mcp:`, `cli:` or
+`probe:` is read as a synthetic per-request label rather than a conversation and
+is deliberately excluded from that working set. Use the one `session_init`
+returned, unchanged, for the whole session.
+
+---
+
+## close_session — call when work is meaningfully complete
+
+### When to call
+
+Call `close_session` when a meaningful unit of work is done — end of a coding
+session, after shipping a feature, after a design review. You do not need to
+call it after every small interaction. The signal is "this session's work is
+committed and should be summarised."
+
+Do not call it at the start of a new session as a cleanup step — `session_init`
+is the correct opener and it does not require a prior close.
+
+### Signature
+
+```
+close_session(
+  session_id: str = "",  # the session_id from session_init; if omitted,
+                         # the system queries the DB for the most recent session
+)
+```
+
+### What it does
+
+Aggregates facts written during the session into per-entity temporal summary
+events. These summaries enable future queries like "what happened during session
+X?" and contribute to the temporal channel in retrieval.
+
+### Real response shape
+
+```json
+{
+  "success": true,
+  "session_id": "slm-20260616-a3f8c1d2",
+  "summary_events_created": 4
+}
+```
+
+`summary_events_created: 0` is normal for short sessions where no new facts
+were written. It is not an error.
+
+---
+
+## Why this matters
+
+Every `recall` call with a `session_id` enqueues engagement signals — which
+results were shown, which were acted on. The learning ranker processes these
+signals to gradually up-weight channels and facts that prove useful for your
+project. Without `session_id`, signals land on a fallback identifier and are
+never attributed to a project or agent. Over many sessions this compounds:
+projects where lifecycle is respected have measurably better retrieval quality
+than projects where session_init is skipped.
+
+Within a single session it compounds faster. The session's working set holds the
+memories its recalls have already surfaced, and later recalls rank those higher,
+so a long conversation converges on the material it is actually about.
+
+### Closing the loop explicitly
+
+Engagement signals say a memory was *shown*. `report_outcome` says it was
+*right*:
+
+```
+report_outcome(memory_ids="<ids you actually used>", outcome="success")
+```
+
+Send it when a recalled memory changed what you did, and send `failure` when a
+confidently-returned memory turned out to be wrong — that is the only signal
+that stops a stale memory from being promoted. See the `slm-recall` skill.
+
+---
+
+## CLI fallback (when MCP is unavailable)
+
+There are no direct `session_init` or `close_session` CLI subcommands.
+When MCP is unavailable, use `slm status` to check system health and
+`slm recall` / `slm remember` directly. Session attribution will not be
+available in degraded CLI-only mode.
+
+```bash
+slm status [--json]    # check mode, profile, DB size, fact count
+slm doctor [--json]    # preflight check including daemon and embedding worker
+```
+
+---
+
+## Common mistakes
+
+| Mistake | Consequence | Fix |
+|---------|-------------|-----|
+| Calling `session_init` twice in one session | Two session IDs; signals split across them | Call once; store the returned ID |
+| Omitting `session_id` from `recall` / `remember` | No learning attribution, and every turn starts cold | Always pass the stored `session_id` |
+| Inventing a `session_id` such as `mcp:agent` or `http:1234` | Read as synthetic, excluded from the working set | Use the id `session_init` returned |
+| Never reporting an outcome | Ranking cannot tell a useful memory from a merely returned one | `report_outcome` after a recall that changed what you did |
+| Never calling `close_session` | Temporal summaries not written | Call at end of each meaningful work unit |
+| Calling `close_session` without a `session_id` when no prior writes exist | Returns error "No session_id found" | Pass the explicit `session_id` from `session_init` |
+
+---
+
+## Profile context (v3.8.0+)
+
+`session_init` operates on the currently active profile. If you need to start
+a session on a different workspace, call `switch_profile` (requires `code`,
+`full`, or `power` MCP profile) before `session_init`, then call `session_init`
+for that workspace. See `slm-profile` for workspace switching.
+
+The returned `memories` array reflects facts stored in the active profile only.
+To also surface shared or global facts in the initial context, pass the query
+explicitly and call `recall` with `include_global`/`include_shared` after
+`session_init`. See `slm-scope` for the sharing model.
+
+---
+
+## Related skills
+
+- `slm-recall` — multi-channel retrieval during the session
+- `slm-remember` — store durable facts during the session
+- `slm-profile` — workspace isolation and profile switching
+- `slm-scope` — multi-scope sharing model
+
+---
+
+*SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later*

package/plugin/hooks/hooks.json

@@ -6,7 +6,7 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/slm-run\" hook mandate || true",
-            "timeout": 5000
+            "timeout": 5
           }
         ]
       },
@@ -23,7 +23,7 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/slm-run\" hook start || true",
-            "timeout": 15000
+            "timeout": 15
           }
         ]
       }
@@ -35,7 +35,7 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/slm-run\" hook checkpoint || true",
-            "timeout": 5000
+            "timeout": 5
           }
         ]
       },
@@ -45,7 +45,7 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/slm-run\" hook post_tool_outcome || true",
-            "timeout": 5000
+            "timeout": 5
           }
         ]
       }
@@ -56,7 +56,7 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/slm-run\" hook user_prompt_rehash || true",
-            "timeout": 5000
+            "timeout": 5
           }
         ]
       },
@@ -65,7 +65,7 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/slm-run\" hook topic_shift || true",
-            "timeout": 3000
+            "timeout": 3
           }
         ]
       }
@@ -76,12 +76,12 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/slm-run\" hook stop || true",
-            "timeout": 10000
+            "timeout": 10
           },
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/slm-run\" hook stop_outcome || true",
-            "timeout": 10000
+            "timeout": 10
           }
         ]
       }
@@ -93,7 +93,7 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/slm-run\" hook before_web || true",
-            "timeout": 5000
+            "timeout": 5
           }
         ]
       }

package/plugin/mcp.cursor.json

@@ -0,0 +1,23 @@
+{
+  "mcpServers": {
+    "superlocalmemory": {
+      "args": [
+        "--from",
+        "superlocalmemory==4.1.22",
+        "slm",
+        "mcp"
+      ],
+      "command": "uvx",
+      "env": {
+        "SLM_AGENT_ID": "cursor_plugin",
+        "SLM_MAX_EMBEDDING_WORKERS": "1",
+        "SLM_MCP_PROFILE": "core",
+        "SLM_NON_INTERACTIVE": "1",
+        "SLM_RERANKER_ENABLED": "false",
+        "SLM_RERANKER_IDLE_TIMEOUT": "120",
+        "TOKENIZERS_PARALLELISM": "false",
+        "UV_TORCH_BACKEND": "cpu"
+      }
+    }
+  }
+}

package/plugin/requirements-cpu-torch.txt

@@ -0,0 +1,13 @@
+# CPU-only torch pin for the Linux-no-GPU path (ensure-venv.sh).
+#
+# Installed from https://download.pytorch.org/whl/cpu, which publishes the
+# same public version with a `+cpu` local segment — PEP 440 ignores the local
+# segment when matching a bare `==X.Y.Z` specifier, so this satisfies the
+# `torch==X.Y.Z` requirement that requirements.txt pulls in transitively via
+# superlocalmemory, without ever contacting the CUDA-wheel-carrying default
+# index for it.
+#
+# Kept equal to pyproject.toml's `torch==` dependency by
+# tests/test_plugin_src/test_torch_cpu_pin_matches_pyproject.py — bump both
+# together, not just this file.
+torch==2.13.0

package/plugin/requirements.txt

@@ -1 +1 @@
-superlocalmemory==4.1.20
+superlocalmemory==4.1.22

package/plugin/scripts/ensure-venv.sh

@@ -60,18 +60,36 @@ fi
 # Paths
 # ---------------------------------------------------------------------------
 REQ="${CLAUDE_PLUGIN_ROOT}/requirements.txt"
+TORCH_CPU_PIN_FILE="${CLAUDE_PLUGIN_ROOT}/requirements-cpu-torch.txt"
 VENV="${CLAUDE_PLUGIN_DATA}/venv"
 SENTINEL="${CLAUDE_PLUGIN_DATA}/.venv-reqs.sha256"
 VENV_TMP="${CLAUDE_PLUGIN_DATA}/venv.tmp"
 
 # ---------------------------------------------------------------------------
-# Compute sha256 of requirements.txt (cross-platform: prefer sha256sum, fall back to shasum -a 256)
+# Compute sha256 of requirements.txt, and of the CPU-torch pin file when it
+# exists (a pin bump alone must also trigger a rebuild).
+# (cross-platform: prefer sha256sum, fall back to shasum -a 256)
 # ---------------------------------------------------------------------------
+_sha256_of() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "$1" | awk '{print $1}'
+    else
+        shasum -a 256 "$1" | awk '{print $1}'
+    fi
+}
+
 hash_req() {
+    local combined
+    combined="$(_sha256_of "${REQ}")"
+    if [ -f "${TORCH_CPU_PIN_FILE}" ]; then
+        combined="${combined}:$(_sha256_of "${TORCH_CPU_PIN_FILE}")"
+    fi
+    # Fold the (possibly combined) digest down to one hash again so the
+    # sentinel stays a single opaque token either way.
     if command -v sha256sum >/dev/null 2>&1; then
-        sha256sum "${REQ}" | awk '{print $1}'
+        printf '%s' "${combined}" | sha256sum | awk '{print $1}'
     else
-        shasum -a 256 "${REQ}" | awk '{print $1}'
+        printf '%s' "${combined}" | shasum -a 256 | awk '{print $1}'
     fi
 }
 
@@ -108,6 +126,30 @@ python3 -m venv "${VENV_TMP}"
 # Upgrade pip first (prefer binary to avoid source builds)
 "${VENV_TMP}/bin/pip" install --upgrade pip --prefer-binary --quiet
 
+# ---------------------------------------------------------------------------
+# CPU-only torch on CPU-only Linux. Plain PyPI resolution of the
+# `torch==X.Y.Z` requirement that requirements.txt pulls in transitively
+# installs the CUDA build on Linux (torch + triton + ~18 nvidia-* packages,
+# about 2.6 GiB) even when there is no GPU to use it. Pre-installing the
+# pinned version from the official CPU index first means the later
+# `pip install -r requirements.txt` below finds it already satisfied and
+# never touches the CUDA wheels. macOS, Windows, a host with a GPU, and a
+# user who already set SLM_TORCH_BACKEND or their own pip index are all left
+# exactly as before (see torch-cpu-resolve.sh).
+# shellcheck source=torch-cpu-resolve.sh
+. "$(dirname "${BASH_SOURCE[0]}")/torch-cpu-resolve.sh"
+if torch_cpu_should_force; then
+    if TORCH_PIN="$(torch_cpu_pin "${TORCH_CPU_PIN_FILE}")"; then
+        echo "SLM plugin: Linux, no GPU detected — installing ${TORCH_PIN} from ${TORCH_CPU_INDEX_URL} (set SLM_TORCH_BACKEND=cuda to opt out)." >&2
+        "${VENV_TMP}/bin/pip" install \
+            --require-virtualenv \
+            --prefer-binary \
+            --quiet \
+            --index-url "${TORCH_CPU_INDEX_URL}" \
+            "${TORCH_PIN}"
+    fi
+fi
+
 # Install requirements
 "${VENV_TMP}/bin/pip" install \
     --require-virtualenv \

package/plugin/scripts/slm-launch

@@ -25,17 +25,61 @@
 #                      plugin         — require the plugin's own venv
 #                      <path>         — an explicit slm binary (leading ~ expanded)
 #   SLM_DATA_DIR       SLM data dir (default: ~/.superlocalmemory)
-#   CLAUDE_PLUGIN_DATA where a plugin-owned venv lives, when there is one
+#   CLAUDE_PLUGIN_DATA where a plugin-owned venv lives (then CURSOR_PLUGIN_DATA,
+#                      PLUGIN_DATA, then ~/.local/share/superlocalmemory-plugin)
+#   SLM_LAUNCHER_BOOTSTRAP=1  build that venv here when nothing else can run
+#
+# HOSTS THAT DO NOT EXPAND THEIR VARIABLES
+#
+# Some hosts (Grok Bot's plugin computer) pass ${CLAUDE_PLUGIN_ROOT} and
+# ${CLAUDE_PLUGIN_DATA} through literally. So this script finds itself from
+# BASH_SOURCE, and treats any value still containing "${" as unset.
+#
+# Which slm runs, in order: SLM_LAUNCHER; an slm on PATH; the plugin venv, if
+# built; uvx, pinned to this plugin's release (CPU-only torch on Linux); and,
+# only with SLM_LAUNCHER_BOOTSTRAP=1, a plugin venv built on the spot.
+# The daemon is started first and `slm serve start` waits (up to 60 s) for its
+# /health, so the first remember after a cold start is not "daemon unavailable".
 #
 # Deliberately NOT set here: the MCP profile. Which tools a host exposes is the
 # user's decision, and a plugin that narrows it takes away tools they configured.
 
+# Where this script lives. Never from ${CLAUDE_PLUGIN_ROOT}: not every host sets it.
+_slm_self="${BASH_SOURCE[0]}"
+while [ -h "${_slm_self}" ]; do
+    _slm_link="$(readlink "${_slm_self}")"
+    case "${_slm_link}" in
+        /*) _slm_self="${_slm_link}" ;;
+        *)  _slm_self="$(dirname "${_slm_self}")/${_slm_link}" ;;
+    esac
+done
+_SLM_SCRIPTS="$(cd "$(dirname "${_slm_self}")" && pwd)"
+_SLM_PLUGIN_ROOT="$(dirname "${_SLM_SCRIPTS}")"
+
+# A value that is empty, or a placeholder the host never replaced, is not a value.
+_slm_usable() {
+    case "$1" in
+        ''|*'${'*) return 1 ;;
+    esac
+    return 0
+}
+[ -n "${HOME:-}" ] || { HOME="$(cd ~ 2>/dev/null && pwd)"; export HOME; }
+_slm_usable "${SLM_DATA_DIR:-}" || unset SLM_DATA_DIR
+_slm_usable "${SLM_LAUNCHER:-}" || unset SLM_LAUNCHER
+if ! _slm_usable "${CLAUDE_PLUGIN_DATA:-}"; then
+    unset CLAUDE_PLUGIN_DATA
+    for _slm_d in "${CURSOR_PLUGIN_DATA:-}" "${PLUGIN_DATA:-}" \
+                  "${XDG_DATA_HOME:-${HOME}/.local/share}/superlocalmemory-plugin"; do
+        if _slm_usable "${_slm_d}"; then CLAUDE_PLUGIN_DATA="${_slm_d}"; break; fi
+    done
+fi
+
 _SLM_DATA="${SLM_DATA_DIR:-$HOME/.superlocalmemory}"
 
 # Which slm to run is decided in ONE place, shared with the hooks and the venv
 # bootstrap, so the three can never disagree about which install is in play.
 # shellcheck source=slm-resolve.sh
-. "$(dirname "${BASH_SOURCE[0]}")/slm-resolve.sh"
+. "${_SLM_SCRIPTS}/slm-resolve.sh"
 _PLUGIN_BIN="$(slm_plugin_bin)"
 
 # Is a daemon already up for this data dir? If so we join it rather than boot a
@@ -46,10 +90,45 @@ if [ -f "${_SLM_DATA}/daemon.pid" ] \
     _daemon_running=1
 fi
 
-# Start a daemon with the chosen binary unless one is already serving.
+# Start a daemon with the chosen command unless one is already serving.
 _ensure_daemon() {
     [ "${_daemon_running}" -eq 1 ] && return 0
-    "$1" serve start >&2
+    "$@" serve start >&2
+}
+
+# The release this plugin tree ships (requirements.txt is stamped every release).
+_slm_pin() {
+    sed -n 's/^\(superlocalmemory==[0-9][0-9A-Za-z.+!-]*\)[[:space:]]*$/\1/p' \
+        "${_SLM_PLUGIN_ROOT}/requirements.txt" 2>/dev/null | head -n 1
+}
+
+# No installed slm and no plugin venv: run this release through uvx. Returns
+# only when it cannot (no uvx, or no pin); otherwise it becomes the server.
+_slm_run_uvx() {
+    local _pin
+    command -v uvx >/dev/null 2>&1 || return 1
+    _pin="$(_slm_pin)"
+    if [ -z "${_pin}" ]; then
+        echo "SLM plugin: not using uvx: no superlocalmemory pin in ${_SLM_PLUGIN_ROOT}/requirements.txt." >&2
+        return 1
+    fi
+    # PyPI's Linux torch is the CUDA build; macOS and Windows get CPU wheels anyway.
+    if [ "$(uname -s 2>/dev/null)" = "Linux" ]; then
+        export UV_TORCH_BACKEND="${UV_TORCH_BACKEND:-cpu}"
+    fi
+    export TOKENIZERS_PARALLELISM="${TOKENIZERS_PARALLELISM:-false}"
+    echo "SLM plugin: no installed slm; running ${_pin} through uvx (downloaded once, then cached)." >&2
+    _ensure_daemon uvx --from "${_pin}" slm || \
+        echo "SLM plugin: daemon did not start; the MCP server will retry on first use." >&2
+    exec uvx --from "${_pin}" slm mcp
+}
+
+# Opt-in: build the plugin venv now, with the same bootstrap SessionStart runs.
+_slm_bootstrap() {
+    [ "${SLM_LAUNCHER_BOOTSTRAP:-0}" = "1" ] || return 1
+    CLAUDE_PLUGIN_ROOT="${_SLM_PLUGIN_ROOT}" CLAUDE_PLUGIN_DATA="${CLAUDE_PLUGIN_DATA}" \
+        bash "${_SLM_SCRIPTS}/ensure-venv.sh" >&2 || return 1
+    [ -x "${SLM_CHOICE_BIN}" ]
 }
 
 if ! slm_choose; then
@@ -88,12 +167,17 @@ case "${SLM_LAUNCHER:-auto}:${SLM_CHOICE}" in
         ;;
     auto:plugin)
         # No system install. Use the plugin's own venv, once SessionStart has
-        # built it. If it is not there either, say which two things were looked
-        # for, so the fix is obvious.
+        # built it. A host that runs no hooks never builds it: then uvx, then
+        # (opt-in) a venv built here. If none of that works, say what was
+        # looked for, so the fix is obvious.
         if [ "${SLM_CHOICE_READY}" -ne 1 ]; then
-            slm_not_found_message >&2
-            echo >&2
-            exit 1
+            _slm_run_uvx
+            if ! _slm_bootstrap; then
+                slm_not_found_message >&2
+                echo >&2
+                echo "  Or install uv (https://docs.astral.sh/uv/): the plugin then runs SuperLocalMemory through uvx." >&2
+                exit 1
+            fi
         fi
         if ! _ensure_daemon "${SLM_CHOICE_BIN}"; then
             echo "SLM plugin: unable to start the owned daemon; refusing a direct MCP writer." >&2

package/plugin/scripts/torch-cpu-resolve.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# torch-cpu-resolve.sh — should this install force a CPU-only torch wheel?
+#
+# PyPI ships CPU-only torch wheels for macOS and Windows, but on Linux the
+# plain `torch==X.Y.Z` wheel pulls the CUDA runtime plus ~18 nvidia-* packages
+# (triton included) — about 2.6 GiB on a host that may have no GPU at all
+# (reference: https://docs.astral.sh/uv/guides/integration/pytorch/, which
+# documents the same PyPI default for `uv pip`; plain pip resolves the same
+# index). The official CPU-only index is documented at
+# https://pytorch.org/get-started/locally/ as:
+#   pip install torch --index-url https://download.pytorch.org/whl/cpu
+#
+# Sourced by ensure-venv.sh (never run directly). Pure decision logic — makes
+# makes no HTTP request and runs no pip — so it is unit-testable without the 2 GiB
+# download it exists to avoid (tests/test_plugin_src/test_torch_cpu_resolve.sh).
+#
+# Environment (all optional):
+#   SLM_TORCH_BACKEND   cpu  — force the CPU index regardless of GPU detection
+#                        <anything else, e.g. cuda/cu124/auto> — leave pip's
+#                        default resolution alone; the user has already decided
+#   PIP_INDEX_URL / PIP_EXTRA_INDEX_URL — if the user already points pip at
+#                        their own index, this never overrides it
+#
+# Safe under `set -euo pipefail`: every variable read has a default.
+
+TORCH_CPU_INDEX_URL="https://download.pytorch.org/whl/cpu"
+
+# torch_cpu_should_force — exit 0 (true, in bash's backwards convention) when
+# this host should get the CPU-only wheel instead of whatever pip would
+# otherwise pick. False (exit 1) covers: not Linux, a GPU is visible, or the
+# user already steered pip (their own index) or torch (SLM_TORCH_BACKEND set
+# to anything but "cpu") themselves.
+torch_cpu_should_force() {
+    local platform
+    platform="$(uname -s 2>/dev/null || echo unknown)"
+    if [ "${platform}" != "Linux" ]; then
+        # macOS (Darwin) already gets CPU-only wheels from plain PyPI; Windows
+        # too. Nothing to override there.
+        return 1
+    fi
+
+    case "${SLM_TORCH_BACKEND:-}" in
+        cpu)
+            return 0
+            ;;
+        "")
+            : # unset — fall through to auto-detection below
+            ;;
+        *)
+            # cuda / cuXXX / auto / anything else: the user already decided.
+            return 1
+            ;;
+    esac
+
+    if [ -n "${PIP_INDEX_URL:-}" ] || [ -n "${PIP_EXTRA_INDEX_URL:-}" ]; then
+        # The user already pointed pip somewhere specific. Do not fight it.
+        return 1
+    fi
+
+    if command -v nvidia-smi >/dev/null 2>&1; then
+        return 1
+    fi
+    if [ -e /proc/driver/nvidia/version ] || [ -e /dev/nvidia0 ]; then
+        return 1
+    fi
+
+    return 0
+}
+
+# torch_cpu_pin <pin_file> — print the "torch==X.Y.Z" line from pin_file.
+# Returns 1 (and prints nothing) when the file is missing or has no such
+# line: fail-open, so a missing/stale pin file can never block an install
+# that would otherwise succeed — it just means pip falls back to its
+# ordinary resolution (the CUDA wheel on Linux) for this run.
+torch_cpu_pin() {
+    local pin_file="$1"
+    if [ ! -f "${pin_file}" ]; then
+        return 1
+    fi
+    local line
+    line="$(grep -m1 '^torch==' "${pin_file}" 2>/dev/null || true)"
+    if [ -z "${line}" ]; then
+        return 1
+    fi
+    printf '%s\n' "${line}"
+}