@divergeai/cli 0.1.23 → 0.1.25

package/README.md

@@ -69,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
@@ -79,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
@@ -87,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)
@@ -113,24 +140,52 @@ claude mcp add --scope user divergent -- diverge tools bridge --tools search_onl
 ## Skills
 
 A skill is a procedure over the tools it names, in the Agent Skills format
-every harness reads (`<name>/SKILL.md`). The organization authors its skills
-on the platform; you get the ones whose every named tool you can run, plus
-the CLI's own `diverge` skill, which tells an agent how to reach the platform's
-tools from a shell.
+every harness reads (`<folder>/SKILL.md`). Each organization authors its
+skills on the platform; the login gets, in every organization it can act
+in, the ones whose every named tool the person can run, plus the CLI's own
+`diverge` skill, which tells an agent how to reach the platform's tools from
+a shell.
 
 ```bash
-diverge skills list       # what the platform serves you
+diverge skills list       # what the platform serves you, per organization
 diverge skills install    # into ~/.claude/skills, ~/.codex/skills and $DSH_HOME/skills
+diverge skills refresh    # the same, best effort and quiet: what sign-in and a session start run
 diverge skills status     # what each folder holds against the platform
 ```
 
-`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.
+The set is derived from the login, never chosen on the machine: who is
+signed in, where they may act, and what they can run there. A skill's
+identity is its organization and its name, so every organization's skills
+sit side by side in one folder, each under the organization's prefix — its
+short code, lowercased, or a slug of its name: `dvx-consultar-inventario`,
+`red-team-triage-cloud-run`. Each SKILL.md is rendered from the skill's
+record on every install, named after its folder, and opens with the
+organization its tools run in, so an agent passes `--organization-id` on
+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 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
+them. A whole-login refresh also retires an organization the login no longer
+lists; `--organization-id` refreshes one and leaves the rest. A session on a
+token file (`DIVERGENT_TOKEN_FILE`) holds that token's one organization. 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, 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
 
@@ -145,7 +200,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
@@ -154,10 +210,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 |
 | --- | --- |
@@ -170,7 +234,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.
 
@@ -212,6 +277,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 |