algo-cli-runtime 0.14.0__py3-none-any.whl

algo_cli/runtime_qos.py

@@ -0,0 +1,236 @@
+"""Runtime QoS and named log helpers (J6 + J7).
+
+Inspired by macOS launchd ``POSIXSpawnType`` and ``StandardErrorPath``:
+classify tools by expected runtime posture and give each tool a stable log path.
+"""
+from __future__ import annotations
+
+import re
+import threading
+import time
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any, Generic, TypeVar
+
+from .config import CONFIG_DIR
+
+
+class SpawnClass(str, Enum):
+    ADAPTIVE = "adaptive"
+    INTERACTIVE = "interactive"
+    BACKGROUND = "background"
+
+
+@dataclass(frozen=True)
+class RuntimeHint:
+    tool_name: str
+    spawn_class: SpawnClass
+    log_path: str
+    log_suppression: bool
+    reason: str
+    estimated_cost: float
+
+    def to_dict(self) -> dict:
+        return {
+            "tool_name": self.tool_name,
+            "spawn_class": self.spawn_class.value,
+            "log_path": self.log_path,
+            "log_suppression": self.log_suppression,
+            "reason": self.reason,
+            "estimated_cost": self.estimated_cost,
+        }
+
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class ScheduledJob(Generic[T]):
+    key: str
+    payload: T
+    spawn_class: SpawnClass
+    estimated_cost: float
+    enqueued_at: float
+    virtual_finish: float
+    sequence: int
+
+
+class WeightedFairQueue(Generic[T]):
+    """Small deterministic weighted-fair queue with starvation-safe aging."""
+
+    DEFAULT_WEIGHTS = {
+        SpawnClass.INTERACTIVE: 4.0,
+        SpawnClass.ADAPTIVE: 2.0,
+        SpawnClass.BACKGROUND: 1.0,
+    }
+
+    def __init__(
+        self,
+        *,
+        weights: dict[SpawnClass, float] | None = None,
+        aging_rate: float = 0.05,
+    ) -> None:
+        configured = dict(self.DEFAULT_WEIGHTS)
+        configured.update(weights or {})
+        self.weights = {key: max(0.01, float(value)) for key, value in configured.items()}
+        self.aging_rate = max(0.0, float(aging_rate))
+        self._class_finish = {spawn: 0.0 for spawn in SpawnClass}
+        self._jobs: list[ScheduledJob[T]] = []
+        self._sequence = 0
+        self._lock = threading.RLock()
+
+    def enqueue(
+        self,
+        key: str,
+        payload: T,
+        spawn_class: SpawnClass,
+        *,
+        estimated_cost: float = 1.0,
+        now: float | None = None,
+    ) -> ScheduledJob[T]:
+        with self._lock:
+            if not self._jobs:
+                self._class_finish = {spawn: 0.0 for spawn in SpawnClass}
+            cost = max(0.01, float(estimated_cost))
+            finish = self._class_finish[spawn_class] + cost / self.weights[spawn_class]
+            self._class_finish[spawn_class] = finish
+            job = ScheduledJob(
+                key=str(key),
+                payload=payload,
+                spawn_class=spawn_class,
+                estimated_cost=cost,
+                enqueued_at=time.monotonic() if now is None else float(now),
+                virtual_finish=finish,
+                sequence=self._sequence,
+            )
+            self._sequence += 1
+            self._jobs.append(job)
+            return job
+
+    def pop(self, *, now: float | None = None) -> ScheduledJob[T] | None:
+        with self._lock:
+            if not self._jobs:
+                return None
+            current = time.monotonic() if now is None else float(now)
+
+            def priority(job: ScheduledJob[T]) -> tuple[float, int]:
+                waited = max(0.0, current - job.enqueued_at)
+                return job.virtual_finish - self.aging_rate * waited, job.sequence
+
+            selected = min(self._jobs, key=priority)
+            self._jobs.remove(selected)
+            return selected
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._jobs)
+
+
+SENSITIVE_TOOL_NAMES = frozenset({
+    "credential_helpers_get",
+    "credential_helpers_store",
+    "x_account_post",
+    "x_account_reply",
+    "x_account_post_action",
+})
+BACKGROUND_TOOL_NAMES = frozenset({
+    "harness_refresh",
+    "reindex_knowledge_graph",
+    "model_pull",
+})
+INTERACTIVE_TOOL_NAMES = frozenset({
+    "session_command",
+    "session_slash",
+    "available_actions",
+})
+
+_LOW_COST_TOOL_NAMES = frozenset({
+    "read_file",
+    "list_directory",
+    "search_files",
+    "find_unique_anchor",
+    "git_status",
+    "available_actions",
+})
+
+
+def _safe_tool_name(tool_name: str) -> str:
+    return re.sub(r"[^A-Za-z0-9_.-]+", "_", tool_name or "tool").strip("_") or "tool"
+
+
+def named_tool_log_path(tool_name: str, *, log_root: Path | str | None = None, suppress: bool = False) -> Path:
+    """Return a stable named log path for a tool, or /dev/null when explicitly suppressed."""
+    if suppress:
+        return Path("/dev/null")
+    root = Path(log_root).expanduser() if log_root is not None else CONFIG_DIR / "logs" / "tools"
+    safe = _safe_tool_name(tool_name)
+    stamp = time.strftime("%Y%m%d")
+    return root / safe / f"{stamp}.log"
+
+
+def classify_tool_runtime(tool_name: str, args: dict[str, Any] | None = None) -> RuntimeHint:
+    """Classify a tool call into a launchd-style runtime posture."""
+    name = (tool_name or "").strip()
+    args = args or {}
+    suppress = name in SENSITIVE_TOOL_NAMES or bool(args.get("suppress_log"))
+    if name in BACKGROUND_TOOL_NAMES:
+        spawn = SpawnClass.BACKGROUND
+        reason = "known long-running/background maintenance tool"
+        estimated_cost = 8.0
+    elif name in INTERACTIVE_TOOL_NAMES:
+        spawn = SpawnClass.INTERACTIVE
+        reason = "session/user-facing command"
+        estimated_cost = 1.0
+    elif name == "run_shell":
+        command = str(args.get("command", "")).lower()
+        if any(token in command for token in ("pytest", "ruff", "mypy", "npm test", "cargo test")):
+            spawn = SpawnClass.ADAPTIVE
+            reason = "verification command; adaptive runtime"
+            estimated_cost = 4.0
+        else:
+            spawn = SpawnClass.INTERACTIVE
+            reason = "shell command may require user-facing output"
+            estimated_cost = 2.0
+    elif name in _LOW_COST_TOOL_NAMES:
+        spawn = SpawnClass.ADAPTIVE
+        reason = "bounded read-only operation"
+        estimated_cost = 1.0
+    else:
+        spawn = SpawnClass.BACKGROUND if suppress else SpawnClass.ADAPTIVE
+        reason = "default runtime classification"
+        estimated_cost = 2.0
+    log_path = named_tool_log_path(name, suppress=suppress)
+    return RuntimeHint(name, spawn, str(log_path), suppress, reason, estimated_cost)
+
+
+def order_tool_batch_by_qos(calls: list[tuple[str, dict[str, Any]]]) -> list[int]:
+    """Return call indexes in weighted-fair dispatch order."""
+    scheduler: WeightedFairQueue[int] = WeightedFairQueue()
+    enqueued_at = time.monotonic()
+    for index, (name, args) in enumerate(calls):
+        hint = classify_tool_runtime(name, args)
+        scheduler.enqueue(
+            str(index),
+            index,
+            hint.spawn_class,
+            estimated_cost=hint.estimated_cost,
+            now=enqueued_at,
+        )
+    ordered: list[int] = []
+    while len(scheduler):
+        job = scheduler.pop(now=enqueued_at)
+        if job is not None:
+            ordered.append(job.payload)
+    return ordered
+
+
+__all__ = [
+    "RuntimeHint",
+    "ScheduledJob",
+    "SpawnClass",
+    "WeightedFairQueue",
+    "classify_tool_runtime",
+    "named_tool_log_path",
+    "order_tool_batch_by_qos",
+]

algo_cli/runtime_services.py

@@ -0,0 +1,320 @@
+"""Ollama / xAI clients, local server startup, and harness-gateway lifecycle."""
+
+from __future__ import annotations
+
+import atexit
+import os
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+from urllib.error import URLError
+from urllib.parse import urljoin
+from urllib.request import Request, urlopen
+
+from ollama import Client
+
+from .config import Config, load_runtime_env
+from . import harness
+from . import model_info as _model_info_module
+from . import xai_auth
+from . import chatgpt_auth
+from .display import show_error, show_info
+from .model_routing import require_cloud_api_key, uses_ollama_cloud
+
+LOCAL_STARTUP_TIMEOUT_SECONDS = 12
+SERVER_READY_TTL_SECONDS = 5.0
+GATEWAY_READY_TTL_SECONDS = 5.0
+
+SERVER_READY_CACHE: dict[str, tuple[float, bool]] = {}
+GATEWAY_PROCESS: subprocess.Popen[Any] | None = None
+GATEWAY_READY_CACHE: dict[str, tuple[float, bool]] = {}
+_TOOL_ENV_KEYS = ("OLLAMA_HOST", "ALGO_CLI_GATEWAY_URL", "OLLAMA_CLI_GATEWAY_URL")
+_TOOL_ENV_CONDITION = threading.Condition(threading.RLock())
+_TOOL_ENV_ACTIVE_VALUES: tuple[str, str, str] | None = None
+_TOOL_ENV_ACTIVE_COUNT = 0
+_TOOL_ENV_PREVIOUS: dict[str, str | None] = {}
+_TOOL_ENV_THREAD_STATE = threading.local()
+
+
+def create_client(cfg: Config) -> Any:
+    load_runtime_env(override=True)
+    if _model_info_module.is_xai_model(cfg.model):
+        from . import xai_client
+
+        return xai_client.active_xai_client()
+    if _model_info_module.is_chatgpt_model(cfg.model):
+        from . import chatgpt_client
+
+        return chatgpt_client.active_chatgpt_client()
+    timeout = max(1.0, float(cfg.chat_stream_timeout_seconds))
+    if uses_ollama_cloud(cfg):
+        require_cloud_api_key(cfg)
+        api_key = os.environ.get("OLLAMA_API_KEY", "").strip()
+        headers = {"Authorization": f"Bearer {api_key}"}
+        return Client(host="https://ollama.com", headers=headers, timeout=timeout)
+    return Client(host=cfg.host, timeout=timeout)
+
+
+def client_for_model(model: str, cfg: Config, active_client: Any) -> Any:
+    if not model or model == cfg.model:
+        return active_client
+    load_runtime_env(override=True)
+    if _model_info_module.is_xai_model(model):
+        if not xai_auth.get_valid_token():
+            show_info(f"Agent block model {model} needs xAI OAuth; falling back to {cfg.model}.")
+            return active_client
+        from . import xai_client
+
+        return xai_client.active_xai_client()
+    if _model_info_module.is_chatgpt_model(model):
+        if not chatgpt_auth.get_valid_token():
+            show_info(f"Agent block model {model} needs ChatGPT OAuth; falling back to {cfg.model}.")
+            return active_client
+        from . import chatgpt_client
+
+        return chatgpt_client.active_chatgpt_client()
+    timeout = max(1.0, float(cfg.chat_stream_timeout_seconds))
+    if uses_ollama_cloud(cfg):
+        require_cloud_api_key(cfg)
+        api_key = os.environ.get("OLLAMA_API_KEY", "").strip()
+        headers = {"Authorization": f"Bearer {api_key}"}
+        return Client(host="https://ollama.com", headers=headers, timeout=timeout)
+    return Client(host=cfg.host, timeout=timeout)
+
+
+def apply_tool_runtime_env(cfg: Config) -> None:
+    os.environ["OLLAMA_HOST"] = cfg.host
+    url = gateway_url()
+    os.environ["ALGO_CLI_GATEWAY_URL"] = url
+    os.environ["OLLAMA_CLI_GATEWAY_URL"] = url
+    if cfg.cloud:
+        load_runtime_env(override=True)
+
+
+@contextmanager
+def scoped_tool_runtime_env(cfg: Config):
+    """Lease process-global tool environment safely across agent threads.
+
+    Equal configurations share a reference-counted lease and remain concurrent.
+    Different configurations serialize because ``os.environ`` cannot represent
+    both values at once.
+    """
+    global _TOOL_ENV_ACTIVE_VALUES, _TOOL_ENV_ACTIVE_COUNT, _TOOL_ENV_PREVIOUS
+
+    url = gateway_url()
+    desired = (str(cfg.host), url, url)
+    thread_depth = int(getattr(_TOOL_ENV_THREAD_STATE, "depth", 0))
+    with _TOOL_ENV_CONDITION:
+        if thread_depth and _TOOL_ENV_ACTIVE_VALUES != desired:
+            raise RuntimeError("nested tool runtime environments must use the same configuration")
+        while _TOOL_ENV_ACTIVE_COUNT and _TOOL_ENV_ACTIVE_VALUES != desired:
+            _TOOL_ENV_CONDITION.wait()
+        if _TOOL_ENV_ACTIVE_COUNT == 0:
+            _TOOL_ENV_PREVIOUS = {key: os.environ.get(key) for key in _TOOL_ENV_KEYS}
+            try:
+                apply_tool_runtime_env(cfg)
+            except BaseException:
+                for key, value in _TOOL_ENV_PREVIOUS.items():
+                    if value is None:
+                        os.environ.pop(key, None)
+                    else:
+                        os.environ[key] = value
+                _TOOL_ENV_PREVIOUS = {}
+                _TOOL_ENV_CONDITION.notify_all()
+                raise
+            _TOOL_ENV_ACTIVE_VALUES = desired
+        _TOOL_ENV_ACTIVE_COUNT += 1
+        _TOOL_ENV_THREAD_STATE.depth = thread_depth + 1
+    try:
+        yield
+    finally:
+        with _TOOL_ENV_CONDITION:
+            _TOOL_ENV_THREAD_STATE.depth = max(0, int(getattr(_TOOL_ENV_THREAD_STATE, "depth", 1)) - 1)
+            _TOOL_ENV_ACTIVE_COUNT -= 1
+            if _TOOL_ENV_ACTIVE_COUNT == 0:
+                for key, value in _TOOL_ENV_PREVIOUS.items():
+                    if value is None:
+                        os.environ.pop(key, None)
+                    else:
+                        os.environ[key] = value
+                _TOOL_ENV_PREVIOUS = {}
+                _TOOL_ENV_ACTIVE_VALUES = None
+                _TOOL_ENV_CONDITION.notify_all()
+
+
+def host_is_local(host: str) -> bool:
+    normalized = host.lower()
+    return "localhost" in normalized or "127.0.0.1" in normalized or "[::1]" in normalized
+
+
+def ollama_server_ready(host: str) -> bool:
+    cached = SERVER_READY_CACHE.get(host)
+    now = time.time()
+    if cached and now - cached[0] <= SERVER_READY_TTL_SECONDS:
+        return cached[1]
+    try:
+        request = Request(urljoin(host.rstrip("/") + "/", "api/version"), method="GET")
+        with urlopen(request, timeout=1.5) as response:
+            ready = 200 <= response.status < 500
+    except (OSError, URLError, ValueError):
+        ready = False
+    SERVER_READY_CACHE[host] = (now, ready)
+    return ready
+
+
+def start_ollama_server(cfg: Config) -> bool:
+    if (
+        uses_ollama_cloud(cfg)
+        or _model_info_module.is_xai_model(cfg.model)
+        or _model_info_module.is_chatgpt_model(cfg.model)
+        or not host_is_local(cfg.host)
+    ):
+        return True
+    return start_local_ollama_host(cfg.host)
+
+
+def start_local_ollama_host(host: str) -> bool:
+    if not host_is_local(host):
+        return True
+    if ollama_server_ready(host):
+        return True
+
+    show_info("Local Ollama server is not responding; starting `ollama serve`.")
+    try:
+        kwargs: dict[str, Any] = {
+            "stdout": subprocess.DEVNULL,
+            "stderr": subprocess.DEVNULL,
+            "stdin": subprocess.DEVNULL,
+            "start_new_session": True,
+        }
+        if sys.platform.startswith("win"):
+            kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW | subprocess.DETACHED_PROCESS
+        subprocess.Popen(["ollama", "serve"], **kwargs)
+        SERVER_READY_CACHE.pop(host, None)
+    except FileNotFoundError:
+        show_error("Could not find `ollama` on PATH. Install Ollama or add it to PATH.")
+        return False
+    except Exception as exc:
+        show_error(f"Could not start Ollama server: {exc}")
+        return False
+
+    deadline = time.time() + LOCAL_STARTUP_TIMEOUT_SECONDS
+    while time.time() < deadline:
+        if ollama_server_ready(host):
+            show_info("Local Ollama server is running.")
+            return True
+        time.sleep(0.5)
+
+    show_error(f"Ollama server did not become ready at {host}.")
+    return False
+
+
+def gateway_url() -> str:
+    return (
+        os.environ.get("ALGO_CLI_GATEWAY_URL")
+        or os.environ.get("OLLAMA_CLI_GATEWAY_URL")
+        or "http://127.0.0.1:8765"
+    ).rstrip("/")
+
+
+def gateway_ready(url: str | None = None) -> bool:
+    url = (url or gateway_url()).rstrip("/")
+    cached = GATEWAY_READY_CACHE.get(url)
+    now = time.time()
+    if cached and now - cached[0] <= GATEWAY_READY_TTL_SECONDS:
+        return cached[1]
+    try:
+        request = Request(url + "/healthz", method="GET")
+        with urlopen(request, timeout=1.0) as response:
+            ready = 200 <= response.status < 500
+    except (OSError, URLError, ValueError):
+        ready = False
+    GATEWAY_READY_CACHE[url] = (now, ready)
+    return ready
+
+
+def gateway_source_dir() -> Path:
+    return Path(__file__).resolve().parents[1] / "harness-gateway"
+
+
+def gateway_command() -> tuple[list[str], Path] | None:
+    configured = os.environ.get("ALGO_CLI_GATEWAY_BIN") or os.environ.get("OLLAMA_CLI_GATEWAY_BIN")
+    if configured:
+        path = Path(configured).expanduser()
+        if path.exists():
+            return [str(path)], path.parent
+    source_dir = gateway_source_dir()
+    exe_name = "harness-gateway.exe" if sys.platform.startswith("win") else "harness-gateway"
+    built = source_dir / exe_name
+    if built.exists():
+        return [str(built)], source_dir
+    go = shutil.which("go") or (r"C:\Program Files\Go\bin\go.exe" if Path(r"C:\Program Files\Go\bin\go.exe").exists() else "")
+    if go and source_dir.exists():
+        return [go, "run", "."], source_dir
+    return None
+
+
+def start_supplemental_gateway(cfg: Config) -> bool:
+    global GATEWAY_PROCESS
+    if not uses_ollama_cloud(cfg):
+        return True
+    if not start_local_ollama_host(cfg.host):
+        return False
+    url = gateway_url()
+    if gateway_ready(url):
+        return True
+    command_info = gateway_command()
+    if command_info is None:
+        show_info(
+            "Supplemental gateway unavailable. Build `harness-gateway` or install Go "
+            "for local embedding/OCR helpers in cloud mode."
+        )
+        return False
+    command, cwd = command_info
+    startup_timeout = 45 if len(command) >= 2 and Path(command[0]).name.lower().startswith("go") and command[1] == "run" else 20
+    addr = url.removeprefix("http://").removeprefix("https://")
+    args = command + ["-addr", addr, "-index", str(harness.INDEX_PATH), "-ollama", cfg.host]
+    try:
+        kwargs: dict[str, Any] = {
+            "cwd": str(cwd),
+            "stdout": subprocess.DEVNULL,
+            "stderr": subprocess.DEVNULL,
+            "stdin": subprocess.DEVNULL,
+        }
+        if sys.platform.startswith("win"):
+            kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
+        GATEWAY_PROCESS = subprocess.Popen(args, **kwargs)
+        GATEWAY_READY_CACHE.pop(url, None)
+    except Exception as exc:
+        show_error(f"Could not start supplemental gateway: {exc}")
+        return False
+    deadline = time.time() + startup_timeout
+    while time.time() < deadline:
+        if gateway_ready(url):
+            show_info(f"Supplemental gateway is running at {url}.")
+            return True
+        time.sleep(0.5)
+    show_error(f"Supplemental gateway did not become ready at {url}.")
+    return False
+
+
+def shutdown_supplemental_gateway() -> None:
+    global GATEWAY_PROCESS
+    if GATEWAY_PROCESS and GATEWAY_PROCESS.poll() is None:
+        try:
+            GATEWAY_PROCESS.terminate()
+            GATEWAY_PROCESS.wait(timeout=3)
+        except Exception:
+            try:
+                GATEWAY_PROCESS.kill()
+            except Exception:
+                pass
+    GATEWAY_PROCESS = None
+
+
+atexit.register(shutdown_supplemental_gateway)

algo_cli/session_commands.py

@@ -0,0 +1,95 @@
+"""Model-callable session slash commands (same behavior as TUI /read, /ls, /cd)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import tools as tools_module
+from .workspace_resolver import parse_path_arg
+
+MODEL_SLASH_COMMANDS: tuple[tuple[str, str], ...] = (
+    ("/read", "Read a file relative to session cwd (deterministic). Args: /read PATH"),
+    ("/ls", "List directory under cwd. Args: /ls or /ls SUBPATH"),
+    ("/cd", "Change session cwd (saved). Args: /cd PATH"),
+    ("/cwd", "Show current session cwd. No args."),
+)
+
+_ALLOWED = frozenset(cmd for cmd, _ in MODEL_SLASH_COMMANDS)
+
+
+def catalog_for_prompt() -> str:
+    lines = [
+        "Slash commands are session controls, not normal prose. If you merely write '/command' in a reply, nothing runs.",
+        "Choose the right path:",
+        "  1. User typed a slash command: the CLI handles it before you see it; do not re-run it unless asked.",
+        "  2. Need deterministic cwd file navigation/read: call session_slash with the full line:",
+        *[f"     - {cmd} — {desc}" for cmd, desc in MODEL_SLASH_COMMANDS],
+        "  3. Need to change/check Algo CLI session state (/status, /mode, /context, /harness refresh, /agent, etc.): call session_command with the full line. Read-only/status commands run without approval; state-changing commands may require approval.",
+        "  4. Need actual work: prefer model-callable tools (read_file/write_file/search_files/run_shell/web_search/etc.) over slash commands.",
+        "When to use common slash commands:",
+        "  - /status or /info: check active model, cwd, context, and toggles before giving configuration advice.",
+        "  - /mode execute|explore|publish: switch operating posture only when the user's task clearly needs it or they ask.",
+        "  - /context status|rebuild|clear: inspect or repair compressed context when context quality/length is the issue.",
+        "  - /reason status|guide: inspect the active reasoning posture or show mode guidance before changing it.",
+        "  - /reason react|reflexion|tot|got|mcts|qcr|neuro_symbolic: change reasoning posture for complex work only; do not switch modes for routine reads/edits.",
+        "    Use react for normal tool loops, reflexion after failed/partial attempts, tot/got/mcts for ambiguous multi-path planning, qcr for comparing candidate solutions, and neuro_symbolic for verification-heavy logic/code claims.",
+        "  - /harness refresh: refresh indexed skills/wiki/memory after local harness files changed.",
+        "  - /intel query TERM: inspect the local repository intelligence graph before code/navigation decisions.",
+        "    Use /intel status to check availability; /intel reindex requires approval because it writes the graph index.",
+        "  - Google Workspace commands are read-only and auth-gated; call available_actions(topic='google') before using /google-login, /google-callback, /google-status, or /google subcommands.",
+        "  - /route TASK: preview the recommended Agent Blocks route before a complex task.",
+        "  - /agent [--pipeline NAME] TASK: run a traceable multi-block pipeline for larger implementation/research/review work.",
+        "  - /agent team [--roles ROLE,ROLE[,ROLE,ROLE]] TASK: delegate independent analysis to 2-4 read-only child threads, then integrate once with normal write and verification gates.",
+        "  - /agent threads or /agent show THREAD: inspect run history; /agent resume THREAD [TASK] continues it and /agent fork THREAD TASK branches it.",
+        "    Delegate only when work has genuinely independent angles. Keep mutations in the integration pipeline; never ask child threads to edit the same workspace.",
+        "  - /kernel check [NAME]: verify kernel imports, slash routes, and active action contracts without executing workloads.",
+        "Do not use slash commands for file edits; use write_file. Do not use slash commands for build/test; use run_shell.",
+        "For the full command/tool catalog and focused examples, call available_actions(topic='slash').",
+    ]
+    return "\n".join(lines)
+
+
+def execute(command_line: str, cfg: Any, *, max_read_chars: int | None = None) -> str:
+    """Run one whitelisted slash command against cfg.cwd."""
+    stripped = (command_line or "").strip()
+    if not stripped.startswith("/"):
+        stripped = f"/{stripped}"
+    if not stripped:
+        return "Error: empty command. Allowed: /read, /ls, /cd, /cwd"
+
+    parts = stripped.split(None, 1)
+    command = parts[0].lower()
+    remainder = stripped[len(parts[0]):].strip() if len(parts) > 1 else ""
+
+    if command not in _ALLOWED:
+        allowed = ", ".join(sorted(_ALLOWED))
+        return f"Error: {command} is not model-invokable. Allowed: {allowed}"
+
+    if command == "/cwd" or (command == "/cd" and not remainder):
+        return f"cwd: {getattr(cfg, 'cwd', '.')}"
+
+    if command == "/cd":
+        target = parse_path_arg(remainder)
+        path = Path(target).expanduser()
+        if not path.is_absolute():
+            path = Path(getattr(cfg, "cwd", ".")) / path
+        if path.exists() and path.is_dir():
+            cfg.cwd = str(path.resolve())
+            if hasattr(cfg, "save"):
+                cfg.save()
+            return f"cwd: {cfg.cwd}"
+        return f"Error: not a directory: {path}"
+
+    if command == "/ls":
+        rel = parse_path_arg(remainder) or "."
+        return tools_module.list_directory(rel, cwd=getattr(cfg, "cwd", None), limit=40)
+
+    if command == "/read":
+        rel = parse_path_arg(remainder)
+        if not rel:
+            return "Error: usage: /read PATH"
+        limit = max_read_chars if max_read_chars is not None else tools_module.MAX_READ_CHARS
+        return tools_module.read_file(rel, cwd=getattr(cfg, "cwd", None), max_chars=limit)
+
+    return f"Error: unhandled command {command}"