kache-ssh 0.1.0__py3-none-any.whl

kache/AGENTS.md

@@ -0,0 +1,212 @@
+# Kache guide for scripts and AI agents
+
+Kache sends shell commands to a person's own devices (their "paired"
+devices) and keeps a live feed of every order. You can use all of it from a
+shell (`kache ... --json`) or as MCP tools (`kache mcp`). This guide is
+everything you need; `kache --help` and `kache <command> --help` list flags.
+
+## How it works
+
+- Every device runs a **gatekeeper** (an SSH server on TCP port 7722). It
+  executes orders only from devices it has paired with, and only after a
+  person said yes to the pairing on that device.
+- An **order** is one command line. It runs exactly as written in the
+  device's own shell: **PowerShell on Windows**, the user's shell
+  (`$SHELL -c`) on Linux and macOS. Check a device's `os` before writing
+  commands for it.
+- **Sessions:** `cd` is remembered per sender and session name, so
+  `cd C:\proj` followed by `git status` in the same session works like a
+  terminal. Other shell state (variables, activated venvs) does not carry
+  over: each order is a fresh shell started in the session folder.
+- **Every order is visible.** Each one appears in the feed of the device
+  that ran it, with the exact command, who sent it and how it ended. The
+  person who owns the devices may be watching live.
+- **Labels.** Orders carry a label naming who gave them. It is taken from
+  `--as`, then `$KACHE_AS`, then an AI agent's own name (`$AI_AGENT`,
+  `CLAUDECODE`). Through MCP the label is the MCP client's name. Never
+  pretend to be the human.
+- **Failures come with evidence.** When an order fails, is refused or is
+  stopped, the gatekeeper writes an evidence report: hints, the last output
+  lines, and the machine's state at that moment.
+- **Addresses.** A paired device is remembered with all of its addresses
+  (LAN IP, Tailscale IP, Tailscale name). Kache tries the one that worked
+  last first, then the others, so devices stay reachable away from home
+  when both run Tailscale.
+
+## Rules for agents
+
+1. Look before you act. Start with `kache devices --json`. It shows what
+   exists, which devices are online, their OS, and how loaded they are.
+2. Prefer read-only commands until you know the state. Ask the person before
+   anything destructive: deleting, overwriting, rebooting, killing processes,
+   or changing system settings.
+3. Always pass a timeout (`--timeout` / `timeout_seconds`). Never start
+   interactive programs; they wait forever for input. Kache has no TTY yet.
+   For long jobs, start them in the background on the device (for example
+   `Start-Process`, `nohup ... &`, or a scheduled task) and poll.
+4. Check a device's health before heavy work. A hot GPU or full RAM shows in
+   `telemetry`.
+5. Pairing needs a person. You may start one (`kache pair` / `kache_pair`)
+   and must tell the person the 6-digit code. Only they can accept it on
+   the other device. Accepting, denying and revoking are not offered to
+   agents through MCP. Do not use `kache accept` unless the person
+   explicitly tells you to.
+6. When a device cannot be reached, run `kache doctor DEVICE --json` and
+   follow its `fix` fields. Do not guess.
+
+## Commands
+
+All commands accept `--json`. JSON output is one object (pretty-printed)
+with `"v"` (the schema version, currently 1). In JSON mode, errors are
+`{"v":1,"ok":false,"error":"..."}` on stdout, with exit code 1.
+
+| Command | Does |
+|---|---|
+| `kache devices` | this device and every paired device: status and health |
+| `kache run TARGET [--as NAME] [--session S] [--timeout SEC] -- COMMAND` | send an order. TARGET is a device name, `a,b,c`, `all` (every paired device) or `this` |
+| `kache feed [-d DEVICE\|all] [-n N] [-f]` | recent events; `-f` follows live. `--json` prints JSON lines, one event per line |
+| `kache evidence ID -d DEVICE` | a failure report (always JSON) |
+| `kache doctor [DEVICE]` | connectivity diagnosis with fixes |
+| `kache discover` | Tailscale devices, and which run Kache |
+| `kache pair ADDRESS` | ask a device to accept this one (a person must accept there) |
+| `kache pending` | pair requests waiting on this device |
+| `kache whoami` | this device: name, addresses, fingerprint, listen mode |
+| `kache rename OLD NEW`, `kache remove NAME` | manage your device list |
+| `kache trusted`, `kache revoke NAME` | who may command this device |
+| `kache listen [all\|tailscale\|IP]` | which networks this gatekeeper answers on |
+| `kache name NEW` | rename this device |
+| `kache agent`, `kache service install`, `kache stop` | run, autostart, stop the gatekeeper |
+| `kache mcp` | MCP server on stdio |
+| `kache` | the interactive Kache terminal (for people) |
+
+### `kache run ... --json`
+
+```json
+{"v": 1, "ok": false, "command": "python train.py", "label": "claude-code",
+ "results": [
+  {"device": "desktop", "exit": 1, "duration": 0.84, "cwd": "C:\\proj",
+   "evidence": "E-3f2a9c", "summary": "A Python module is missing on this device.",
+   "rejected": null, "timed_out": false,
+   "stdout": "...", "stderr": "...ModuleNotFoundError: No module named 'torch'\n",
+   "evidence_report": {"...": "see Evidence below"}},
+  {"device": "pi", "exit": null, "error": "cannot reach pi (...)", "unreachable": true}
+ ]}
+```
+
+- `results` always holds one entry per target, in target order.
+- `exit` is `null` when the device could not be reached.
+- `rejected` is set when the gatekeeper refused the order before running
+  it, for example a command that is not installed on Linux or macOS, or a
+  Kache version mismatch.
+
+### `kache devices --json`
+
+```json
+{"v": 1, "devices": [
+  {"name": "desktop", "this_device": false, "online": true,
+   "address": "100.81.247.101", "addresses": ["100.81.247.101", "192.168.50.152"], "port": 7722,
+   "fingerprint": "SHA256:...", "os": "Windows 11", "kache": "0.1.0", "trusts_you": true,
+   "telemetry": {"cpu": 12.5, "cpu_temp": null, "ram": 41.0, "ram_used": 13.1, "ram_total": 31.8,
+                 "disk": 63.2, "uptime": 86400, "os": "Windows 11", "kache": "0.1.0", "time": 1760000000.0,
+                 "gpus": [{"name": "NVIDIA GeForce RTX 4060 Ti", "temp": 54, "util": 97,
+                           "mem_used": 5.2, "mem_total": 8.0}]},
+   "error": null}]}
+```
+
+- `cpu`, `ram` and `disk` are percentages; memory is in GiB.
+- `cpu_temp` is in °C, or `null` where the OS does not expose it (Windows).
+- `trusts_you: false` means the other device removed this one. Pair again.
+
+### Feed events (`kache feed --json`, `kache_feed`)
+
+One JSON object per line. All of them have `v`, `kind`, `time` (unix
+seconds), `device` (the gatekeeper that saw it) and `device_fp`. Events
+replayed from history on connect have `"replay": true`.
+
+| kind | extra fields |
+|---|---|
+| `order` | `id`, `cmd` (exact command), `sender` {`name`, `label`, `via` (`cli`/`terminal`/`mcp`), `fingerprint`, `addr`}, `cwd`, `session` |
+| `done` | `id`, `cmd`, `sender`, `exit`, `duration`, `session`; `evidence` + `summary` on failure; `rejected`; `cancelled: true` when stopped |
+| `evidence` | `id` (E-...), `order` (order id), `cmd`, `sender`, `summary`, `exit` |
+| `pair-request` | `id` (P-...), `name`, `os`, `fingerprint`, `addr`, `code` |
+| `paired` | `name`, `fingerprint`, `addr` |
+| `pair-declined` | `name`, `fingerprint`, `reason` |
+| `unpaired` | `sender`, `text` |
+| `unreachable` | `text` (from the CLI or MCP, when a device's feed could not be opened) |
+
+### Evidence reports
+
+```json
+{"id": "E-3f2a9c", "time": 1760000000.0, "device": "desktop",
+ "order": {"id": "O-1a2b3c", "cmd": "python train.py", "sender": {"...": "..."}, "cwd": "C:\\proj"},
+ "exit": 1, "duration": 0.84, "summary": "A Python module is missing on this device.",
+ "hints": [{"kind": "python-module", "text": "The Python module 'torch' is not installed on this device."}],
+ "stdout_tail": ["..."], "stderr_tail": ["..."], "command_found": true,
+ "system": {"os": "Windows 11", "machine": "AMD64", "python": "3.13.1", "kache": "0.1.0",
+            "shell": "powershell.exe", "telemetry": {"...": "..."}, "top_processes": [{"...": "..."}]}}
+```
+
+Hint kinds: `command-not-found`, `permission`, `disk-full`,
+`python-module`, `network`, `port-in-use`, `python-exception`,
+`out-of-memory`, `signal`, `cancelled`.
+
+## Exit codes (`kache run`)
+
+| code | meaning |
+|---|---|
+| 0 | the order succeeded on every target |
+| n | the order's own exit code (the highest one across several devices) |
+| 1 | Kache error: bad input, gatekeeper not running, pairing refused... |
+| 2 | at least one device could not be reached |
+| 77 | the device does not accept orders from this one (not paired) |
+| 124 | `--timeout` expired; the order was stopped on the device |
+| 126 | refused: Kache versions differ |
+| 127 | refused: the command does not exist on that device (Linux/macOS; on Windows a missing command exits 1 with a `command-not-found` hint) |
+
+## MCP
+
+Add Kache to any MCP client. In Claude Code:
+`claude mcp add kache -- kache mcp`
+
+| Tool | Arguments |
+|---|---|
+| `kache_devices` | none |
+| `kache_run` | `target`, `command`, optional `session`, `timeout_seconds` (default 120, max 3600) |
+| `kache_feed` | optional `device` (default `all`), `limit` (default 30, max 60) |
+| `kache_evidence` | `id`, `device` |
+| `kache_doctor` | optional `device` |
+| `kache_discover` | none |
+| `kache_pending` | none |
+| `kache_pair` | `address` |
+
+- Results are the same JSON as the CLI, in `structuredContent`, with a
+  text copy in `content`.
+- Each output stream keeps its last 60,000 characters per device; anything
+  cut is reported in `stdout_truncated` / `stderr_truncated`.
+- The default session is `mcp-<client name>`, so `cd` persists across
+  calls.
+
+## Files (read-only for agents)
+
+`kache whoami` prints the state folder: `%LOCALAPPDATA%\kache` on Windows,
+`~/.local/share/kache` on Linux, `~/Library/Application Support/kache` on
+macOS, or `$KACHE_HOME` if set.
+
+| file | contents |
+|---|---|
+| `feed.jsonl` | every event this gatekeeper emitted, one JSON per line (rotated at 5 MB to `feed.old.jsonl`) |
+| `evidence/E-*.json` | evidence reports |
+| `devices.json` | devices this one commands: addresses, port, pinned fingerprint |
+| `trusted.json` | devices allowed to command this one |
+| `device.json` | this device's name, port and listen mode |
+| `device_key` | this device's private key. Never read, copy or print it |
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `cannot reach X (... refused)` | the device is on, but Kache is not running there: `kache service install` on it |
+| `cannot reach X (... timed out)` | the device is off or asleep, on another network without Tailscale, or a firewall drops port 7722 |
+| `answered with a different key` | the device was reinstalled, or this is not the same device. Remove it and pair again; never ignore this |
+| exit 77 | that device no longer trusts this one: pair again |
+| a command works by hand but not through Kache | Kache uses a non-interactive shell without your profile (PowerShell `-NoProfile`). Use full paths or set variables in the command |

kache/__init__.py

@@ -0,0 +1,17 @@
+"""Kache: one terminal to command all your devices.
+
+Every device runs a gatekeeper agent (an SSH server with its own rules);
+the Kache terminal pairs devices, shows their health, sends orders to one
+device or all of them, and keeps a live feed of every order anyone sends.
+"""
+
+__version__ = "0.1.0"
+
+# Bumped whenever devices running different Kache versions could
+# misunderstand each other. The gatekeeper refuses orders from other
+# protocol versions instead of guessing.
+PROTOCOL = 1
+
+# Version of the JSON shapes scripts and AI agents read (feed events, CLI
+# --json output, MCP tool results). Every feed event carries it as "v".
+SCHEMA = 1

kache/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()