@runneth/cli 0.0.0-sha.08ddca3b68de.production

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@runneth/cli",
+  "version": "0.0.0-sha.08ddca3b68de.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": "dist/cli.js",
+    "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"
+  ],
+  "dependencies": {
+    "ws": "^8.21.0",
+    "zod": "4.3.6"
+  },
+  "runnethCliUpdate": {
+    "mode": "registry",
+    "packageName": "@runneth/cli",
+    "tag": "latest"
+  }
+}

package/skills/runneth/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: runneth
+description: Use the Runneth CLI for conversation automation, interactive chat, VM access over SSH, saved targets, and persistent local shells. Use when working with Runneth conversations, connecting to a conversation VM, running remote commands through JSONL, setting up CLI authentication or agent skills, or inspecting the runtime filesystem.
+---
+
+# Runneth
+
+## 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 updates
+
+The promoted CLI checks for updates automatically and asks before installing.
+Use these commands when the user asks about the installed version or wants to
+update:
+
+```bash
+runneth --version
+runneth update
+```
+
+An update refuses to start while this installation has an active local daemon.
+Let persistent sessions finish, close them, and run `runneth shutdown` in
+each CLI home before retrying the update. Do not end active sessions merely to
+update the CLI unless the user explicitly approves it. The next daemon-backed
+command starts the updated daemon.
+
+The first manual package-manager upgrade that installs the updater requires
+this shutdown step in every CLI home and custom socket before installation.
+If an unregistered daemon remains afterward, use `close` and `shutdown` to
+finish the cutover; other daemon commands and updates in that home refuse it.
+`shutdown` succeeds when the selected daemon is already stopped.
+
+A crashed updater can leave a durable `replacement.json` record in the
+account-home `.runneth-cli-daemon-gates` directory. It blocks new daemons and
+updates even after heartbeat locks expire. Do not delete it because its PID
+is gone or its timestamp is old. Recovery requires a computer restart, direct
+package-manager repair of the recorded installation, successful `--version`
+and `--help` checks, then removal of only the reported replacement record.
+Follow the installed package README's interrupted-update recovery procedure.
+
+## Command discovery
+
+Run `runneth help --json` to read the public command catalog. It includes command
+paths, audience, execution location, output format, flags, required inputs, and
+effects. Use `runneth help <command> --json` to narrow the catalog and
+`runneth <command> --help` for examples. Help does not start sign-in or execute commands.
+
+Choose the interface for the task:
+
+- `chat`: interactive terminal conversations for humans.
+- `conversation`: remote conversation automation through JSON or a persistent JSONL process.
+- `ssh` and `ssh stdio`: commands and processes on a remote VM.
+- `open`, `send`, `status`, `list`, `close`, and `shutdown`: local shells on the user's computer.
+
+## Conversations
+
+Use an explicit workspace for conversation commands. Check existing sign-in with
+`runneth oauth status`; use `runneth oauth login` when sign-in is needed. Login
+returns an access token, so do not include its output in logs or user-facing
+summaries. Read `runneth help conversation --json` for authentication options.
+
+Create a conversation:
+
+```bash
+runneth conversation create --workspace <workspace-id> --title "Review the latest report" --json
+```
+
+Read `conversation.id` from the result, then use that ID for later requests:
+
+```bash
+runneth conversation send --workspace <workspace-id> --conversation <conversation-id> --message "Summarize the latest report" --json
+runneth conversation state --workspace <workspace-id> --conversation <conversation-id> --json
+```
+
+These commands require `--json`. There is no implicit active conversation.
+`send` waits for the assistant response; use `--stdin` instead of `--message`
+when the message comes from a file or pipe. Inspect the returned assistant
+message's status before reporting success.
+
+### Persistent conversation session
+
+Keep one process open for repeated conversation operations:
+
+```bash
+runneth conversation session --workspace <workspace-id> --jsonl
+```
+
+Wait for the `ready` event. It reports connection and workspace context, not an
+active conversation. Send one complete JSON object per line, followed by a
+newline. Match response events to the request `id`.
+
+<!-- prettier-ignore -->
+```jsonl
+{"id":"1","method":"create","params":{"title":"Review the latest report"}}
+```
+
+Wait for `created`, read `conversation.id`, and replace `<conversation-id>` in
+each request below. Send requests as needed, rather than sending the whole block
+at once:
+
+```jsonl
+{"id":"2","method":"send","params":{"conversationId":"<conversation-id>","text":"Summarize the latest report"}}
+{"id":"3","method":"state","params":{"conversationId":"<conversation-id>"}}
+{"id":"4","method":"ping"}
+{"id":"5","method":"close"}
+```
+
+`send` emits `sent`, state updates, then `complete`. Set `params.wait` to `false`
+to return after `sent`, then use `state` to inspect progress. Treat `error`
+events as failures. `close` ends this local JSONL session; it does not delete the
+remote conversation.
+
+## Remote SSH
+
+Use the CLI OAuth SSH flow for normal VM access. It handles login, token refresh,
+key generation, public-key installation, SSH configuration, and the tunnel.
+Use Azure, daemon APIs, Datadog, or direct host administration when the user asks
+for fleet, VM, image, daemon, or control-plane debugging, or when debugging the
+CLI path itself.
+
+Place remote command arguments after `--` so their flags, including `--help`,
+reach the remote process.
+
+### Connect through a conversation
+
+When you have a conversation ID and its workspace, let the CLI discover the VM:
+
+```bash
+runneth ssh --workspace <workspace-id> --conversation <conversation-id> -- 'pwd'
+runneth ssh stdio --workspace <workspace-id> --conversation <conversation-id>
+```
+
+This resolves the conversation's public SSH target through the API. Do not
+combine `--conversation` with `--target`, `--host`, or `--ssh-url`. Use saved
+targets below when you already have a VM host or SSH app URL.
+
+### Saved 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 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 ssh target add <target-name> \
+  --ssh-url https://<full-host>/runneth/ssh \
+  --default
+```
+
+List and select targets:
+
+```bash
+runneth ssh target list
+runneth ssh target use <target-name>
+```
+
+Import multiple targets from JSON:
+
+```bash
+runneth 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"
+    }
+  ]
+}
+```
+
+### Run a command or shell
+
+Run a one-off command:
+
+```bash
+runneth ssh --target <target-name> -- 'whoami && pwd && hostname'
+```
+
+Open an interactive shell:
+
+```bash
+runneth ssh --target <target-name>
+```
+
+The CLI reads the target VM's authenticated `/runneth/ssh/api` metadata before
+connecting, independently of app catalog health. VMs
+that advertise `runneth-ssh-v1` authorize one WebSocket upgrade and stream SSH
+bytes over that full-duplex socket. Older VMs continue through the HTTPS
+tunnel. Transport selection is automatic.
+
+For agents that need to run multiple operations without reconnecting, keep one
+authenticated SSH session open with stdio mode.
+
+### Persistent SSH session
+
+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 ssh stdio --target <target-name>
+```
+
+Wait for the `ready` event. Send one complete JSON request per line on stdin,
+followed by a newline, and read one JSON event per line on stdout.
+
+One-off command:
+
+<!-- prettier-ignore -->
+```jsonl
+{"id":"1","method":"exec","params":{"command":"pwd && ls -la","timeoutMs":600000}}
+```
+
+Spawn a persistent process and write to it:
+
+```jsonl
+{"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:
+
+```jsonl
+{"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. Wait for `started`, then use the
+same `id` for that process's `stdin`, `signal`, and `close` requests. Match output
+and `exit` events by `id`. A successful remote command has exit `code: 0` and
+`ok: true`; `ok: true` alone does not mean the command succeeded.
+
+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
+
+SSH 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 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.
+
+## Refresh installed skills
+
+After updating the CLI, run:
+
+```bash
+runneth skills install --agent all
+```
+
+This replaces the Runneth skill for both Claude Code and Codex with the copy
+bundled in that CLI version. Use `--agent claude` or `--agent codex` to update
+only one. Updating the CLI alone does not refresh installed skills. Start a new
+agent session to load the refreshed instructions.
+
+## Troubleshooting
+
+Common failures:
+
+- `401` or `403`: OAuth is missing, expired, or the user does not have access to the VM organization.
+- Capability request failure: verify the authenticated `/runneth/ssh/api` endpoint is reachable and returns valid SSH metadata. Discovery allows 70 seconds for authorization and response delivery.
+- `503`: public app routing, daemon health, runtime app startup, or the tunnel limit is blocking access.
+- Slow interactive I/O on a VM without the WebSocket capability: the CLI uses the HTTPS polling transport for that VM.
+- Slow interactive I/O over WebSocket: inspect public network latency and VM load.
+- Unexpected idle disconnects: inspect public app and daemon health plus WebSocket heartbeat failures.