@joeyshi12/casper 0.6.0 → 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joey Shi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+<p align="center">
+<img src="/assets/banner.svg" alt="Casper banner" width="100%"/>
+</p>
+
+<p align="center">
+<a href="https://github.com/joeyshi12/casper/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="License: MIT"/></a>
+<a href="https://www.npmjs.com/package/@joeyshi12/casper"><img src="https://img.shields.io/npm/v/@joeyshi12/casper.svg" alt="npm"/></a>
+<a href="https://github.com/joeyshi12/casper/actions/workflows/test.yml"><img src="https://github.com/joeyshi12/casper/actions/workflows/test.yml/badge.svg" alt="Tests"/></a>
+<a href="https://github.com/joeyshi12/casper/actions/workflows/publish.yml"><img src="https://github.com/joeyshi12/casper/actions/workflows/publish.yml/badge.svg" alt="Publish"/></a>
+</p>
+
+A web client for `kiro-cli`, over its Agent Client Protocol (ACP). Start a long
+Kiro task and it keeps running server-side; on reconnect the client replays
+exactly what it missed.
+
+## Features
+
+- **Sessions** you can create, search, rename and delete. Live ones run in a
+  bounded process pool; idle ones go dormant and resume on demand.
+- **Per-session model and agent**, from the live model list and kiro's agents.
+- **Rich rendering** - Markdown, Mermaid, syntax-highlighted code, and MCP tool
+  calls with their status, input and output.
+- **File browser** for the session's workspace, with previews for text, images
+  and PDFs.
+- **Observability** - credits spent, context-window usage, turn duration.
+- **PWA** - installable, responsive, reconnects when the network returns.
+
+## Install
+
+Needs Node 24+ (Casper keeps its state in SQLite via the built-in `node:sqlite`)
+and [`kiro-cli`](https://kiro.dev) installed and logged in — Casper is a client
+for it, so nothing works without it.
+
+```bash
+npm install -g @joeyshi12/casper
+casper
+```
+
+The first run generates an access token, prints it in a bordered block, and drops
+the `casper` agent into `~/.kiro/agents`. Open the printed URL and paste the token.
+
+To survive reboots, install the systemd user service:
+
+```bash
+casper service install
+```
+
+systemd is optional. Without it, start Casper however you prefer — your own init
+system, `nohup casper &`, tmux.
+
+| Command | |
+|---|---|
+| `casper` | Run the server in the foreground |
+| `casper token` | Print the access token |
+| `casper reset-token [value]` | Set a new token and sign every device out |
+| `casper doctor` | Check kiro-cli, settings, data directory and web app |
+| `casper service install` | Run as a systemd user service |
+| `casper service uninstall` | Remove the service, keeping settings and sessions |
+| `casper service status` | Show the service status |
+
+To update, `npm install -g @joeyshi12/casper@latest`. Re-run
+`casper service install` afterwards if you use the service: the unit records
+absolute node and package paths, and both move on upgrade. Your token and sessions
+survive.
+
+To remove it:
+
+```bash
+casper service uninstall
+npm uninstall -g @joeyshi12/casper
+rm -rf ~/.casper ~/.config/casper   # only if you want sessions and settings gone too
+```
+
+## Configuration
+
+Settings live in `~/.config/casper/config.json` (or `$XDG_CONFIG_HOME/casper/`),
+written `0600` because it holds the token:
+
+```json
+{
+  "port": 4319,
+  "defaultCwd": "/home/you/projects",
+  "fileRoot": "/home/you",
+  "defaultAgent": "casper"
+}
+```
+
+A missing or malformed file is ignored with a warning rather than failing startup,
+and unrecognised keys are reported so a typo doesn't pass silently.
+
+Every setting also works as an environment variable, and **the environment wins**,
+which is handy for containers and one-off runs. Two are environment-only:
+`CASPER_DATA_DIR`, because it says where data lives and so can't be read from
+inside it, and `CASPER_WEB_DIST`, which is install layout rather than a preference.
+
+| Variable | Config key | Default | |
+|---|---|---|---|
+| `HOST` | `host` | `0.0.0.0` | Bind address |
+| `PORT` | `port` | `4319` | Server port |
+| `CASPER_TOKEN` | `token` | _(generated)_ | Entered once at login, exchanged for a per-device cookie |
+| `CASPER_SESSION_TTL_SECONDS` | `sessionTtlSeconds` | `604800` | Device-login lifetime, slid forward on activity |
+| `KIRO_BIN` | `kiroBin` | `kiro-cli` | Path to the kiro-cli binary |
+| `DEFAULT_CWD` | `defaultCwd` | cwd | Working directory for new sessions |
+| `DEFAULT_AGENT` | `defaultAgent` | `kiro_default` | Agent for new sessions |
+| `CASPER_FILE_ROOT` | `fileRoot` | `/` | Confines the file browser. Defaults to everything the server can read; narrow it to keep authenticated users out of system files |
+| `MAX_LIVE_SESSIONS` | `maxLiveSessions` | `6` | Concurrent live kiro processes |
+| `CASPER_DATA_DIR` | _(env only)_ | `~/.casper` | Where `casper.db` lives |
+| `CASPER_WEB_DIST` | _(env only)_ | beside the bundle | Built web app to serve |
+
+Beyond your LAN, put a TLS-terminating reverse proxy in front of
+`http://127.0.0.1:4319`, forwarding WebSocket upgrades with a long read timeout for
+lengthy turns. PWA install and reliable reconnects need HTTPS.
+
+## Security
+
+Casper launches kiro with `--trust-all-tools`, so unattended runs never block on
+approvals — the agent can run commands and write files without asking. Treat access
+to Casper as equivalent to a shell on the machine.
+
+The token is 24 random bytes, generated for you and exchanged at login for a
+per-device cookie; only its hash is stored. Comparison is constant-time, `/api/login`
+allows ten failures per quarter hour per address before answering 429, and the
+settings file and database are `0600`.
+
+## Develop
+
+```bash
+npm install
+CASPER_TOKEN=dev npm run dev   # server and web dev servers together
+npm test
+npm run e2e                    # prompt, disconnect mid-turn, reconnect, replay
+```
+
+The repo is an npm workspace: `shared/` for types, `web/` for the React app, and
+`server/`, which is the package published to npm. `npm run build` bundles the server
+with esbuild and copies the built web app in beside it.

package/dist/server.js

@@ -6746,7 +6746,7 @@ var program = new Command();
 // server/src/cli/program.ts
 init_paths();
 init_settings();
-var VERSION = true ? "0.6.0" : "dev";
+var VERSION = true ? "0.6.1" : "dev";
 async function bootstrap() {
   const file = configFilePath();
   const settings = readSettings(file);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joeyshi12/casper",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Web client for kiro-cli over the Agent Client Protocol",
   "license": "MIT",
   "author": "Joey Shi",