runspec-linux 0.6.2__tar.gz → 0.7.0__tar.gz

{runspec_linux-0.6.2 → runspec_linux-0.7.0}/CHANGELOG.md

@@ -1,5 +1,46 @@
 # runspec-linux Changelog
 
+## [0.7.0] — 2026-08-01
+
+Enhancements for corporate application support, devops, and performance work.
+
+### Added — filesystem (folded from runspec-fs)
+
+- The **`fs`** runnable is now folded into the Linux pack (backed by the
+  dependency-free `runspec-fs-core`): one verb per Filesystem MCP tool
+  (`read-text-file` … `move-file`), reads `autonomous` and mutations `confirm`.
+  `runspec serve` flattens the verbs into leaf `fs_<verb>` MCP tools, so a
+  runspec-console agent gets local **and** remote filesystem access on every
+  fleet host through the OS pack it already installs — no separate `runspec-fs`
+  needed. Per-invocation `--run-as <user>` / `--become-method` are inherited on
+  every verb (POSIX escalation, no directory jail).
+
+### Added — new runnables
+
+- **Perf tuning & analysis:** `get-sysctl`, `set-sysctl` (a privileged write —
+  `confirm`, optional `--persist` to `/etc/sysctl.d`), `cpu-info` (governor /
+  frequency / topology), `pressure` (kernel PSI stats).
+- **App discovery & investigation:** `service-detail` (a unit's ExecStart binary,
+  working dir, user, env files, unit-file path, state), `open-ports` (listening
+  port → pid → process), `owning-package` (which package owns a path, dpkg/rpm),
+  `failed-units`.
+- **Network deep-diagnostics:** `trace-route`, `route-table`, `socket-stats`,
+  `dns-config`.
+
+### Added — `--run-as` / `--sudo` on the privileged runnables
+
+- `restart-service`, `tail-log`, `search-log`, `journalctl`, `set-sysctl`,
+  `service-detail`, and `open-ports` now take a mutually-exclusive
+  **`--run-as <user>`** / **`--sudo`** pair (plus `--become-method sudo|su`) so
+  they can run against root-owned / service-account-owned resources.
+  Escalation is internal (`sudo -n -u` / `su`), governed by an `exclusive` group
+  so the two flags can't be combined.
+
+### Changed
+
+- Requires `runspec >= 0.44.0` (leaf-tool inherited globals via `runspec serve`)
+  and `runspec-linux-core >= 0.4.0`; adds a `runspec-fs-core >= 0.2.0` dependency.
+
 ## [0.6.2] — 2026-07-08
 
 Pull in `runspec-linux-core >= 0.3.5` so `install-into-venv` now normalises the

{runspec_linux-0.6.2 → runspec_linux-0.7.0}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: runspec-linux
-Version: 0.6.2
+Version: 0.7.0
 Summary: Linux system admin runnables for runspec
 Requires-Python: >=3.10
-Requires-Dist: runspec-linux-core>=0.3.5
+Requires-Dist: runspec-fs-core>=0.2.0
+Requires-Dist: runspec-linux-core>=0.4.0
 Requires-Dist: runspec-webops-core>=0.1.0
-Requires-Dist: runspec>=0.27.0
+Requires-Dist: runspec>=0.44.0
 Provides-Extra: dev
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'

{runspec_linux-0.6.2 → runspec_linux-0.7.0}/pyproject.toml

@@ -4,13 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux"
-version = "0.6.2"
+version = "0.7.0"
 requires-python = ">=3.10"
 description = "Linux system admin runnables for runspec"
 dependencies = [
-    "runspec>=0.27.0",
-    "runspec-linux-core>=0.3.5",
+    "runspec>=0.44.0",
+    "runspec-linux-core>=0.4.0",
     "runspec-webops-core>=0.1.0",
+    "runspec-fs-core>=0.2.0",
 ]
 
 [project.scripts]
@@ -27,6 +28,18 @@ journalctl        = "runspec_linux.logs:main_journalctl"
 ping-host         = "runspec_linux.network:main_ping_host"
 check-port        = "runspec_linux.network:main_check_port"
 show-connections  = "runspec_linux.network:main_show_connections"
+trace-route       = "runspec_linux.network:main_trace_route"
+route-table       = "runspec_linux.network:main_route_table"
+socket-stats      = "runspec_linux.network:main_socket_stats"
+dns-config        = "runspec_linux.network:main_dns_config"
+get-sysctl        = "runspec_linux.perf:main_get_sysctl"
+set-sysctl        = "runspec_linux.perf:main_set_sysctl"
+cpu-info          = "runspec_linux.perf:main_cpu_info"
+pressure          = "runspec_linux.perf:main_pressure"
+service-detail    = "runspec_linux.investigate:main_service_detail"
+open-ports        = "runspec_linux.investigate:main_open_ports"
+owning-package    = "runspec_linux.investigate:main_owning_package"
+failed-units      = "runspec_linux.investigate:main_failed_units"
 find-large-files  = "runspec_linux.files:main_find_large_files"
 backup-files      = "runspec_linux.files:main_backup_files"
 last-logins       = "runspec_linux.security:main_last_logins"
@@ -46,6 +59,8 @@ install-into-venv = "runspec_linux.venvs:main_install_into_venv"
 configure-pip     = "runspec_linux.venvs:main_configure_pip"
 nc-command        = "runspec_linux.nc_command:main"
 which             = "runspec_linux.commands:main_which"
+# Filesystem (folded from runspec-fs; backed by runspec-fs-core)
+fs                = "runspec_linux.fs.cli:main"
 # Web / TLS probes (runspec-webops-core; cross-platform)
 cert-check        = "runspec_linux.webops:main_cert_check"
 cert-chain        = "runspec_linux.webops:main_cert_chain"

runspec_linux-0.7.0/runspec_linux/_escalation.py

@@ -0,0 +1,20 @@
+"""Shared wrapper helper for the ``--run-as`` / ``--sudo`` / ``--become-method``
+escalation args.
+
+The privileged runnables declare a mutually-exclusive ``escalation`` group with
+``--run-as <user>`` and ``--sudo`` (a flag = "run as root"), plus
+``--become-method sudo|su``. The group guarantees at most one of run-as/sudo is
+set, so this resolves them to the ``(run_as, become_method)`` the core helpers
+take: ``--sudo`` → ``run_as="root"``, ``--run-as x`` → ``run_as="x"``, neither →
+``run_as=None`` (no escalation, runs as the login user).
+"""
+
+from __future__ import annotations
+
+import runspec as rs
+
+
+def resolve_escalation(spec: rs.RunSpec) -> tuple[str | None, str]:
+    """Return ``(run_as, become_method)`` from a spec carrying the escalation args."""
+    run_as = "root" if spec.sudo.value else (spec.run_as.value or None)
+    return run_as, spec.become_method.value

runspec_linux-0.7.0/runspec_linux/fs/__init__.py

@@ -0,0 +1,12 @@
+"""The ``fs`` runnable folded into runspec-linux.
+
+The filesystem is part of the operating system, so the Linux pack ships the
+filesystem runnable directly (backed by the dependency-free ``runspec-fs-core``)
+rather than leaving it to the separate ``runspec-fs`` package. Installing
+runspec-linux therefore gives a runspec-console agent local *and* remote
+filesystem access on every fleet host — one verb per Filesystem MCP tool,
+flattened by ``runspec serve`` into leaf ``fs_<verb>`` tools.
+
+The code mirrors ``runspec-fs`` (``cli`` + runspec-free ``_dispatch`` /
+``_worker``); all logic lives in ``runspec_fs_core``.
+"""

runspec_linux-0.7.0/runspec_linux/fs/_dispatch.py

@@ -0,0 +1,63 @@
+"""Verb → core-helper dispatch, importing only ``runspec_fs_core`` (no runspec).
+
+Shared by ``cli.py`` (the in-process path) and ``_worker.py`` (the ``--run-as``
+path), so both map a verb name + a plain-JSON kwargs dict to the same core
+helper. Keeping it runspec-free means the worker — which runs as a *different* OS
+user under sudo/su — needs only the pure core on its import path, not runspec.
+
+A verbatim copy of ``runspec_fs._dispatch`` so the Linux pack stays
+self-contained; the logic is the shared ``runspec_fs_core``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_fs_core import (
+    allowed_directories,
+    create_directory,
+    directory_tree,
+    edit_file,
+    get_file_info,
+    list_directory,
+    list_directory_with_sizes,
+    move_file,
+    read_media_file,
+    read_multiple_files,
+    read_text_file,
+    search_files,
+    write_file,
+)
+
+
+def run_verb(verb: str, kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Run ``verb`` with plain ``kwargs`` (already unpacked from the parsed spec,
+    JSON-round-trip safe). Raises on failure like the core helpers do."""
+    if verb == "read-text-file":
+        return read_text_file(kwargs["path"], head=kwargs.get("head"), tail=kwargs.get("tail"))
+    if verb == "read-media-file":
+        return read_media_file(kwargs["path"])
+    if verb == "read-multiple-files":
+        return read_multiple_files(kwargs["paths"])
+    if verb == "list-directory":
+        return list_directory(kwargs["path"])
+    if verb == "list-directory-with-sizes":
+        return list_directory_with_sizes(kwargs["path"], sort_by=kwargs["sort_by"])
+    if verb == "directory-tree":
+        return directory_tree(kwargs["path"], exclude=kwargs.get("exclude"))
+    if verb == "search-files":
+        return search_files(kwargs["path"], kwargs["pattern"], exclude=kwargs.get("exclude"))
+    if verb == "get-file-info":
+        return get_file_info(kwargs["path"])
+    if verb == "list-allowed-directories":
+        return allowed_directories()
+    if verb == "write-file":
+        return write_file(kwargs["path"], kwargs["content"])
+    if verb == "edit-file":
+        edits = [tuple(pair) for pair in kwargs["edits"]]
+        return edit_file(kwargs["path"], edits, dry_run=kwargs["dry_run"])
+    if verb == "create-directory":
+        return create_directory(kwargs["path"])
+    if verb == "move-file":
+        return move_file(kwargs["source"], kwargs["destination"])
+    raise ValueError(f"unknown verb: {verb!r}")

runspec_linux-0.7.0/runspec_linux/fs/_worker.py

@@ -0,0 +1,32 @@
+"""Run-as worker: read ``{"verb": ..., "kwargs": ...}`` JSON from stdin, run the
+verb via the pure core, print the JSON result. ``cli.py`` invokes this as the
+target OS user under ``sudo``/``su`` when ``--run-as`` is set, so an in-process
+filesystem verb runs with that user's permissions.
+
+Imports only ``runspec_linux.fs._dispatch`` (→ ``runspec_fs_core``), never
+``runspec`` — the escalated user only needs the pure core importable, and the
+payload is already fully resolved, so no ``runspec.toml`` lookup happens here.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from runspec_fs_core import FsCoreError
+
+from runspec_linux.fs._dispatch import run_verb
+
+
+def main() -> None:
+    payload = json.loads(sys.stdin.read())
+    try:
+        result = run_verb(payload["verb"], payload["kwargs"])
+    except (FsCoreError, OSError, ValueError) as exc:
+        print(json.dumps({"error": str(exc), "kind": type(exc).__name__}, default=str))
+        sys.exit(1)
+    print(json.dumps(result, default=str))
+
+
+if __name__ == "__main__":
+    main()

runspec_linux-0.7.0/runspec_linux/fs/cli.py

@@ -0,0 +1,131 @@
+"""cli.py — the ``fs`` entry point (folded into runspec-linux).
+
+One binary, a verb per Filesystem MCP tool. ``rs.parse("fs")`` resolves the
+subcommand and its args (from the merged ``[fs]`` tables in the pack's
+``runspec.toml``); we unpack each ``.value`` at the boundary into a plain kwargs
+dict and run the matching :mod:`runspec_fs_core` helper.
+
+**Per-invocation ``--run-as``** (a global arg, like ``runspec-linux``'s venv
+runnables): when set to a different OS user, the resolved ``(verb, kwargs)`` is
+shipped over stdin to :mod:`runspec_linux.fs._worker` re-invoked as that user via
+``sudo -n -u`` / ``su`` (:func:`runspec_fs_core.build_become`), so the in-process
+verb runs with that user's permissions. Access is bounded by that user's OS
+permissions — there is no directory jail.
+
+A verbatim copy of ``runspec_fs.cli`` with the local ``_dispatch`` / ``_worker``
+import paths; the logic is the shared ``runspec_fs_core``.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from typing import Any
+
+import runspec as rs
+from runspec_fs_core import BecomeError, FsCoreError, build_become, current_user, escalation_supported
+
+from runspec_linux.fs._dispatch import run_verb
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload, default=str))
+
+
+def _pair_edits(old_text: list[str], new_text: list[str]) -> list[list[str]]:
+    """Zip the two parallel ``--old-text`` / ``--new-text`` lists into
+    ``[old, new]`` pairs, erroring if their counts differ."""
+    if len(old_text) != len(new_text):
+        raise ValueError(f"--old-text / --new-text count mismatch: {len(old_text)} vs {len(new_text)} (pair them by position)")
+    return [[old, new] for old, new in zip(old_text, new_text, strict=False)]
+
+
+def _verb_kwargs(spec: rs.RunSpec) -> dict[str, Any]:
+    """Unpack the parsed spec into a plain, JSON-round-trip-safe kwargs dict for
+    the active verb (paths as strings), so the same dict serves the in-process
+    path and the run-as worker."""
+    command = spec.runspec_command
+
+    if command == "read-text-file":
+        return {"path": str(spec.path.value), "head": spec.head.value, "tail": spec.tail.value}
+    if command == "read-media-file":
+        return {"path": str(spec.path.value)}
+    if command == "read-multiple-files":
+        return {"paths": [str(p) for p in spec.paths.value]}
+    if command == "list-directory":
+        return {"path": str(spec.path.value)}
+    if command == "list-directory-with-sizes":
+        return {"path": str(spec.path.value), "sort_by": spec.sort_by.value}
+    if command == "directory-tree":
+        return {"path": str(spec.path.value), "exclude": spec.exclude.value or None}
+    if command == "search-files":
+        return {"path": str(spec.path.value), "pattern": spec.pattern.value, "exclude": spec.exclude.value or None}
+    if command == "get-file-info":
+        return {"path": str(spec.path.value)}
+    if command == "list-allowed-directories":
+        return {}
+    if command == "write-file":
+        return {"path": str(spec.path.value), "content": spec.content.value}
+    if command == "edit-file":
+        return {
+            "path": str(spec.path.value),
+            "edits": _pair_edits(spec.old_text.value, spec.new_text.value),
+            "dry_run": spec.dry_run.value,
+        }
+    if command == "create-directory":
+        return {"path": str(spec.path.value)}
+    if command == "move-file":
+        return {"source": str(spec.source.value), "destination": str(spec.destination.value)}
+
+    # require-command = true makes a bare invocation unreachable.
+    raise SystemExit("no command — see `fs --help`")  # pragma: no cover
+
+
+def _run_as_worker(run_as: str, method: str, verb: str, kwargs: dict[str, Any]) -> str:
+    """Re-invoke the verb as ``run_as`` via the worker under sudo/su and return
+    its stdout. Raises :class:`BecomeError` on an escalation failure (a
+    passwordless-sudo hint on the classic cases)."""
+    if not escalation_supported():
+        raise BecomeError("--run-as requires a POSIX host (sudo/su)")
+    argv = build_become([sys.executable, "-m", "runspec_linux.fs._worker"], run_as, method)
+    payload = json.dumps({"verb": verb, "kwargs": kwargs})
+    try:
+        proc = subprocess.run(argv, input=payload, capture_output=True, text=True)
+    except FileNotFoundError as exc:  # sudo / su not on PATH
+        raise BecomeError(f"{method} not found: {exc}") from exc
+
+    if proc.returncode != 0:
+        err = (proc.stderr or "").strip()
+        low = err.lower()
+        if "password is required" in low or "a terminal is required" in low:
+            raise BecomeError(f"passwordless {method} is not configured for run-as {run_as!r} ({err})")
+        # The worker prints a JSON error on stdout for tool-level failures — pass
+        # it through with the worker's exit code rather than masking it.
+        out = (proc.stdout or "").strip()
+        if out:
+            print(out)
+            sys.exit(proc.returncode)
+        raise BecomeError(err or f"run-as {run_as!r} failed (exit {proc.returncode})")
+    return proc.stdout
+
+
+def main() -> None:
+    spec = rs.parse("fs")
+    run_as = spec.run_as.value
+    method = spec.become_method.value
+    try:
+        kwargs = _verb_kwargs(spec)
+        if run_as and run_as != current_user():
+            out = _run_as_worker(run_as, method, spec.runspec_command, kwargs)
+            sys.stdout.write(out if out.endswith("\n") else out + "\n")
+            return
+        result = run_verb(spec.runspec_command, kwargs)
+    except (FsCoreError, OSError, ValueError) as exc:
+        _emit({"error": str(exc), "kind": type(exc).__name__})
+        sys.exit(1)
+    _emit(result)
+
+
+if __name__ == "__main__":
+    main()

runspec_linux-0.7.0/runspec_linux/investigate.py

@@ -0,0 +1,50 @@
+"""Wrappers for the application discovery & investigation runnables."""
+
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import failed_units, open_ports, owning_package, service_detail
+
+from runspec_linux._escalation import resolve_escalation
+
+
+def main_service_detail() -> None:
+    spec = rs.parse("service-detail")
+    unit = spec.unit.value
+    run_as, method = resolve_escalation(spec)
+    try:
+        print(json.dumps(service_detail(unit, run_as=run_as, become_method=method)))
+    except Exception as e:
+        print(json.dumps({"error": str(e), "unit": unit}))
+        sys.exit(1)
+
+
+def main_open_ports() -> None:
+    spec = rs.parse("open-ports")
+    proto = spec.proto.value
+    run_as, method = resolve_escalation(spec)
+    try:
+        print(json.dumps(open_ports(proto, run_as=run_as, become_method=method)))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_owning_package() -> None:
+    spec = rs.parse("owning-package")
+    path = str(spec.path.value)
+    try:
+        print(json.dumps(owning_package(path)))
+    except Exception as e:
+        print(json.dumps({"error": str(e), "path": path}))
+        sys.exit(1)
+
+
+def main_failed_units() -> None:
+    rs.parse("failed-units")
+    try:
+        print(json.dumps(failed_units()))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

{runspec_linux-0.6.2 → runspec_linux-0.7.0}/runspec_linux/logs.py

@@ -5,15 +5,21 @@ import sys
 
 import runspec as rs
 from runspec_linux_core import journalctl, search_log, tail_log
-from runspec_linux_core.errors import ToolNotFoundError
+from runspec_linux_core.errors import CommandError, ToolNotFoundError
+
+from runspec_linux._escalation import resolve_escalation
 
 
 def main_tail_log() -> None:
     spec = rs.parse("tail-log")
     file_path = str(spec.file.value)
     lines = spec.lines.value
+    run_as, method = resolve_escalation(spec)
     try:
-        print(json.dumps(tail_log(file_path, lines)))
+        print(json.dumps(tail_log(file_path, lines, run_as=run_as, become_method=method)))
+    except CommandError as e:
+        print(json.dumps({"error": str(e), "file": file_path}))
+        sys.exit(1)
     except OSError as e:
         print(json.dumps({"error": str(e), "file": file_path}))
         sys.exit(1)
@@ -24,8 +30,12 @@ def main_search_log() -> None:
     file_path = str(spec.file.value)
     pattern = spec.pattern.value
     limit = spec.limit.value
+    run_as, method = resolve_escalation(spec)
     try:
-        print(json.dumps(search_log(file_path, pattern, limit)))
+        print(json.dumps(search_log(file_path, pattern, limit, run_as=run_as, become_method=method)))
+    except CommandError as e:
+        print(json.dumps({"error": str(e), "file": file_path}))
+        sys.exit(1)
     except OSError as e:
         print(json.dumps({"error": str(e), "file": file_path}))
         sys.exit(1)
@@ -39,8 +49,9 @@ def main_journalctl() -> None:
     unit = spec.unit.value
     lines = spec.lines.value
     since = spec.since.value
+    run_as, method = resolve_escalation(spec)
     try:
-        print(json.dumps(journalctl(unit, lines, since)))
+        print(json.dumps(journalctl(unit, lines, since, run_as=run_as, become_method=method)))
     except ToolNotFoundError as e:
         print(json.dumps({"error": str(e)}))
         sys.exit(1)

runspec_linux-0.7.0/runspec_linux/network.py

@@ -0,0 +1,80 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import (
+    check_port,
+    dns_config,
+    ping_host,
+    route_table,
+    show_connections,
+    socket_stats,
+    trace_route,
+)
+
+
+def main_ping_host() -> None:
+    spec = rs.parse("ping-host")
+    host = spec.host.value
+    count = spec.count.value
+    try:
+        print(json.dumps(ping_host(host, count)))
+    except Exception as e:
+        print(json.dumps({"error": str(e), "host": host}))
+        sys.exit(1)
+
+
+def main_check_port() -> None:
+    spec = rs.parse("check-port")
+    host = spec.host.value
+    port = spec.port.value
+    timeout = spec.timeout.value
+    print(json.dumps(check_port(host, port, timeout)))
+
+
+def main_show_connections() -> None:
+    spec = rs.parse("show-connections")
+    state_filter = spec.state.value
+    try:
+        print(json.dumps(show_connections(state_filter)))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_trace_route() -> None:
+    spec = rs.parse("trace-route")
+    host = spec.host.value
+    max_hops = spec.max_hops.value
+    try:
+        print(json.dumps(trace_route(host, max_hops)))
+    except Exception as e:
+        print(json.dumps({"error": str(e), "host": host}))
+        sys.exit(1)
+
+
+def main_route_table() -> None:
+    rs.parse("route-table")
+    try:
+        print(json.dumps(route_table()))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_socket_stats() -> None:
+    rs.parse("socket-stats")
+    try:
+        print(json.dumps(socket_stats()))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_dns_config() -> None:
+    rs.parse("dns-config")
+    try:
+        print(json.dumps(dns_config()))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux-0.7.0/runspec_linux/perf.py

@@ -0,0 +1,54 @@
+"""Wrappers for the performance tuning & analysis runnables."""
+
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import cpu_info, get_sysctl, pressure, set_sysctl
+from runspec_linux_core.errors import CommandError
+
+from runspec_linux._escalation import resolve_escalation
+
+
+def main_get_sysctl() -> None:
+    spec = rs.parse("get-sysctl")
+    pattern = spec.pattern.value or None
+    try:
+        print(json.dumps(get_sysctl(pattern)))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_set_sysctl() -> None:
+    spec = rs.parse("set-sysctl")
+    key = spec.key.value
+    value = spec.value.value
+    persist = spec.persist.value
+    run_as, method = resolve_escalation(spec)
+    try:
+        print(json.dumps(set_sysctl(key, value, persist=persist, run_as=run_as, become_method=method)))
+    except CommandError as e:
+        print(json.dumps({"key": key, "applied": False, "error": str(e)}))
+        sys.exit(1)
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_cpu_info() -> None:
+    rs.parse("cpu-info")
+    try:
+        print(json.dumps(cpu_info()))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_pressure() -> None:
+    rs.parse("pressure")
+    try:
+        print(json.dumps(pressure()))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

{runspec_linux-0.6.2 → runspec_linux-0.7.0}/runspec_linux/runspec.toml

@@ -81,6 +81,27 @@ type        = "str"
 short       = "-s"
 description = "Service name to restart"
 
+# Escalation: restarting a system service needs privilege.
+[restart-service.args.run-as]
+type        = "str"
+description = "Run as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+required    = false
+
+[restart-service.args.sudo]
+type        = "flag"
+description = "Run as root (via sudo). Mutually exclusive with --run-as."
+default     = false
+
+[restart-service.args.become-method]
+type        = "choice"
+options     = ["sudo", "su"]
+description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+default     = "sudo"
+
+[restart-service.groups.escalation]
+exclusive   = true
+args        = ["run-as", "sudo"]
+
 # ── Logs ──────────────────────────────────────────────────────────────────────
 
 [tail-log]
@@ -100,6 +121,27 @@ short       = "-n"
 description = "Number of lines to return"
 default     = 50
 
+# Escalation: read a root-owned / service-account-owned log (tail -n under sudo/su).
+[tail-log.args.run-as]
+type        = "str"
+description = "Read as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+required    = false
+
+[tail-log.args.sudo]
+type        = "flag"
+description = "Read as root (via sudo). Mutually exclusive with --run-as."
+default     = false
+
+[tail-log.args.become-method]
+type        = "choice"
+options     = ["sudo", "su"]
+description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+default     = "sudo"
+
+[tail-log.groups.escalation]
+exclusive   = true
+args        = ["run-as", "sudo"]
+
 [search-log]
 serve       = ["local"]
 description = "Search a log file for lines matching a pattern"
@@ -122,6 +164,27 @@ short       = "-n"
 description = "Maximum number of matching lines to return"
 default     = 100
 
+# Escalation: search a root-owned / service-account-owned log (cat under sudo/su).
+[search-log.args.run-as]
+type        = "str"
+description = "Read as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+required    = false
+
+[search-log.args.sudo]
+type        = "flag"
+description = "Read as root (via sudo). Mutually exclusive with --run-as."
+default     = false
+
+[search-log.args.become-method]
+type        = "choice"
+options     = ["sudo", "su"]
+description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+default     = "sudo"
+
+[search-log.groups.escalation]
+exclusive   = true
+args        = ["run-as", "sudo"]
+
 [journalctl]
 serve       = ["local"]
 description = "Fetch recent journal entries for a systemd unit (systemd-only)"
@@ -144,6 +207,27 @@ type        = "str"
 description = "Return entries since this time string (e.g. '1 hour ago', '2026-05-27 08:00')"
 required    = false
 
+# Escalation: read a protected unit's journal (outside the systemd-journal group).
+[journalctl.args.run-as]
+type        = "str"
+description = "Read as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+required    = false
+
+[journalctl.args.sudo]
+type        = "flag"
+description = "Read as root (via sudo). Mutually exclusive with --run-as."
+default     = false
+
+[journalctl.args.become-method]
+type        = "choice"
+options     = ["sudo", "su"]
+description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+default     = "sudo"
+
+[journalctl.groups.escalation]
+exclusive   = true
+args        = ["run-as", "sudo"]
+
 # ── Network ───────────────────────────────────────────────────────────────────
 
 [ping-host]
@@ -896,3 +980,311 @@ type        = "flag"
 short       = "-k"
 description = "Skip TLS certificate verification when fetching the spec"
 default     = false
+
+# ── Performance tuning & analysis ─────────────────────────────────────────────
+
+[get-sysctl]
+serve       = ["local"]
+description = "Read kernel parameters (sysctl), optionally filtered by a substring of the key"
+autonomy    = "autonomous"
+output      = "json"
+
+[get-sysctl.args.pattern]
+type        = "str"
+short       = "-p"
+description = "Only return keys containing this substring (e.g. 'net.core')"
+required    = false
+
+[set-sysctl]
+serve       = ["local"]
+description = "Set a kernel parameter (sysctl -w), optionally persisting it under /etc/sysctl.d"
+autonomy    = "confirm"
+output      = "json"
+
+[set-sysctl.args.key]
+type        = "str"
+short       = "-k"
+description = "Dotted sysctl key (e.g. net.core.somaxconn)"
+
+[set-sysctl.args.value]
+type        = "str"
+description = "New value to set"
+
+[set-sysctl.args.persist]
+type        = "flag"
+description = "Also append the setting to /etc/sysctl.d/99-runspec.conf so it survives a reboot"
+default     = false
+
+# Escalation: writing a kernel parameter is privileged.
+[set-sysctl.args.run-as]
+type        = "str"
+description = "Apply as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+required    = false
+
+[set-sysctl.args.sudo]
+type        = "flag"
+description = "Apply as root (via sudo). Mutually exclusive with --run-as."
+default     = false
+
+[set-sysctl.args.become-method]
+type        = "choice"
+options     = ["sudo", "su"]
+description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+default     = "sudo"
+
+[set-sysctl.groups.escalation]
+exclusive   = true
+args        = ["run-as", "sudo"]
+
+[cpu-info]
+serve       = ["local"]
+description = "Report CPU model, core count, and per-CPU scaling governor and frequency"
+autonomy    = "autonomous"
+output      = "json"
+
+[pressure]
+serve       = ["local"]
+description = "Report kernel PSI pressure-stall stats for CPU, IO, and memory"
+autonomy    = "autonomous"
+output      = "json"
+
+# ── Application discovery & investigation ─────────────────────────────────────
+
+[service-detail]
+serve       = ["local"]
+description = "Show where a systemd unit lives: ExecStart binary, working dir, user, env files, unit-file path, and state"
+autonomy    = "autonomous"
+output      = "json"
+
+[service-detail.args.unit]
+type        = "str"
+short       = "-u"
+description = "Systemd unit name (e.g. nginx or nginx.service)"
+
+# Escalation: some properties on protected units need privilege.
+[service-detail.args.run-as]
+type        = "str"
+description = "Read as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+required    = false
+
+[service-detail.args.sudo]
+type        = "flag"
+description = "Read as root (via sudo). Mutually exclusive with --run-as."
+default     = false
+
+[service-detail.args.become-method]
+type        = "choice"
+options     = ["sudo", "su"]
+description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+default     = "sudo"
+
+[service-detail.groups.escalation]
+exclusive   = true
+args        = ["run-as", "sudo"]
+
+[open-ports]
+serve       = ["local"]
+description = "List listening sockets mapped to the owning process (port to pid to process name)"
+autonomy    = "autonomous"
+output      = "json"
+
+[open-ports.args.proto]
+type        = "choice"
+options     = ["tcp", "udp", "both"]
+description = "Which listening sockets to report"
+default     = "tcp"
+
+# Escalation: the full pid/process map needs privilege (ss shows other users' processes only as root).
+[open-ports.args.run-as]
+type        = "str"
+description = "Probe as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+required    = false
+
+[open-ports.args.sudo]
+type        = "flag"
+description = "Probe as root (via sudo). Mutually exclusive with --run-as."
+default     = false
+
+[open-ports.args.become-method]
+type        = "choice"
+options     = ["sudo", "su"]
+description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+default     = "sudo"
+
+[open-ports.groups.escalation]
+exclusive   = true
+args        = ["run-as", "sudo"]
+
+[owning-package]
+serve       = ["local"]
+description = "Report which installed package owns a file path (dpkg / rpm)"
+autonomy    = "autonomous"
+output      = "json"
+
+[owning-package.args.path]
+type        = "path"
+short       = "-p"
+description = "File path to resolve to its owning package"
+
+[failed-units]
+serve       = ["local"]
+description = "List systemd service units currently in the failed state"
+autonomy    = "autonomous"
+output      = "json"
+
+# ── Network deep-diagnostics ──────────────────────────────────────────────────
+
+[trace-route]
+serve       = ["local"]
+description = "Trace the network path to a host (traceroute / tracepath)"
+autonomy    = "autonomous"
+output      = "json"
+
+[trace-route.args.host]
+type        = "str"
+short       = "-H"
+description = "Destination host or IP"
+
+[trace-route.args.max-hops]
+type        = "int"
+short       = "-m"
+description = "Maximum number of hops to probe"
+default     = 30
+
+[route-table]
+serve       = ["local"]
+description = "Show the kernel IPv4 routing table (ip route)"
+autonomy    = "autonomous"
+output      = "json"
+
+[socket-stats]
+serve       = ["local"]
+description = "Summarise socket usage by protocol (ss -s)"
+autonomy    = "autonomous"
+output      = "json"
+
+[dns-config]
+serve       = ["local"]
+description = "Show the host's DNS configuration: nameservers, search domains, and options (/etc/resolv.conf + resolvectl)"
+autonomy    = "autonomous"
+output      = "json"
+
+# ── Filesystem (folded from runspec-fs; backed by runspec-fs-core) ─────────────
+# The filesystem is part of the OS, so the Linux pack ships the `fs` runnable
+# directly. One verb per Filesystem MCP tool; `runspec serve` re-expands each
+# verb into a leaf MCP tool (fs_read-text-file, fs_write-file, …), giving a
+# runspec-console agent local AND remote filesystem access on every fleet host.
+# No directory jail — access is bounded by the OS permissions of the invoking
+# (or --run-as) user.
+
+[fs]
+serve = ["local"]
+description = "Read and manipulate the filesystem on this host (local, or remote via runspec-console)"
+output = "json"
+require-command = true
+examples = [
+  {cmd = "fs list-directory --path .", description = "List the current directory"},
+  {cmd = "fs read-text-file --path README.md --head 20", description = "Read the first 20 lines of a file"},
+  {cmd = "fs search-files --path . --pattern '*.py'", description = "Find Python files recursively"},
+  {cmd = "fs edit-file --path a.txt --old-text foo --new-text bar", description = "Replace 'foo' with 'bar'"},
+  {cmd = "fs --run-as deploy read-text-file --path /home/deploy/app.log", description = "Run a verb as another OS user (chosen per invocation)"},
+]
+
+# ── global args (inherited by every verb) ──────────────────────────────────
+# Per-invocation run-as: the user/agent picks which OS user each verb runs as,
+# like runspec-linux's venv runnables. The operation is re-invoked as that user
+# via sudo/su, so access is bounded by THAT user's OS permissions — no jail.
+[fs.args]
+run-as        = {type = "str",    required = false, description = "Run this operation as another OS user (via sudo -n -u / su, chosen per invocation). Access is then bounded by that user's OS permissions. POSIX only; needs passwordless sudo for the target user."}
+become-method = {type = "choice", options = ["sudo", "su"], default = "sudo", description = "How to escalate to --run-as."}
+
+# ── reads / metadata → autonomous ──────────────────────────────────────────
+
+[fs.commands.read-text-file]
+description = "Read a file as UTF-8 text; optionally only the first N (--head) or last N (--tail) lines"
+autonomy = "autonomous"
+[fs.commands.read-text-file.args]
+path = {type = "path", required = true, description = "File to read"}
+head = {type = "int", required = false, description = "Return only the first N lines"}
+tail = {type = "int", required = false, description = "Return only the last N lines"}
+
+[fs.commands.read-media-file]
+description = "Read a binary/media file and return it base64-encoded with its MIME type"
+autonomy = "autonomous"
+[fs.commands.read-media-file.args]
+path = {type = "path", required = true, description = "File to read"}
+
+[fs.commands.read-multiple-files]
+description = "Read several files at once; a failed read is reported per-file without aborting the batch"
+autonomy = "autonomous"
+[fs.commands.read-multiple-files.args]
+paths = {type = "path", multiple = true, required = true, description = "Files to read (repeat --paths per file)"}
+
+[fs.commands.list-directory]
+description = "List a directory's immediate contents, each tagged file or directory"
+autonomy = "autonomous"
+[fs.commands.list-directory.args]
+path = {type = "path", required = true, description = "Directory to list"}
+
+[fs.commands.list-directory-with-sizes]
+description = "List a directory's contents with per-entry sizes and totals"
+autonomy = "autonomous"
+[fs.commands.list-directory-with-sizes.args]
+path = {type = "path", required = true, description = "Directory to list"}
+sort-by = {type = "choice", options = ["name", "size"], default = "name", description = "Sort order (size is descending)"}
+
+[fs.commands.directory-tree]
+description = "Return a recursive JSON tree of a directory"
+autonomy = "autonomous"
+[fs.commands.directory-tree.args]
+path = {type = "path", required = true, description = "Directory to walk"}
+exclude = {type = "str", multiple = true, required = false, description = "Glob patterns to prune (repeat --exclude)"}
+
+[fs.commands.search-files]
+description = "Recursively find files/directories whose name matches a pattern (glob, or case-insensitive substring)"
+autonomy = "autonomous"
+[fs.commands.search-files.args]
+path = {type = "path", required = true, description = "Directory to search under"}
+pattern = {type = "str", required = true, description = "Glob (e.g. '*.py') or a case-insensitive substring"}
+exclude = {type = "str", multiple = true, required = false, description = "Glob patterns to prune (repeat --exclude)"}
+
+[fs.commands.get-file-info]
+description = "Return detailed metadata for a file or directory (size, timestamps, permissions)"
+autonomy = "autonomous"
+[fs.commands.get-file-info.args]
+path = {type = "path", required = true, description = "File or directory to stat"}
+
+[fs.commands.list-allowed-directories]
+description = "Report the effective user and starting directories (informational — no directory jail is enforced)"
+autonomy = "autonomous"
+
+# ── mutations → confirm ────────────────────────────────────────────────────
+
+[fs.commands.write-file]
+description = "Create a new file or overwrite an existing one with UTF-8 text"
+autonomy = "confirm"
+[fs.commands.write-file.args]
+path = {type = "path", required = true, description = "File to write"}
+content = {type = "str", required = true, description = "File contents"}
+
+[fs.commands.edit-file]
+description = "Apply ordered old→new substring replacements to a file; returns a unified diff. Pair each --old-text with a --new-text by position."
+autonomy = "confirm"
+[fs.commands.edit-file.args]
+path = {type = "path", required = true, description = "File to edit"}
+old-text = {type = "str", multiple = true, required = true, description = "Text to find (repeat --old-text; paired by position with --new-text)"}
+new-text = {type = "str", multiple = true, required = true, description = "Replacement text (repeat --new-text; paired by position with --old-text)"}
+dry-run = {type = "flag", default = false, description = "Compute and diff the edits without writing"}
+
+[fs.commands.create-directory]
+description = "Create a directory (and any missing parents); idempotent"
+autonomy = "confirm"
+[fs.commands.create-directory.args]
+path = {type = "path", required = true, description = "Directory to create"}
+
+[fs.commands.move-file]
+description = "Move or rename a file/directory; fails if the destination already exists"
+autonomy = "confirm"
+[fs.commands.move-file.args]
+source = {type = "path", required = true, description = "Path to move"}
+destination = {type = "path", required = true, description = "New path (must not already exist)"}

{runspec_linux-0.6.2 → runspec_linux-0.7.0}/runspec_linux/services.py

@@ -5,6 +5,8 @@ import runspec as rs
 from runspec_linux_core import check_service, list_services, restart_service
 from runspec_linux_core.errors import CommandError
 
+from runspec_linux._escalation import resolve_escalation
+
 
 def main_check_service() -> None:
     spec = rs.parse("check-service")
@@ -29,8 +31,9 @@ def main_list_services() -> None:
 def main_restart_service() -> None:
     spec = rs.parse("restart-service")
     service = spec.service.value
+    run_as, method = resolve_escalation(spec)
     try:
-        print(json.dumps(restart_service(service)))
+        print(json.dumps(restart_service(service, run_as=run_as, become_method=method)))
     except CommandError as e:
         print(json.dumps({"service": service, "restarted": False, "error": str(e)}))
         sys.exit(1)

runspec_linux-0.7.0/tests/test_escalation.py

@@ -0,0 +1,34 @@
+"""The wrapper-side escalation resolver: --sudo / --run-as / --become-method →
+(run_as, become_method).
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from runspec_linux._escalation import resolve_escalation
+
+
+def _spec(sudo: bool, run_as: str, method: str = "sudo") -> SimpleNamespace:
+    # A parsed spec exposes each arg as an object with a .value.
+    return SimpleNamespace(
+        sudo=SimpleNamespace(value=sudo),
+        run_as=SimpleNamespace(value=run_as),
+        become_method=SimpleNamespace(value=method),
+    )
+
+
+def test_sudo_maps_to_root() -> None:
+    assert resolve_escalation(_spec(sudo=True, run_as="")) == ("root", "sudo")
+
+
+def test_run_as_user() -> None:
+    assert resolve_escalation(_spec(sudo=False, run_as="deploy")) == ("deploy", "sudo")
+
+
+def test_neither_is_none() -> None:
+    assert resolve_escalation(_spec(sudo=False, run_as="")) == (None, "sudo")
+
+
+def test_become_method_passthrough() -> None:
+    assert resolve_escalation(_spec(sudo=False, run_as="svc", method="su")) == ("svc", "su")

runspec_linux-0.7.0/tests/test_fs.py

@@ -0,0 +1,51 @@
+"""The `fs` runnable folded into runspec-linux (backed by runspec-fs-core).
+
+Smoke coverage that the folded verbs run in-process and that the run-as worker
+path builds the right escalation command. Full verb behaviour is covered by
+runspec-fs-core's own suite.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+
+import pytest
+
+from runspec_linux.fs import _dispatch, cli
+
+
+def test_dispatch_read_and_list(tmp_path) -> None:
+    f = tmp_path / "a.txt"
+    f.write_text("hello\nworld\n")
+    assert _dispatch.run_verb("read-text-file", {"path": str(f)})["content"] == "hello\nworld\n"
+    listing = _dispatch.run_verb("list-directory", {"path": str(tmp_path)})
+    assert listing["count"] == 1
+    assert listing["entries"][0]["name"] == "a.txt"
+
+
+def test_dispatch_unknown_verb() -> None:
+    with pytest.raises(ValueError):
+        _dispatch.run_verb("frobnicate", {})
+
+
+def test_pair_edits_mismatch() -> None:
+    with pytest.raises(ValueError, match="count mismatch"):
+        cli._pair_edits(["a", "b"], ["x"])
+
+
+def test_run_as_worker_builds_sudo_command(monkeypatch: pytest.MonkeyPatch) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_run(argv, input=None, capture_output=None, text=None):  # noqa: A002
+        captured["argv"] = argv
+        captured["input"] = input
+        return subprocess.CompletedProcess(argv, 0, stdout='{"ok": true}', stderr="")
+
+    monkeypatch.setattr(cli.subprocess, "run", fake_run)
+    out = cli._run_as_worker("svc", "sudo", "list-directory", {"path": "/tmp"})
+    argv = captured["argv"]
+    assert argv[:4] == ["sudo", "-n", "-u", "svc"]
+    assert argv[-2:] == ["-m", "runspec_linux.fs._worker"]
+    assert json.loads(captured["input"]) == {"verb": "list-directory", "kwargs": {"path": "/tmp"}}
+    assert json.loads(out) == {"ok": True}

runspec_linux-0.6.2/runspec_linux/network.py

@@ -1,34 +0,0 @@
-import json
-import sys
-
-import runspec as rs
-from runspec_linux_core import check_port, ping_host, show_connections
-
-
-def main_ping_host() -> None:
-    spec = rs.parse("ping-host")
-    host = spec.host.value
-    count = spec.count.value
-    try:
-        print(json.dumps(ping_host(host, count)))
-    except Exception as e:
-        print(json.dumps({"error": str(e), "host": host}))
-        sys.exit(1)
-
-
-def main_check_port() -> None:
-    spec = rs.parse("check-port")
-    host = spec.host.value
-    port = spec.port.value
-    timeout = spec.timeout.value
-    print(json.dumps(check_port(host, port, timeout)))
-
-
-def main_show_connections() -> None:
-    spec = rs.parse("show-connections")
-    state_filter = spec.state.value
-    try:
-        print(json.dumps(show_connections(state_filter)))
-    except Exception as e:
-        print(json.dumps({"error": str(e)}))
-        sys.exit(1)