@ashrlabs/ashr 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
+# ashr
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Ashr terminal interface. By default it connects to the same hosted Manifold
+tasks, chats, files, skills, memory, command queue and approvals as the browser.
+Use `--local` for the separate agent that runs in your repository on your machine.
+
+## Install
+
+```
+npm i -g @ashrlabs/ashr  # then run: ashr
+npx @ashrlabs/ashr       # try it without installing
+```
+
+Needs Node 22.19 or newer.
+
+## Hosted Manifold
+
+```
+ashr                         sign in (first run only) and open the hosted workspace
+ashr --task support          select a task
+ashr --task support --chat ID open the same chat as the browser
+ashr --service               require MANIFOLD_API_KEY or a saved key; never opens a browser
+ashr login                   sign in through the browser and exit
+ashr login --key ask_…       save a service key instead
+ashr logout                  forget the saved sign-in
+```
+
+On first launch `ashr` opens the dashboard's `/terminal` page. Sign in, pick
+the organization, and click **Connect terminal**. The dashboard mints a key for
+this terminal (labelled `Terminal · <hostname>` under API keys) and hands it
+back once to a loopback listener. The terminal saves it to
+`~/.ashr/credentials.json` (mode 600), and you can close the tab. Later launches
+open the workspace directly. If the key is revoked, `ashr` asks you to sign in
+again. If the browser doesn't open, use the printed URL.
+
+`--api-url`/`MANIFOLD_API_URL` and `--dashboard-url`/`MANIFOLD_DASHBOARD_URL`
+select matching deployments. `MANIFOLD_API_KEY` or `--key` override the saved
+sign-in.
+
+`/account` shows who the terminal is signed in as. `/org` opens organization
+settings in the browser. `/login` signs in again (for example to switch
+organization) and clears the old task/chat selection. `/logout` forgets the
+saved key.
+
+Use `/help` for the complete command reference. Hosted controls include:
+
+- `/tasks`, `/task NAME`, `/chats SEARCH`, `/new NAME`, `/open ID`, `/rename NAME`, `/fork NAME [SEQ]`.
+- `/model PROVIDER/MODEL`, `/thinking LEVEL`, `/compact`, `/steer TEXT`, `/next TEXT`, `/queue`, `/stop`, `/approve ID`, `/reject ID`.
+- `/files`, `/view PATH`, `/diff PATH`, `/download PATH LOCAL_FILE`, `/export LOCAL_FILE`.
+- `/skills`, `/skill import LOCAL_FOLDER`, `/skill toggle NAME`, `/skill invoke NAME`, `/memory QUERY`.
+- `/pipelines`, `/sources`, `/datasets`, `/evals`, `/benchmarks`, `/experiments`, `/models`, `/monitoring`, `/interactions`, `/uploads`, `/artifacts`, `/serving`, `/sdk`.
+
+Hosted `!COMMAND` runs in the hosted workspace; `!!COMMAND` excludes its output
+from model context. Escape stops active hosted work or pauses a local transfer.
+Ctrl-C stops active hosted work; when idle it disconnects. `/quit` disconnects
+while leaving hosted jobs running. `/pending` and `/retry` recover uncertain
+submissions without changing their request IDs. Upload receipts support resume.
+
+Dashboard writes require the command's explicit `--confirm` flag. The terminal
+covers serving, training and evaluation environments. Organization, member and
+API-key administration stay in the dashboard; `/org` opens it.
+
+## Local model keys
+
+ashr uses your own model provider key. Set it in your shell, or store it once:
+
+```
+export ANTHROPIC_API_KEY=sk-…          # or OPENAI_API_KEY, GEMINI_API_KEY
+ashr login --provider anthropic        # stores it in ~/.ashr/credentials.json (readable only by you)
+```
+
+A key set in your shell always wins over a stored one. Keys are never passed to the commands the agent runs.
+
+`ashr login` opens a human Manifold workspace. It does not store a provider key.
+
+## Using the local agent
+
+```
+ashr --local         new session in this repo
+ashr -c              continue the latest session here
+ashr -r              pick a session to resume
+ashr -p "<prompt>"   one turn, printed (for scripts and CI)
+```
+
+While the agent works, Enter steers it, Option-Enter queues a message for when it finishes, and Esc stops it. When an approval is waiting, `a` approves, `r` rejects and `A` always allows; Tab switches to the input box so you can type a message instead. Ctrl-O shows the full output of the last tool. Type `/` for commands: `/usage`, `/permissions` (and `/permissions remove <rule>`), `/resume`, `/fork`, `/rewind`, `/compact`, `/model`, `/mode`, `/add-dir`, `/help`.
+
+## Local permissions
+
+Like pi, ashr runs the agent's tools without asking by default (Auto mode). It still stops and asks before:
+
+- anything that spends money on Manifold (data copies, GPU runs, evaluations, deploys)
+- reading or writing outside the repo, including a shell redirect to a file outside it
+- `git push`, force operations, `sudo`, and running a downloaded script
+
+Outside the repo covers shell commands too: a command that names a path outside the repo (for example `cat ~/.ssh/id_rsa` or `--out=/tmp/x`) asks in every mode, unless it's a directory you added with `/add-dir` or a device file under `/dev`.
+
+Prefer to approve more? Shift-Tab cycles the mode:
+
+| Mode | Runs without asking | Asks first |
+|---|---|---|
+| auto (default) | everything inside the repo | the stops above |
+| ask | reading and read-only commands (`ls`, `cat`, `grep`, `git log` …) | edits, other shell commands, connector tools |
+| edit | reads, read-only commands and edits inside the repo | other shell commands, connector tools |
+
+In ask and edit mode, changes to the repo's own `.git/` files always ask, since git settings there can run commands.
+
+Set your own default with `"defaultMode": "ask"` in `~/.ashr/settings.json`. A repo's committed settings can make you stricter but never move you to Auto.
+
+These stops catch an agent's honest mistakes. They are not a security boundary: in Auto the agent can run any program, and a program can do anything your user account can. For untrusted repos, run ashr in a container or a separate user account.
+
+Answering `A` on an approval saves an "always allow" rule. Rules live in three files; any deny rule wins:
+
+- `~/.ashr/settings.json` — yours, everywhere
+- `.ashr/settings.json` — the team's, committed
+- `.ashr/settings.local.json` — yours, for this repo (gitignored; "always allow" writes here)
+
+```json
+{ "permissions": { "allow": ["shell:pytest *", "edit:src/**"], "deny": ["shell:git push *", "edit:.env*"] } }
+```
+
+A repo's committed rules apply only after you trust them; ashr asks the first time and again whenever they change.
+
+In print mode nothing can be approved interactively: a run that needs approval exits 3 and names the rule to add, for example `--allow "edit:a.txt"` (one `--allow` per part of a compound shell command), or the mode that would allow it (`--mode edit|auto` for edits, `--mode auto` otherwise). Actions that ask in every mode (spending, outside the repo, dangerous shell commands) need an interactive run.
+
+## Where local things live
+
+- Sessions: `~/.ashr/sessions/<org>/<repo>/` (one JSONL file per session, plus full tool outputs and file snapshots for `/fork` and `/rewind`)
+- `ASHR.md` in your repo and `~/.ashr/memory.md` are read into every session.
+- Set `ASHR_HOME` to keep all of this somewhere else.
+
+## Parity checks
+
+Run `npm test`, `npm run typecheck`, and `npm run build` from `cli/`.
+`npm run test:parity` starts a disposable SQLite backend and verifies both
+client contracts against real routes. Set `MANIFOLD_TEST_PYTHON` to a Python
+environment with the repository's backend test dependencies installed.
+
+`npm run test:parity:browser` builds the actual React/TUI fixtures, starts
+loopback-only servers on ports 3192, 3194 and 3195, then runs Chromium acceptance
+and saves video/screenshots under `.artifacts/parity/`. It needs Playwright and
+its Chromium browser installed; `PLAYWRIGHT_MODULE` may point to an existing
+Playwright ESM entry. It refuses occupied fixture ports and stops its own servers.
+
+These tests simulate Clerk identity and model/compute responses explicitly.
+They do not verify deployed Clerk configuration, paid compute or external
+storage. See `docs/terminal-parity-audit.md` for coverage and remaining live checks.