@divergeai/cli 0.1.22 → 0.1.24

package/README.md

@@ -13,6 +13,12 @@ diverge tools list --organization-id <id>
 
 Node 22 or later. Linux and macOS are supported; Windows is best-effort.
 
+`diverge --help`, `diverge <command> --help` and `diverge <command> <verb>
+--help` print the usage, and that usage is the CLI's command table: a
+command, verb or option that does not exist is answered with the closest ones
+it lists, by spelling or by what their description says (`diverge whoami` →
+`diverge status`, `tools search` → `tools list --filter`), and exits 1.
+
 ## Sign in
 
 `diverge login` runs the browser sign-in (authorization code with PKCE on a
@@ -63,6 +69,23 @@ platform grants it only where your roles back the login's scopes.
   reach it when `DIVERGENT_API_URL` names it. Nothing on disk chooses the
   deployment.
 
+### Session token
+
+A session started for one piece of work runs on the token handed to it, not
+on a login. Set `DIVERGENT_TOKEN_FILE` to a file holding that bearer token:
+every command reads the file again, so a supervisor replaces it for each
+attempt, and the CLI never reads, refreshes or writes a login under
+`$DIVERGE_HOME` and never falls back to one or to service credentials.
+
+- The token decides the organization: commands act in the token's, and an
+  `--organization-id` or `DIVERGENT_ORG_ID` naming another is refused before
+  any request.
+- `diverge token` prints the file's token, so `forge` and the agent overlays
+  run on it unchanged. `Acting as:` names the account the platform says the
+  token is for, marked as a session token, with the actor the token names.
+- A missing, empty or unreadable file is an error naming the file.
+- `login`, `logout`, `org` and `update` refuse: the session holds no login.
+
 ## Coding agents
 
 `diverge agents setup <agent>` writes the configuration one agent needs to use
@@ -73,7 +96,7 @@ the gateway, keeping everything else in the file:
 | `claude` | `~/.claude/settings.json` (or `./.claude/settings.local.json` with `--scope project`): the gateway base URL and `diverge token` as the key helper; `--project-id` adds the project header, `--model-discovery` lets Claude Code list the gateway's models |
 | `opencode` | `~/.config/opencode/opencode.json`: a `divergent-<surface>` provider reading `DIVERGENT_TOKEN` |
 | `codex` | `~/.codex/config.toml`: a `divergent` provider block with `diverge token` as its auth command; `--print` shows it instead |
-| `dsh` | `$DSH_HOME/divergent-<surface>.yml`: a patch overlay with the models the gateway serves and dsh's DeepSeek adapter, telemetry upload and vendor search turned off; the Divergent agent preset; and your skills in `$DSH_HOME/skills`, through which the agent reaches every platform tool, web search included, from dsh's shell with `diverge tools` |
+| `dsh` | `$DSH_HOME/divergent-<surface>.yml`: a patch overlay with the models the gateway serves, each with the input, context window and output cap the gateway lists for it, dsh's DeepSeek adapter, telemetry upload and vendor search turned off, a shell command budget raised from dsh's 60 s to the CLI's own request ceiling so a platform tool call is never cut off before the platform answers, and Chrome DevTools MCP on port 9222; the Divergent agent preset; and your skills in `$DSH_HOME/skills`, through which the agent reaches every platform tool, web search included, from dsh's shell with `diverge tools` |
 
 `diverge agents run dsh` launches DeepSeek Harness on the overlay and keeps
 its token fresh in dsh's own credentials file until it exits. With nothing
@@ -81,6 +104,16 @@ else it starts dsh's web UI and prints the URL; `diverge agents run dsh --
 "<task>"` answers one task headless and exits; anything after `--` goes to
 dsh as given.
 
+The session runs on its own token, not on your login. The CLI keeps
+`$DSH_HOME/session-token` fresh beside the credentials file, and writes
+`$DSH_HOME/bin/diverge`, first on dsh's PATH, which runs the CLI that started
+the session on that token (`DIVERGENT_TOKEN_FILE`). Every `diverge` the agent
+runs from dsh's shell therefore acts in the organization the session was
+started for. It never reads, refreshes or rewrites your login from inside dsh's
+sandbox, where your home is read-only, and it never reaches another `diverge`
+the host has on PATH. `diverge org use` elsewhere does not move a running
+session; start a new one to act in another organization.
+
 `diverge agents status` shows the organization, the scopes, and the models
 each surface serves. `diverge agents rotate` keeps a token file fresh
 (default `~/.divergent/token`, every 600 seconds; `--once` writes and exits)
@@ -118,13 +151,25 @@ diverge skills install    # into ~/.claude/skills, ~/.codex/skills and $DSH_HOME
 diverge skills status     # what each folder holds against the platform
 ```
 
+Each SKILL.md is rendered from the skill's record on the platform on every
+install, so what lands in the folder is the skill as it stands now.
+
 `agents setup claude|codex|dsh` and `agents run dsh` install them as well, so
 a harness the CLI set up has the skills from its first session. A refresh
 replaces the CLI's own folders, retires the ones the organization retired, and
 never touches a skill you authored beside them. The skills are the tool
 surface: an agent reaches every platform tool from its shell with `diverge
 tools`, which costs nothing until a tool is called, and the `diverge` skill
-shows it how, file-based arguments and batches included.
+shows it how, arguments piped through stdin and batches included.
+
+dsh also gets the browser. The overlay mounts Chrome DevTools MCP, attached
+to a Chrome the person starts in debug mode (`--remote-debugging-port=9222`,
+on a profile of its own), and the CLI's `drive-chrome` skill says how to use
+it. This is the one MCP server the overlay mounts: platform tools stay in the
+shell, but a browser session has to outlive one command, and dsh runs each
+command in a fresh sandbox. Its tool definitions ride on every request
+(about 5k tokens, cached after the first). Without a Chrome on the port the
+server waits; the first tool call connects.
 
 ## Platform tools
 
@@ -139,7 +184,8 @@ diverge tools describe rbac_assign_role      # one schema, on demand
 diverge tools call rbac_list_roles --args-json '{}'
 diverge tools call rbac_list_roles --json    # exactly one JSON outcome on stdout, errors included
 diverge tools call inventory_lookup_stock --args-file args.json   # or --args-json - to read stdin
-diverge tools run calls.json --wait          # several calls from one file (- for stdin), one JSON line of outcome each
+diverge tools set writes.json --summary "Coordinators follow their cargo"   # several related writes, ONE decision
+diverge tools run calls.json --wait          # several independent calls from one file (- for stdin), one JSON line of outcome each
 ```
 
 Put arguments in a file or on stdin when a shell may touch them: Windows
@@ -148,10 +194,18 @@ JSON array of `{"tool": "...", "args": {...}}` (or one per line), runs them in
 order, and exits with the worst outcome: 1 failed, 4 rejected, 5 expired,
 3 pending, else 0.
 
+When several writes serve one intent, raise them with `set` instead: the
+same file format, one pending invocation for the lot, one card for the
+person who decides it. Once approved the calls run in order and stop at the
+first failure; `diverge tools invocation <id>` reads every call's outcome
+(`succeeded`, `failed`, `not_run`) from `result.calls`. A set carries writes
+only, with arguments frozen when it is raised.
+
 A write that needs a human is not refused: it is persisted as a pending
 invocation, decided in the platform's approval inbox, and read back here by
-id. Branch on the exit code, never on text; `call`, `run` and `invocation <id>`
-give the same code for the same status, with or without `--json`:
+id. Branch on the exit code, never on text; `call`, `set`, `run` and
+`invocation <id>` give the same code for the same status, with or without
+`--json`:
 
 | code | meaning |
 | --- | --- |
@@ -164,7 +218,8 @@ give the same code for the same status, with or without `--json`:
 
 The CLI raises and reads; it never decides. `diverge tools bridge` serves the
 same catalog as a stdio MCP server for clients without a shell, with
-`divergent_invocation_status` for the read-back. `--tools <name,name>` publishes
+`divergent_submit_set` to raise a set and `divergent_invocation_status` for
+the read-back. `--tools <name,name>` publishes
 and accepts only those tools: the whole catalog is tens of thousands of tokens
 on every request, so a harness gets the tools it was given and nothing else.
 
@@ -206,6 +261,7 @@ non-interactive shells, under `CI`, and with `DIVERGE_NO_UPDATE_CHECK=1`.
 | `DIVERGE_HOME` | state directory, default `~/.diverge` |
 | `DIVERGENT_ORG_ID`, `DIVERGENT_PROJECT_ID` | tool scope when the flags are omitted; without either, the login's organization |
 | `DIVERGENT_CLIENT_ID`, `DIVERGENT_CLIENT_SECRET`, `DIVERGENT_USER_ID` | unattended tool execution with service credentials, delegated to that person |
+| `DIVERGENT_TOKEN_FILE` | a file holding the token this session runs on, in place of any login (see Session token) |
 | `DSH_HOME` | where dsh keeps its files, default `~/.dsh` |
 | `DIVERGE_NO_UPDATE_CHECK` | set to skip the once-a-day check for a newer release |