@runneth/cli 0.0.0-sha.3142666bf4dc.production

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@runneth/cli",
+  "version": "0.0.0-sha.3142666bf4dc.production",
+  "type": "module",
+  "description": "Fast persistent local shell sessions for coding agents",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Motion-Creative/agent-builder.git"
+  },
+  "homepage": "https://github.com/Motion-Creative/agent-builder",
+  "bugs": {
+    "url": "https://github.com/Motion-Creative/agent-builder/issues"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "bin": {
+    "runneth-cli": "dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "skills"
+  ]
+}

package/skills/runneth/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: runneth
+description: Connect to and inspect Runneth sandboxes from Codex or Claude Code using the OAuth Runneth CLI. Use whenever the user says runneth in an operational context, asks to SSH into a Runneth VM or sandbox, configure Runneth CLI targets, run commands in a VM, keep a persistent SSH control process, install Runneth SSH access, or reason about the /agent, /runneth, /daemon, and runtime SSH layout.
+---
+
+# Runneth
+
+## Default Transport
+
+Use the Runneth CLI OAuth SSH flow for normal runtime access.
+
+The CLI handles OAuth login, token refresh, Runneth key generation, public-key install, SSH config, and the SSH tunnel. For normal runtime SSH, use the CLI path exclusively.
+
+Use Azure, daemon APIs, Datadog, or direct host administration only when the user explicitly asks for fleet, VM, image, daemon, or control-plane debugging, or when the CLI path itself is being debugged.
+
+## CLI Package
+
+Use the package spec the user gives you when one is provided. By default, use the public npm package:
+
+```bash
+npx @runneth/cli ...
+```
+
+If the package is already installed on PATH, use `runneth-cli ...`.
+
+## Targets
+
+A target stores the OAuth resource URL and the SSH app URL for a VM.
+
+Add a target from a full host:
+
+```bash
+runneth-cli ssh target add <target-name> \
+  --host <full-host> \
+  --default
+```
+
+`--host` is the entire host. Do not infer or append a suffix. If the user gives the complete SSH app URL, use `--ssh-url`:
+
+```bash
+runneth-cli ssh target add <target-name> \
+  --ssh-url https://<full-host>/runneth/ssh \
+  --default
+```
+
+List and select targets:
+
+```bash
+runneth-cli ssh target list
+runneth-cli ssh target use <target-name>
+```
+
+Import multiple targets from JSON:
+
+```bash
+runneth-cli ssh target import ./runneth-targets.json
+```
+
+Example import file:
+
+```json
+{
+  "resourceUrl": "https://projects.motionapp.com/mcp",
+  "defaultTarget": "primary",
+  "targets": [
+    {
+      "name": "primary",
+      "host": "e0da08e2-cf18-457f-80e3-48745967dedf.app.runneth.com"
+    },
+    {
+      "name": "worker",
+      "sshUrl": "https://example.internal/runneth/ssh"
+    }
+  ]
+}
+```
+
+## Commands
+
+Run a one-off command:
+
+```bash
+runneth-cli ssh --target <target-name> -- 'whoami && pwd && hostname'
+```
+
+Open an interactive shell:
+
+```bash
+runneth-cli ssh --target <target-name>
+```
+
+The public HTTP tunnel can have noticeable per-keystroke latency. For agents or sequential command work, prefer one-off commands or stdio mode.
+
+## Agent Stdio Mode
+
+Use stdio mode for Claude Code, Codex, and other agents that need to keep one SSH session available without reopening SSH for every command.
+
+Start the process:
+
+```bash
+runneth-cli ssh stdio --target <target-name>
+```
+
+Send one JSON request per line on stdin and read one JSON event per line on stdout.
+
+One-off command:
+
+```json
+{
+  "id": "1",
+  "method": "exec",
+  "params": { "command": "pwd && ls -la", "timeoutMs": 600000 }
+}
+```
+
+Spawn a persistent process and write to it:
+
+```json
+{"id":"2","method":"spawn","params":{"command":"bash"}}
+{"id":"2","method":"stdin","params":{"data":"pwd\n"}}
+{"id":"2","method":"stdin","params":{"data":"exit\n"}}
+```
+
+Other supported requests:
+
+```json
+{"id":"5","method":"list"}
+{"id":"2","method":"signal","params":{"signal":"SIGINT"}}
+{"id":"2","method":"close"}
+{"id":"7","method":"ping"}
+```
+
+For `spawn`, the request `id` is the process id. Use the same `id` for that process's `stdin`, `signal`, and `close` requests.
+
+Keep the stdio process open for the duration of a task. Do not repeatedly reopen SSH for a sequence of commands unless the stdio process is unavailable.
+
+## Auth And Keys
+
+The CLI uses OAuth. On first use it opens a browser or prints an authorization URL; the user must complete that login. Use CLI flags such as `--no-open` only when browser opening is not possible.
+
+The CLI generates one shared default Runneth key pair and reuses it across targets by default. The public key is installed into the VM through the OAuth-protected SSH app API.
+
+Use `--unique-key` when the user wants a separate key for one target. Use `--identity-file <path>` when the user provides an existing private key and matching public key.
+
+The default OAuth resource should be baked into the published CLI from `MONDRIAN_API_URL/mcp`. If a package was built without the correct default, pass `--resource https://projects.motionapp.com/mcp` explicitly and treat that as a package/build issue to fix.
+
+## Runtime Filesystem
+
+Runtime SSH enters as the `runneth-ssh` user.
+
+Useful paths inside a Runneth VM:
+
+- `/agent` - workspace shared with the runtime.
+- `/agent/.runtime` - runtime-owned state.
+- `/daemon` - process-daemon HTTP API and runtime controls.
+- `/daemon/ssh/authorized_keys` - Runneth SSH authorized keys on the VM OS disk.
+- `/runneth` - app code and app_core runtime.
+
+## Validation
+
+For a smoke test, run:
+
+```bash
+runneth-cli ssh --target <target-name> -- 'printf "user=%s pwd=%s host=%s\n" "$(whoami)" "$(pwd)" "$(hostname)"'
+```
+
+Expected result: the command exits successfully, the user is usually `runneth-ssh`, and the VM hostname is returned.
+
+## Troubleshooting
+
+Common failures:
+
+- `401` or `403`: OAuth is missing, expired, or the user does not have access to the VM organization.
+- `404` for `/api/tunnels`: app_core is stale or the SSH app route is not deployed.
+- `405` for `/api/keys`: the SSH app is stale and does not expose the public-key install API.
+- `503`: public app routing, daemon health, runtime app startup, or the tunnel limit is blocking access.
+- Slow interactive typing: expected HTTP tunnel latency; switch to `ssh stdio` or one-off commands.