@stratusagent/cli 0.3.0 → 0.6.0

package/README.md

@@ -2,6 +2,8 @@
 
 Stratus Agent CLI — create always-on agents that get smarter over time. Quickly set up Stratus Agent on your machine, create new agents, connect AI providers, and configure channels.
 
+<img width="2400" height="1004" alt="image" src="https://github.com/user-attachments/assets/ef16d58f-694c-406e-b201-aee61b093753" />
+
 ## Install
 
 Needs **Node.js 22.13+** — the gateway's session store uses `node:sqlite`, which runs unflagged from 22.13. On the 23.x line that landed separately, in **23.4**, so 23.0–23.3 are too old despite the higher number. Every package declares the range, and the CLI checks it at startup, so an unsupported Node gets a line naming what it needs rather than a missing-builtin error later on.
@@ -27,6 +29,96 @@ npm install -g @stratusagent/channel-slack
 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:
@@ -63,6 +155,7 @@ stratus run --provider anthropic --model claude-opus-5 "hello"
 stratus run --prompt "use the echo tool" --format json
 stratus serve                          # stratusd: the whole roster, always on
 stratus serve --idle-timeout 120 --no-events
+stratus serve --approvals remote       # ask a human in Slack instead of refusing
 stratus service install                # keep stratusd running under launchd/systemd
 stratus service status
 stratus logs -f                        # what the daemon has been doing
@@ -89,15 +182,22 @@ riskier is refused, with a line in the log saying which agent wanted what:
 09:14:36  —           warning: ava: shell.run is gated and nobody is available to approve it (session slack:ava:…)
 ```
 
-That is the honest behavior behind a service manager, where there is no
-terminal to prompt on. Asking a human through Slack and resuming the turn on
-their answer is the next piece of this; until then the daemon refuses rather
-than assumes.
+That is the honest default behind a service manager, where there is no
+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
@@ -108,7 +208,278 @@ calls face this policy again under their allowlist, and the chain is depth
 bounded.
 
 `stratus chat` and `stratus run` are unaffected: at a terminal, `--approvals`
-works exactly as before.
+works exactly as before (`always`, `ask`, `never`).
+
+### Asking a human: remote approval
+
+In `remote` mode a gated call does not fail — the turn parks, the request is
+posted to Slack with **Allow once**, **Always allow**, and **Deny**, and the
+turn resumes on the answer. The question goes to the thread the turn is
+happening in, so whoever is talking to the agent sees it where they already
+are.
+
+Turn it on for the daemon with `--approvals remote`, or in
+`~/.stratus/config.json` so the installed service picks it up too:
+
+```jsonc
+{
+  "approvals": {
+    "mode": "remote",              // headless (default) or remote
+    "timeoutMs": 900000,           // unanswered after 15 minutes → denied (max 2147483647)
+    "slackApprovers": ["U01OPS"],  // who may decide, for every agent
+    "slackChannel": "C07OPS",      // where to ask when the turn isn't in Slack
+    "agents": {
+      "ava": { "slackApprovers": ["U01DYLAN"] }
+    }
+  }
+}
+```
+
+An agent inherits the top-level route key by key, so `ava` above asks her own
+approver in the shared `C07OPS` fallback channel. An explicit
+`"slackApprovers": []` on an agent excludes it from the default list — that
+agent's gated calls are then denied outright — while omitting the key
+inherits.
+
+**Only a config you chose is allowed to set this block** — `--config`,
+`STRATUS_CONFIG`, or the global `~/.stratus/config.json`. An auto-discovered
+project-local `stratus.config.json` outranks the global one for provider
+settings, but it can be checked into any repository, and appointing the
+people who may authorize an agent's tool calls is not something a clone gets
+to do. Its `approvals` block is ignored, with a warning naming the file.
+
+Three things are worth knowing before you turn it on:
+
+- **Approvers are people, not places.** Posting into a channel does not make
+  everyone in it an approver: each request is bound to the ids configured for
+  that agent, and anyone else's click is refused with a notice only they see.
+  The request stays open for someone who may actually answer it. This matters
+  most for **Always allow**, which widens what the agent may do unattended.
+- **An agent with no approver configured is denied immediately**, not left to
+  time out — `remote` with nobody listed behaves exactly like `headless`. If
+  no channel can ask for an agent at all (no Slack tokens for it, or
+  `@stratusagent/channel-slack` not installed) there is nothing to render the
+  request, so its gated calls wait out the timeout instead. The daemon names
+  those agents at startup, rather than leaving you to find out at 3am:
+
+  ```text
+  approvals: remote — gated calls are parked and asked in Slack (approvers set for ava)
+  ```
+- **A parked turn survives a restart.** The daemon records what has not run
+  before it asks, so an approval outstanding when it stops is finished when
+  it starts again — the question is re-asked in Slack, the call runs on the
+  answer, and anything queued behind it still runs too. The re-asked request
+  keeps the window it started with rather than getting a fresh one, and a
+  wait that has already used up its `timeoutMs` is denied instead of
+  re-asked: downtime is not a reason to extend a security decision.
+- **A turn that was mid-flight is failed, not left hanging.** Parking is the
+  one state a restart can resume from — a turn that stopped anywhere else
+  (waiting on the provider, inside a tool, or on an approval asked by an
+  agent billed through a Claude subscription, which is deliberately not
+  checkpointed) cannot be. Those sessions come back marked `failed`, with a
+  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. 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
+approving something you cannot see. Arguments are escaped (a model-written
+argument cannot mention or broadcast to the workspace through the prompt)
+and truncated with a visible notice when they are long.
+
+Requests are also denied — visibly, with a reason — when they expire, when
+the turn is cancelled, when the daemon shuts down, and when a turn reaches a
+gated call while the daemon is already stopping. Every one of those retracts
+the buttons in Slack, so a message never keeps offering a decision with
+nowhere to land.
+
+`timeoutMs` is capped at 2147483647 (~24.8 days), the longest timer Node can
+hold. A larger value is rejected at startup rather than accepted: it would
+not wait longer, it would expire every approval almost immediately.
+
+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.
 
 ## Always on
 
@@ -286,6 +657,44 @@ You are a sharp, warm generalist. Answer first, explain second...
 
 Agents remember: facts saved with the built-in `memory.remember` tool persist to `~/.stratus/memory.jsonl`, keyed to the agent — so the Ava you talk to tomorrow remembers today, from any directory.
 
+**Ids are not labels.** Frontmatter may set `id:` explicitly, and it keys the
+agent's sessions, memory, credentials, Slack tokens, and every per-agent path
+on disk. So it has to stay one path segment, and one ordinary map key: an id
+may not start with a dot or contain a slash, a backslash, a control
+character, or leading or trailing whitespace, and it may not be a name every
+object already answers to (`__proto__`, `constructor`, `toString`). Anything that would leave its directory is rejected when the soul
+loads rather than quietly cleaned up — `id: ../../escape` is refused, not
+rewritten to `escape`.
+
+Anything else is yours. An id like `Ava_1` or `team.alpha` is unusual but
+harmless, and it is already keying that agent's sessions and sign-ins, so it
+is left exactly as written. Omit `id:` and one is derived from the name as a
+plain slug (`ava`); a generated agent's id is also capped at 64 characters,
+but a slug derived from a name you chose is used whole, because shortening
+an id moves the agent it belongs to.
+
+Creating an agent checks the id against every id the served roster holds,
+not against the filenames on disk: what the roster files *declare* (a soul
+at `renamed.md` can declare `id: ava`), the configured default soul even
+when its file lives elsewhere, and the reserved `stratus`. A new agent gets
+a suffixed id (`ava-3f9c`) rather than one that would collide. Its name
+stays the one you chose.
+
+**Two souls cannot share an id.** That is not two agents; it is one agent
+whose memory and sign-ins belong to whichever file sorted first. The roster
+refuses to load and names both files, `stratus serve` will not start,
+`stratus doctor` reports it, and `stratus setup` → Channels offers no
+agents at all — nothing is servable while the roster is ambiguous, so
+connecting a Slack app would configure something that cannot run. Neither
+command offers to clear "unmatched" Slack tokens in that state either: a
+roster that would not load cannot prove which ids are missing, and the
+tokens at risk belong to agents that are perfectly fine. (An unreadable *single* soul still degrades to a
+warning — one broken file never takes the team down. A collision has no
+correct winner, which is the difference.) The built-in `stratus` id is
+reserved: souls claiming it are skipped — including two of them, since
+neither was going to get the id, so their agreeing on it is not a collision
+to refuse over.
+
 ## Options
 
 | Flag | Purpose |
@@ -295,19 +704,30 @@ Agents remember: facts saved with the built-in `memory.remember` tool persist to
 | `--model` | Model for real providers (anthropic default: `claude-opus-5`) |
 | `--base-url` | Override the provider API base URL |
 | `--config <file>` | Load settings from a specific config file |
-| `--approvals` | Tool approval mode: `always`, `ask`, or `never` |
+| `--approvals` | `run`/`chat`: tool approval mode — `always`, `ask`, or `never`. `serve`: how the daemon reaches a human — `headless` (refuse gated calls) or `remote` (ask in Slack); overrides the config's `approvals.mode` |
 | `--max-turns` | Max provider turns per run (default 8) |
 | `--format` | `text` or `json` |
 | `--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.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { type JsonValue, type Session, type StratusEvent } from '@stratusagent/core';
-import { type CredentialProviderName, type RuntimeConfig, type StratusProviderName } from '@stratusagent/state';
+import { type CredentialProviderName, type RuntimeSelection, type RuntimeConfig, type StratusProviderName } from '@stratusagent/state';
 import { type ServiceRunner } from './service.ts';
 export { installService, launchdPlist, readServiceStatus, servicePlatform, serviceUnitPath, startService, stopService, systemdUnit, uninstallService, SERVICE_LABEL, type ServiceRunner, type ServiceStatus, } from './service.ts';
 export { createLogWriter, currentLogPosition, truncateRedirectLogs, formatLogRecord, parseLogLines, readRecentRecords, tailLog, type LogRecord, } from './logs.ts';
@@ -50,7 +50,17 @@ export interface ParsedRunCommand {
 export interface ParsedDashboardCommand {
     command: 'dashboard';
     port?: number;
-    host: string;
+    /**
+     * Present only when `--host` was actually given.
+     *
+     * A defaulted string here would be indistinguishable from an explicit
+     * `--host 127.0.0.1`, and the two mean opposite things when a trusted
+     * config says `api.host: "0.0.0.0"`: absent means "let the config decide",
+     * while explicit means "bind loopback, whatever the config says". Collapsing
+     * them exposed the API on every interface to an operator who had just asked
+     * for the opposite.
+     */
+    host?: string;
     openBrowser: boolean;
 }
 export interface ParsedSetupCommand {
@@ -78,6 +88,14 @@ export interface ParsedChatCommand {
 export interface ParsedAgentsCommand {
     command: 'agents';
     format: 'text' | 'json';
+    /**
+     * Ask a running gateway instead of resolving locally. The first
+     * remote-consuming command: the same listing, rendered from the control
+     * API's answer rather than from this machine's files.
+     */
+    gateway?: string;
+    /** Bearer token override, for a gateway whose token file is not local. */
+    token?: string;
 }
 export interface ParsedDoctorCommand {
     command: 'doctor';
@@ -102,24 +120,29 @@ export interface ParsedLogsCommand {
     sessionId?: string;
     format: 'text' | 'json';
 }
+export type ServeApprovalMode = 'headless' | 'remote';
 export interface ParsedServeCommand {
     command: 'serve';
     configPath?: string;
+    /** Overrides `approvals.mode` in the config file. */
+    approvals?: ServeApprovalMode;
     /** Watchdog idle timeout in milliseconds. 0 disables. */
     idleTimeoutMs?: number;
     events: boolean;
     /** Write the structured log to ~/.stratus/logs. Defaults to true. */
     logToFile?: boolean;
+    /** Serve the control API. Defaults to true when the package is installed. */
+    api?: boolean;
+    /** Overrides `api.port` in the config file. */
+    apiPort?: number;
+    /** Overrides `api.host` in the config file. */
+    apiHost?: string;
 }
 export interface ParsedHelpCommand {
     command: 'help';
 }
 export type ParsedCommand = ParsedRunCommand | ParsedChatCommand | ParsedDashboardCommand | ParsedSetupCommand | ParsedAgentNewCommand | ParsedAgentsCommand | ParsedDoctorCommand | ParsedLogsCommand | ParsedServiceCommand | ParsedServeCommand | ParsedHelpCommand;
-export interface DashboardServerHandle {
-    url: string;
-    close: () => Promise<void>;
-}
-export declare const CLI_VERSION = "0.3.0";
+export declare const CLI_VERSION = "0.6.0";
 /**
  * The range every package declares in its `engines` field. Two floors, not
  * one: `node:sqlite` was unflagged in 22.13.0 on the LTS line and in 23.4.0
@@ -141,11 +164,20 @@ export declare const SUPPORTED_NODE_RANGE = ">=22.13 <23 || >=23.4";
  * string is a bad reason to refuse to run.
  */
 export declare const unsupportedNodeMessage: (version: string) => string | undefined;
-declare const HELP_TEXT = "Stratus Agent CLI\n\nUsage:\n  stratus setup\n  stratus chat\n  stratus chat --soul ./examples/souls/ava.md\n  stratus run --prompt \"Use the demo tool\"\n  stratus run \"Say hello\"\n  ANTHROPIC_API_KEY=... stratus run --provider anthropic \"Say hello\"\n  stratus run --soul ./examples/souls/ava.md \"Say hello\"\n  echo \"Use the echo tool\" | stratus run --stdin\n  STRATUS_PROVIDER=openai OPENAI_API_KEY=... stratus run \"Say hello\"\n  stratus run --config ./stratus.config.json --provider openai \"Say hello\"\n  stratus agents\n  stratus doctor\n  stratus service install\n  stratus service status\n  stratus logs -f\n  stratus logs --agent ava -n 200\n  stratus dashboard\n  stratus dashboard --port 4123 --host 0.0.0.0 --no-open\n\nCommands:\n  setup            Menu-driven onboarding: pick a provider, sign in (Claude\n                   subscription or API key), create your agent, connect it to\n                   Slack, and test it \u2014 settings go to ~/.stratus/config.json,\n                   sign-ins and channel tokens to ~/.stratus/credentials.json\n                   (0600)\n  chat             Talk with your agent \u2014 the conversation persists across turns\n                   and remembered facts accumulate; /exit or Ctrl+C to leave\n  run              Execute one local Stratus Agent session\n  serve            Run stratusd, the always-on gateway: durable sessions, the\n                   whole roster live at once (each agent on its own provider),\n                   delegation, and a watchdog \u2014 Ctrl+C / SIGTERM drains cleanly\n                   (--idle-timeout <seconds>, --no-events, --no-log-file,\n                   --config <path>); everything it says is also written to\n                   ~/.stratus/logs, which \"stratus logs\" reads\n  service          Keep stratusd running under launchd (macOS) or systemd\n                   (Linux): install, uninstall, status, start, stop.\n                   Installing starts it now and at every login\n                   (--no-login installs without the login trigger,\n                   --config <path> pins the daemon to one config file)\n  logs             Read the daemon's log from any terminal: -f to follow,\n                   -n <count> for backlog, --agent / --session to filter,\n                   --format json for the raw records\n  agent new        Create an agent identity (generates a human-ish name + avatar theme)\n  agents           List your agents: who they are, where their souls live, what\n                   they run on, what they remember (also: stratus agent list)\n  doctor           Show what a run would use right now \u2014 provider, model, soul \u2014\n                   and which file or environment variable decided each, then\n                   flag anything that would surprise you (--format json)\n  dashboard        Start the local Stratus Agent dashboard and open it in your browser\n  help             Show this help message\n\nAgent options:\n  --name           Agent name (omit to have one generated)\n  --instructions   The agent's persona/instructions\n  --format         Output format for agent new: text, json, or soul (a ready-to-edit soul file)\n\nOptions:\n  --prompt, -p     Prompt to send to the local agent loop\n  --stdin          Read the prompt from stdin\n  --provider       Provider to use: anthropic, openai, or demo\n  --model          Model name for real providers (anthropic default: claude-opus-5, openai default: gpt-4.1-mini)\n  --base-url       Override the provider API base URL\n  --soul           Run as the agent defined by a soul file (markdown + frontmatter, see examples/souls)\n  --config         Config file path (run: load settings from it, setup: write it)\n  --format         Output format: text or json (default: text)\n  --no-events      Hide event-by-event progress lines in text mode\n  --approvals      Tool approval mode: always, ask, or never (default: always)\n  --max-turns      Maximum provider turns per run (default: 8)\n  --port           Dashboard port, defaults to an open local port\n  --host           Dashboard host (default: 127.0.0.1)\n  --no-open        Do not open the browser automatically\n  --help, -h       Show this help message\n\nConfig file:\n  The CLI looks for ./stratus.config.json first, then a path from --config / STRATUS_CONFIG,\n  then the global ~/.stratus/config.json written by `stratus setup`.\n  A \"soul\" key (or STRATUS_SOUL) points at a soul file so every run uses that agent.\n  Legacy STRATUSCLAW_* env vars and stratusclaw.config.json are still supported for compatibility.\n\nSoul files:\n  A soul file is markdown with frontmatter (name, provider, model, tools, credentials)\n  followed by the agent's persona in prose. See examples/souls/ava.md.\n";
+declare const HELP_TEXT = "Stratus Agent CLI\n\nUsage:\n  stratus setup\n  stratus chat\n  stratus chat --soul ./examples/souls/ava.md\n  stratus run --prompt \"Use the demo tool\"\n  stratus run \"Say hello\"\n  ANTHROPIC_API_KEY=... stratus run --provider anthropic \"Say hello\"\n  stratus run --soul ./examples/souls/ava.md \"Say hello\"\n  echo \"Use the echo tool\" | stratus run --stdin\n  STRATUS_PROVIDER=openai OPENAI_API_KEY=... stratus run \"Say hello\"\n  stratus run --config ./stratus.config.json --provider openai \"Say hello\"\n  stratus agents\n  stratus agents --gateway http://127.0.0.1:4123\n  stratus doctor\n  stratus service install\n  stratus service status\n  stratus logs -f\n  stratus logs --agent ava -n 200\n  stratus dashboard\n  stratus dashboard --port 4123 --host 0.0.0.0 --no-open\n\nCommands:\n  setup            Menu-driven onboarding: pick a provider, sign in (Claude\n                   subscription or API key), create your agent, connect it to\n                   Slack, and test it \u2014 settings go to ~/.stratus/config.json,\n                   sign-ins and channel tokens to ~/.stratus/credentials.json\n                   (0600)\n  chat             Talk with your agent \u2014 the conversation persists across turns\n                   and remembered facts accumulate; /exit or Ctrl+C to leave\n  run              Execute one local Stratus Agent session\n  serve            Run stratusd, the always-on gateway: durable sessions, the\n                   whole roster live at once (each agent on its own provider),\n                   delegation, and a watchdog \u2014 Ctrl+C / SIGTERM drains cleanly\n                   (--idle-timeout <seconds>, --approvals <headless|remote>,\n                   --no-events, --no-log-file, --config <path>); everything it\n                   says is also written to ~/.stratus/logs, which\n                   \"stratus logs\" reads. With @stratusagent/control-api\n                   installed it also serves the HTTP + WebSocket control API\n                   on 127.0.0.1:4123 (--no-api, --api-host, --api-port, or\n                   the config file's \"api\" block)\n  service          Keep stratusd running under launchd (macOS) or systemd\n                   (Linux): install, uninstall, status, start, stop.\n                   Installing starts it now and at every login\n                   (--no-login installs without the login trigger,\n                   --config <path> pins the daemon to one config file)\n  logs             Read the daemon's log from any terminal: -f to follow,\n                   -n <count> for backlog, --agent / --session to filter,\n                   --format json for the raw records\n  agent new        Create an agent identity (generates a human-ish name + avatar theme)\n  agents           List your agents: who they are, where their souls live, what\n                   they run on, what they remember (also: stratus agent list).\n                   --gateway <url> asks a running daemon instead of resolving\n                   locally, authenticating with ~/.stratus/gateway-token\n                   (override with --token or STRATUS_GATEWAY_TOKEN)\n  doctor           Show what a run would use right now \u2014 provider, model, soul \u2014\n                   and which file or environment variable decided each, then\n                   flag anything that would surprise you (--format json)\n  dashboard        Open the web dashboard: finds a running daemon (or starts one),\n                   mints a single-use sign-in link, and opens your browser at it.\n                   Needs @stratusagent/control-api and @stratusagent/dashboard\n  help             Show this help message\n\nAgent options:\n  --name           Agent name (omit to have one generated)\n  --instructions   The agent's persona/instructions\n  --format         Output format for agent new: text, json, or soul (a ready-to-edit soul file)\n\nOptions:\n  --prompt, -p     Prompt to send to the local agent loop\n  --stdin          Read the prompt from stdin\n  --provider       Provider to use: anthropic, openai, or demo\n  --model          Model name for real providers (anthropic default: claude-opus-5, openai default: gpt-4.1-mini)\n  --base-url       Override the provider API base URL\n  --soul           Run as the agent defined by a soul file (markdown + frontmatter, see examples/souls)\n  --config         Config file path (run: load settings from it, setup: write it)\n  --format         Output format: text or json (default: text)\n  --no-events      Hide event-by-event progress lines in text mode\n  --approvals      run/chat: tool approval mode \u2014 always, ask, or never (default: always)\n                   serve: how the daemon reaches a human \u2014 headless (refuse every\n                   gated call) or remote (ask in Slack). Default headless, or\n                   the config file's \"approvals.mode\"\n  --max-turns      Maximum provider turns per run (default: 8)\n  --port           dashboard: port for a daemon it starts (default: 4123)\n  --host           dashboard: host for a daemon it starts (default: 127.0.0.1)\n  --no-open        Do not open the browser automatically\n  --gateway        agents: read the roster from a running daemon's control API\n  --token          Bearer token for --gateway (default: ~/.stratus/gateway-token)\n  --no-api         serve: do not serve the control API\n  --api-host       serve: control API interface (default: 127.0.0.1)\n  --api-port       serve: control API port (default: 4123, 0 for any free port)\n  --help, -h       Show this help message\n\nConfig file:\n  The CLI looks for ./stratus.config.json first, then a path from --config / STRATUS_CONFIG,\n  then the global ~/.stratus/config.json written by `stratus setup`.\n  A \"soul\" key (or STRATUS_SOUL) points at a soul file so every run uses that agent.\n  Legacy STRATUSCLAW_* env vars and stratusclaw.config.json are still supported for compatibility.\n\nPlugins (tools):\n  Capability is optional: install a package, then list it under \"plugins\" in a\n  TRUSTED config (--config, STRATUS_CONFIG, or ~/.stratus/config.json), keyed by\n  package name. A plugin runs inside this process, so an auto-discovered\n  project-local stratus.config.json may not enable one.\n\n    \"plugins\": {\n      \"@stratusagent/tool-fs\": { \"enabled\": true, \"roots\": [\"~/notes\"],\n                                 \"agents\": { \"ava\": { \"roots\": [\"~/work/ava\"] } } },\n      \"@stratusagent/tool-web\": { \"enabled\": true }\n    }\n\n  Available: @stratusagent/tool-fs (fs.read/list/search/write),\n  @stratusagent/tool-shell (shell.run), @stratusagent/tool-web (web.fetch),\n  @stratusagent/tool-browser (browser.goto/read/screenshot/act).\n  Installing one grants no agent anything \u2014 each soul lists what it may call.\n\nSoul files:\n  A soul file is markdown with frontmatter (name, provider, model, tools, credentials)\n  followed by the agent's persona in prose. See examples/souls/ava.md.\n  \"tools\" takes exact names or a whole toolset: tools: [fs.read, fs.search] or\n  tools: [fs.*]. Omitted means every registered tool.\n";
 declare const stringifyValue: (value: JsonValue) => string;
 export declare const parseCommand: (argv: string[], env?: CliEnvironment) => ParsedCommand;
 export declare const formatEvent: (event: StratusEvent) => string | null;
-export declare const resolveRuntimeConfig: (command: ParsedRunCommand, env?: CliEnvironment) => Promise<RuntimeConfig>;
+/**
+ * Kept with its historical CLI signature: a parsed run command is a
+ * RuntimeSelection plus CLI-only fields the resolver ignores.
+ *
+ * Those fields are *permitted*, not required. Demanding a whole
+ * `ParsedRunCommand` made the type claim the resolver cared about
+ * `approvals`, `format`, and `events` — it reads none of them — so every
+ * caller with a selection in hand had to invent values to get past it.
+ */
+export declare const resolveRuntimeConfig: (command: RuntimeSelection & Partial<Omit<ParsedRunCommand, keyof RuntimeSelection>>, env?: CliEnvironment) => Promise<RuntimeConfig>;
 /**
  * A saved subscription sign-in silently demoted to per-token billing is the
  * one config surprise that costs money — an API key in the environment
@@ -160,14 +192,11 @@ export declare const runSingleLoop: (prompt: string, streams: CliStreams, option
     approvals?: CliApprovalMode;
     maxTurns?: number;
     env?: CliEnvironment;
+    configPath?: string;
 }) => Promise<Session>;
 export declare const printSessionSummary: (session: Session, streams: CliStreams) => void;
 export declare const runChat: (command: ParsedChatCommand, streams: CliStreams, env?: CliEnvironment) => Promise<number>;
 export declare const openExternalUrl: (url: string) => Promise<void>;
-export declare const startDashboardServer: (options: {
-    host: string;
-    port?: number;
-}) => Promise<DashboardServerHandle>;
 export declare const slackAppManifest: (agentName: string) => string;
 export declare const runSetup: (command: ParsedSetupCommand, streams: CliStreams, env?: CliEnvironment) => Promise<number>;
 export declare const runAgents: (command: ParsedAgentsCommand, streams: CliStreams, env?: CliEnvironment) => Promise<number>;
@@ -219,6 +248,15 @@ export declare const runLogs: (command: ParsedLogsCommand, streams: CliStreams,
  */
 export declare const runService: (command: ParsedServiceCommand, streams: CliStreams, env?: CliEnvironment) => Promise<number>;
 export declare const runAgentNew: (command: ParsedAgentNewCommand, streams: CliStreams, env?: CliEnvironment) => Promise<number>;
+/**
+ * `stratus dashboard` — open the web UI against a running daemon, starting
+ * one in the foreground when there is none.
+ *
+ * The daemon is started by calling `runServe`, not by rebuilding its wiring:
+ * channels, approvals, the credential preflight, and the log writer are all
+ * decisions `serve` already makes, and a second copy of them here would drift
+ * the first time either side gained a rule.
+ */
 export declare const runDashboard: (command: ParsedDashboardCommand, streams: CliStreams, env?: CliEnvironment) => Promise<number>;
 /**
  * `stratus serve` — run the gateway (stratusd) in the foreground: load the