@divergeai/cli 0.1.27 → 0.1.29

package/README.md

@@ -6,8 +6,8 @@ model gateway, and call platform tools as yourself.
 ```bash
 npm install -g @divergeai/cli
 diverge login                        # browser sign-in; the organization is chosen afterwards in the CLI
+diverge dsh                          # DeepSeek Harness on the gateway, up to date, with your skills
 diverge agents setup claude          # Claude Code on the gateway
-diverge agents run dsh -- --profile web --port 3131 --no-open
 diverge tools list --organization-id <id>
 ```
 
@@ -50,11 +50,16 @@ platform grants it only where your roles back the login's scopes.
   `status`, `Acting as:` before every `tools` request — because a token
   names only a user id and the wrong account is invisible without the email:
   use the operator account for operator work, and the break-glass account
-  only knowingly.
+  only knowingly. The `Organization:` and `Acting as:` lines go to stderr, so
+  a pipe receives only the command's output and `--json` is the document
+  alone.
 - A login is for one account. `diverge login --as <email>` tells the platform
   which one; it signs that account in instead of reusing whatever session the
   browser holds and issues nothing to any other. Without `--as` the account
-  of the last login is kept, so switching accounts is always explicit.
+  of the last login is kept, so switching accounts is always explicit: a
+  browser that signs in any other account is refused and the login, shared
+  by every session on the machine, is left as it was. A second identity
+  beside it gets its own `DIVERGE_HOME`.
 - Without `--scopes` a login asks for the scopes the platform registers for
   this CLI — everything it and Forge use — and holds what your roles grant,
   so a routine re-login never narrows what another session relies on. The
@@ -96,13 +101,38 @@ 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, 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
-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.
+### dsh
+
+`diverge dsh` is the one command for DeepSeek Harness; dsh needs no setup and
+no install of its own. With nothing else it starts dsh's web UI and prints the
+URL; `diverge dsh -- "<task>"` answers one task headless and exits; anything
+after `--` goes to dsh as given. Each launch, in order:
+
+1. updates the CLI when a newer release exists and restarts on it. A registry
+   that does not answer or an install that fails warns and goes on;
+   `DIVERGE_NO_UPDATE_CHECK=1` skips this.
+2. signs in if the login does not serve the gateway.
+3. installs the dsh release this CLI is tested with, once per release, under
+   `$DIVERGE_HOME/harness/dsh/<version>`: about a minute and nearly 1 GB, and
+   Node 24.9 or later. A dsh you installed yourself is neither used nor touched.
+   A version no launch has used for a week is deleted.
+4. brings your skills up to date in `$DSH_HOME/skills`.
+5. writes the overlay `$DSH_HOME/divergent-<surface>.yml`: 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, in the shipped agent presets too; 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 agent reaches every platform tool, web search included,
+   from dsh's shell with `diverge tools`.
+6. starts dsh, keeps its token fresh in dsh's own credentials file until it
+   exits, and records the session as the organization's own (ADR 0121).
+
+The CLI runs only the dsh release it is tested with, because dsh's configuration
+and session log change between its pre-releases. A weekly job proposes the next
+release, CI runs it for real on the overlay, and the merged change reaches you
+as a CLI update on your next launch.
 
 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
@@ -171,7 +201,7 @@ every call instead of depending on the machine's default organization.
 Nobody runs the install by hand after the first time: `diverge login`
 installs, and a session start refreshes — `agents setup claude` writes a
 SessionStart hook into Claude Code's user settings, a Divergent checkout
-refreshes from its worktree setup for every harness, and `agents run dsh`
+refreshes from its worktree setup for every harness, and `diverge dsh`
 refreshes before dsh starts. A refresh is per organization: it
 replaces that organization's folders, retires the ones it stopped serving,
 and never touches another organization's or a skill you authored beside
@@ -192,6 +222,19 @@ 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.
 
+dsh runs the repository's hooks. Started inside a git checkout whose root
+holds a Claude Code hook config (`.claude/settings.json`), `diverge dsh`
+mounts dsh's own hook bridge (`@deepseek-ai/dsh-hooks-claude-code`, installed
+beside the harness) on that file, and says so at launch; anywhere else
+nothing is mounted. The bridge reads the file once at start and runs each
+command hook at the matching moment: session start, prompt, tool use, stop.
+Three things differ from Claude Code, and a hook meant for both allows for
+them: a hook runs inside dsh's sandbox (the working directory is writable,
+the home directory is not, `/tmp` does not outlive the command); context is
+read only as JSON (`hookSpecificOutput.additionalContext`), never as plain
+output; and a stop hook is never told the stop was already continued, so it
+keeps its own record of what it held for.
+
 ## Platform tools
 
 Every command takes the scope it acts in: `--organization-id` (or
@@ -201,7 +244,7 @@ resource inside a project, `--project-id` (or `DIVERGENT_PROJECT_ID`).
 
 ```bash
 diverge tools list --filter rbac             # find candidates by name or description
-diverge tools describe rbac_assign_role      # one schema, on demand
+diverge tools describe rbac_update_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
@@ -253,18 +296,19 @@ reaches it through your bridge binding. See
 [RFC: Tenant Plugins](../../docs/rfcs/rfc-tenant-plugins.md).
 
 ```bash
-diverge plugins validate manifest.json     # dry run: every problem the platform would refuse, at once
-diverge plugins publish  manifest.json     # forge_plugins:create in the login's organization; exits 3 when it waits on a decision
+diverge plugins validate manifest.json     # forge_validate_plugin: every problem at once, and whether publishing needs a decision
+diverge plugins publish  manifest.json     # forge_publish_plugin, raised as you; a person decides in Compass; exits 3 while it waits
 diverge plugins list
-diverge plugins retire <pluginId>          # the descriptor and its tools go; installations stay
+diverge plugins retire <pluginId>          # forge_retire_plugin, raised as you; the descriptor and its tools go, installations stay
 ```
 
-Tools are pinned to the manifest: a change is a new version published again.
-A version that only reshapes or removes the tools already served is stored at
-once. Anything else changes authority and is stored only once a person decides
-it: `publish` raises it as `forge_publish_plugin`, prints the invocation and
-its Compass link, and exits 3; read the outcome with
-`diverge tools invocation <id>`.
+Every write is a tool invocation decided by the organization's policy
+(ADR 0124): `publish` and `retire` print the invocation and its Compass link
+and exit 3 while they wait; read the outcome with
+`diverge tools invocation <id>`. Tools are pinned to the manifest: a change
+is a new version published again. A version that only reshapes or removes
+the tools already served is what the deploy pipeline stores unattended with
+`forge_reshape_plugin`; `validate` says which publish a version needs.
 After publishing, enable the plugin with `forge_set_plugin_state` (or the
 Forge Routing page) and bind the runtime with a bridge binding whose
 `runtimeType` equals the manifest's `runtime.type`; declare `networkPolicy`
@@ -278,6 +322,7 @@ version in the background and caches the answer under `$DIVERGE_HOME`; the
 next command prints one line on stderr when a newer release exists. Nothing
 waits on the network for it, and it stays quiet in the bridge, in
 non-interactive shells, under `CI`, and with `DIVERGE_NO_UPDATE_CHECK=1`.
+`diverge dsh` does not wait for the notice: it updates before it launches.
 
 ## Environment
 
@@ -289,7 +334,7 @@ non-interactive shells, under `CI`, and with `DIVERGE_NO_UPDATE_CHECK=1`.
 | `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 |
+| `DIVERGE_NO_UPDATE_CHECK` | set to skip the once-a-day check for a newer release, and the update at a `diverge dsh` launch |
 
 ## Security