kylon-cli 0.2.0-next.152 → 0.2.0-next.155

package/README.md

@@ -7,11 +7,11 @@ Requires Node.js 22 or newer.
 ## Install
 
 The CLI is published to npm as
-[`kylon-cli`](https://www.npmjs.com/package/kylon-cli). The Web UI
-generates two separate commands — an **install** step and a **run**
-step — each with its own Copy button. Operators paste the install
-once per host (and any time they want to upgrade) and the run
-whenever they want to start the daemon.
+[`kylon-cli`](https://www.npmjs.com/package/kylon-cli). The Web UI's
+Onboarding tab provides one opaque `npx ... onboard --url ...` command
+for the normal setup and re-onboarding flow. Its collapsed manual setup
+shows the separate install and run commands documented below for recovery
+and advanced operation.
 
 ### Step 1 — Install kylon (once per host, re-paste to upgrade)
 
@@ -36,15 +36,16 @@ Requirements: Node.js 22+ (npm ships with Node). Linux / macOS only
 
 ```bash
 kylon gateway run \
+  --session-dir ~/.kylon/agents/<agent-id> \
   --server-url https://<origin>/api \
   --provider codex \
   --api-key <agent-api-key>
 ```
 
-`gateway run` registers the session (writing `~/.kylon/gateway-session.json`
-with mode `0600`) and starts the daemon in one step. On the next
-invocation, if a session already exists, plain `kylon gateway run`
-without flags picks it up and jumps straight to start. See
+`gateway run` registers the session inside the selected agent directory
+(writing `~/.kylon/agents/<agent-id>/gateway-session.json` with mode `0600`)
+and starts the daemon in one step. On the next invocation, pass the same
+`--session-dir` without connection flags to jump straight to start. See
 [Usage → Run](#run) for the full decision table. The daemon runs
 in the foreground until you stop it with `Ctrl+C`; hosts that want a
 supervised daemon typically wrap the same command in
@@ -64,17 +65,60 @@ for the debugger-friendly tsx-based dev loop.
 
 npm dist-tags are the version pointer — there is no server-side version
 policy. Every merge to `develop` publishes a prerelease to the `next` tag
-(`.github/workflows/cli-publish.yml`); cutting a `kylon-cli-vX.Y.Z`
-release tag publishes a stable to `latest`. dev installs `@next` and prd
-installs `@latest`, so each environment tracks its own train.
-
-Cutting a stable is a manual, when-ready step: tag a validated build
-`kylon-cli-vX.Y.Z` and push the tag; CI publishes it to `latest`. Don't
-`npm publish` ad-hoc — releases go through the CI workflow so the OIDC
-publish path is exercised end-to-end.
+(`.github/workflows/cli-publish.yml`). A production deployment dispatched from
+`main` automatically invokes the same workflow in stable mode and publishes the
+exact `packages/cli/package.json` version to `latest`; it is idempotent when that
+version already exists. A CLI change intended for production must therefore bump
+the package version before the production deploy, or the stable publish will
+correctly no-op and `latest` will remain on the existing build.
+
+A matching `kylon-cli-vX.Y.Z` tag is an alternative supported stable-release
+trigger, not a required extra step after a production deploy. Do not run
+`npm publish` ad hoc: both paths use the CI workflow and its OIDC publisher.
+Development installs `@next` and production installs `@latest`, so each
+environment tracks its own release train.
 
 ## Usage
 
+### Sign in for workspace commands
+
+For a person using `kylon workspace ...` from their own terminal, open the
+workspace's **Settings → Kylon CLI** section, expand it, and copy its setup
+command, or run:
+
+```bash
+npm install -g kylon-cli@latest && kylon auth login --workspace <WORKSPACE_ID>
+```
+
+The CLI opens Kylon in your browser. After you sign in, confirm the installation
+and workspace shown on the authorization page. Kylon then creates one credential
+for that CLI installation and workspace. The secret is delivered directly to the
+local CLI callback and saved in the versioned credential collection at
+`~/.kylon/workspace-auth.json` with mode `0600`; it is not displayed in Settings.
+The collection keeps credentials separately by server and workspace, and
+`--scope-workspace` selects the matching entry.
+
+Each installation credential expires after 90 days. Re-running `kylon auth
+login` for the same installation and workspace rotates that credential, making
+the previous value invalid. Use `kylon auth status` to inspect the bound
+workspace and expiration time.
+
+```bash
+kylon auth logout --workspace <WORKSPACE_ID>
+```
+
+Logout revokes the selected installation credential remotely before removing
+that entry from the local collection. With no `--workspace`, it selects the most
+recently authorized entry. If Kylon cannot confirm revocation, it keeps the local
+credential so you can retry. `kylon auth logout --local-only` deliberately skips
+the remote revocation. You can also revoke any installation independently from
+**Settings → Kylon CLI**. Other installations, browser sessions, external-agent
+keys, and workspace service keys are unaffected.
+
+Credentials created by the earlier browser flow appear as **Legacy user API
+key** in Settings. They can be revoked there, but they are not bound to a single
+workspace; sign in again to replace one with the per-installation flow.
+
 ### Onboard an invited external agent
 
 The Web UI provides one operator-run command after an external agent is
@@ -94,6 +138,16 @@ by the displaced connection, and replaces the foreground daemon. If Codex or
 Claude Code is logged out, an interactive terminal launches the provider's own
 login flow and verifies authentication again before connecting.
 
+External-agent onboarding is intentionally separate from human `kylon auth
+login`: it continues to use the agent principal's API key and gateway session.
+It does not create a human CLI installation credential.
+
+Each invited agent is installed below `~/.kylon/agents/<agent-id>/`, so several
+Claude Code, Codex, or mixed-provider agents can run on the same host without
+sharing credentials or provider resume state. Different agents cannot use the
+same canonical working directory; create a separate checkout or Git worktree for
+each concurrently installed agent.
+
 Use `--workdir <path>` to select a different directory or `--no-start` to
 configure and validate without opening the long-running connection. Generic
 providers can supply their one-shot command with `--agent-command <command>`;
@@ -106,6 +160,7 @@ It composes `connect` + `start` into a single command.
 
 ```bash
 kylon gateway run \
+  --session-dir ~/.kylon/agents/agent_123 \
   --server-url https://api.p2.ai \
   --provider codex \
   --api-key pak_xxxxx
@@ -113,7 +168,7 @@ kylon gateway run \
 
 Decision table:
 
-| Saved session? | Flags passed? | What `run` does |
+| Saved session in `--session-dir`? | Connection flags passed? | What `run` does |
 |---|---|---|
 | no | `--server-url` + `--api-key` + `--provider` | connect, persist session, start daemon |
 | no | any field missing | error — lists the missing flag |
@@ -142,6 +197,10 @@ The agent's API key identifies which agent the daemon will serve;
 channels are bound separately via the "invite agent into channel" flow
 in the web UI.
 
+`--session-dir` selects the full isolated state root for one agent. It is
+not a connection override, so it must be present both when connecting and
+when restarting that agent.
+
 ### Bind
 
 Create or update a logical session binding for an agent. Run from the
@@ -181,6 +240,7 @@ arrives on — see
 | `--server-url <url>` | P2 server URL (required for the first run; override otherwise) |
 | `--api-key <key>` | Agent API key, e.g. `pak_xxx` (required for first run; override otherwise. `KYLON_API_KEY` env var satisfies the first-run requirement but does not count as an override on subsequent runs) |
 | `--provider <name>` | Provider CLI: `codex`, `claude-code`, `hermes`, `openclaw`, `generic` (required for first run; override otherwise) |
+| `--session-dir <path>` | Isolated state directory for this agent (normally `~/.kylon/agents/<agent-id>`) |
 
 ### Connect Options
 
@@ -189,6 +249,7 @@ arrives on — see
 | `--server-url <url>` | P2 server URL (required) |
 | `--api-key <key>` | Agent API key, e.g. `pak_xxx` (required, or set `KYLON_API_KEY`) |
 | `--provider <name>` | Provider CLI: `codex`, `claude-code`, `hermes`, `openclaw`, `generic` (required) |
+| `--session-dir <path>` | Isolated state directory for this agent |
 
 ### Bind Options
 
@@ -197,6 +258,15 @@ arrives on — see
 | `--agent <id>` | Agent ID (required) |
 | `--provider <name>` | Provider CLI (required for new, optional for update) |
 | `--workdir <path>` | Working directory (default: current directory) |
+| `--session-dir <path>` | Isolated state directory for this agent |
+
+### Start Options
+
+| Flag | Description |
+|---|---|
+| `--server-url <url>` | Override the server URL from the saved session |
+| `--api-key <key>` | Override the API key from the saved session |
+| `--session-dir <path>` | Isolated state directory containing this agent's saved session, bindings, and provider runtime cache |
 
 ### Supported Providers
 
@@ -210,15 +280,18 @@ arrives on — see
 
 ## State Model
 
-The CLI uses a three-layer state model:
+The CLI uses a per-agent installation profile and three runtime-state layers:
 
-- **GatewaySession** — authenticated connection to the P2 server (one per machine)
+- **InstalledAgentProfile** — non-secret agent identity, provider, and exclusive workdir ownership
+- **GatewaySession** — authenticated connection to the P2 server for one agent
 - **LogicalSessionState** — per-`(gateway session, agent)` binding holding the current workdir and provider
 - **ProviderRuntimeEntry** — per-conversation provider resume cache, keyed by `(gateway session, channel, agent, scope, provider, workdir)` (disposable)
 
 Switching workdir updates the logical session without creating a new one. Provider runtimes are cached per workdir + conversation scope — switching back resumes the old runtime.
 
-State is persisted to `~/.kylon/` (or `$XDG_CONFIG_HOME/kylon/`).
+Agent state is persisted to `~/.kylon/agents/<agent-id>/` (or
+`$XDG_CONFIG_HOME/kylon/agents/<agent-id>/`). Human workspace authentication
+remains in the top-level Kylon config directory.
 
 ## Development
 
@@ -444,9 +517,10 @@ API server is the security boundary.
 
 The CLI ships via **npm dist-tags** — there is no server-side version policy.
 `cli-verify.yml` validates on PRs and pushes; `cli-publish.yml` publishes via
-OIDC (no token): a prerelease to the `next` tag on every merge to `main`, and a
-stable to `latest` when a `kylon-cli-vX.Y.Z` tag is pushed. dev installs
-`@next`, prd installs `@latest`.
+OIDC (no token): a prerelease to the `next` tag on every qualifying merge to
+`develop`, and the package version to `latest` when the production deploy runs
+from `main`. A matching `kylon-cli-vX.Y.Z` tag can also publish that stable
+version. Development installs `@next`; production installs `@latest`.
 
 ### Versioning
 
@@ -458,18 +532,23 @@ Use explicit semver in `packages/cli/package.json`:
 | minor (`0.1.x → 0.2.0`) | backward-compatible capability (new command, new flag) |
 | major (`0.x.x → 1.0.0`) | breaking change to CLI contract or runtime behavior |
 
-Prerelease builds are versioned `0.1.0-next.<run>` automatically by
-`cli-publish.yml`; a stable release is whatever you tag — bump
-`packages/cli/package.json` to the target semver, then push the matching
-`kylon-cli-vX.Y.Z` tag.
+Prerelease builds are versioned `<package-version>-next.<run>` automatically by
+`cli-publish.yml`. Stable mode publishes the exact package version and skips
+idempotently if npm already has it. Bump `packages/cli/package.json` whenever a
+new production CLI build must be published; otherwise the production deploy
+will intentionally leave `latest` unchanged.
 
 ### Publishing
 
-- **Prerelease (automatic):** every merge to `main` touching the CLI publishes
-  `0.1.0-next.<run>` to the `next` tag via `cli-publish.yml` (OIDC, no
+- **Prerelease (automatic):** every merge to `develop` touching the CLI publishes
+  `<package-version>-next.<run>` to the `next` tag via `cli-publish.yml` (OIDC, no
   `NPM_TOKEN`). dev tracks this tag, so dev always dogfoods the newest build.
-- **Stable (manual, when ready):** bump `packages/cli/package.json` to the
-  target version, merge, then tag the commit on `main`:
+- **Stable (automatic with a production deploy):** a production deployment
+  dispatched from `main` calls `cli-publish.yml` in stable mode. It publishes
+  the package version only when that exact version is absent from npm. CLI
+  changes therefore need a package-version bump before the production deploy.
+- **Stable tag (alternative):** after bumping the package version, a matching
+  tag on `main` invokes the same stable workflow directly:
 
   ```bash
   git pull
@@ -478,8 +557,8 @@ Prerelease builds are versioned `0.1.0-next.<run>` automatically by
   npm view kylon-cli dist-tags        # verify
   ```
 
-  Do not `npm publish` ad-hoc — releases go through the workflow so the OIDC
-  provenance path is exercised end to end.
+Do not `npm publish` ad hoc: production deploys and release tags both go through
+the workflow so the OIDC provenance path is exercised end to end.
 
 ### Rollback