kylon-cli 0.2.0-next.151 → 0.2.0-next.154

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
@@ -94,6 +95,12 @@ 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.
 
+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 +113,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 +121,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 +150,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 +193,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 +202,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 +211,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 +233,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