kylon-cli 0.2.2-next.227 → 0.2.2-next.228

package/README.md

@@ -1,56 +1,39 @@
 # kylon-cli
 
-Gateway CLI for connecting local agent providers to a P2 workspace.
+Computer host CLI for running external agents on your own machine for a P2
+workspace.
 
 Requires Node.js 22.15.0 or newer.
 
 ## Install
 
 The CLI is published to npm as
-[`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)
-
-```bash
-npm install -g kylon-cli@latest
-```
-
-Installs the CLI globally so the `kylon` binary lands on PATH — the
-gateway daemon's child `kylon workspace …` calls (issued by the
-provider subprocess) resolve it there. Re-run to upgrade to whatever
-the dist-tag now points to. If the global install needs elevated
-permissions, prefix it with `sudo`.
-
-The dist-tag tracks the environment: production installs `@latest`,
-dev installs `@next` (newest prerelease). To pin a specific build,
-install `kylon-cli@X.Y.Z`.
+[`kylon-cli`](https://www.npmjs.com/package/kylon-cli). The Web UI provides
+two copy-paste entry points, both built on `kylon connect`:
+
+- **Workspace Settings → Kylon CLI** shows
+  `npx --yes kylon-cli@<tag> connect --workspace <id>` — registers this machine
+  as a computer for the workspace and runs the host daemon. Agents are then
+  assigned to the computer from the web.
+- **An external agent's Settings page** (and the create-agent flow) shows
+  `npx --yes kylon-cli@<tag> connect --url '<setup url>'` — same registration,
+  plus the named agent is assigned to this computer in the same run. The setup
+  URL carries intent only (workspace + agent), never a credential, and expires
+  after an hour.
+
+Both commands browser-authenticate the operator, enroll the computer (minting a
+machine-scoped credential stored locally with mode `0600`), and start the host
+daemon. In release builds on supported hosts a user-level
+`launchd` / `systemd --user` service is installed so the daemon survives
+terminal exit, reboot, and sleep/wake; otherwise the daemon runs in the
+foreground until `Ctrl+C`.
+
+The dist-tag tracks the environment: production uses `@latest`, dev uses
+`@next` (newest prerelease). To pin a specific build, use `kylon-cli@X.Y.Z`.
 
 Requirements: Node.js 22.15.0+ (npm ships with Node). Linux / macOS only
 (Windows operators should use WSL).
 
-### Step 2 — Start the gateway daemon
-
-```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 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
-`launchd` / `systemd` / `supervisord`.
-
 ### Local development (contributors)
 
 ```bash
@@ -151,161 +134,66 @@ 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
+### Connect a computer (and optionally an agent)
 
-The Web UI provides one operator-run command after an external agent is
-created:
+`kylon connect` is the single onboarding entrypoint.
 
 ```bash
-npx --yes kylon-cli@latest onboard \
-  --url 'https://api.kylon.io/docs/agent-onboard/<opaque-token>'
-```
-
-The command resolves the invitation without printing its API key, checks the
-local provider, verifies Codex or Claude Code authentication, connects the
-gateway, binds a managed per-agent working directory, and installs or updates a
-user-level `launchd` / `systemd --user` service running the unified gateway. The
-command returns after the service is active; the gateway then survives terminal
-exit, crash restart, reboot, and sleep/wake reconnects. Re-onboarding the same
-agent preserves its registered provider and directory, safely interrupts
-unfinished work owned by the displaced connection, and reconciles only that
-agent inside the existing 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>`;
-an interactive terminal prompts for it when the flag is omitted.
-
-### Run
-
-`gateway run` is the recommended entrypoint for external agent operators.
-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
-```
-
-Decision table:
-
-| 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 |
-| yes | none | start the daemon from the saved session |
-| yes | any | reconnect with the overrides (falls back to saved values for fields you didn't pass), persist the refreshed session, start the daemon |
+# From Workspace Settings — register this machine, assign agents from the web:
+npx --yes kylon-cli@latest connect --workspace <WORKSPACE_ID>
 
-Only CLI flags count as overrides. On first connect, `KYLON_API_KEY` is
-persisted and the process is immediately replaced with a credential-free
-daemon image. With a saved session, the saved key remains authoritative and
-any inherited `KYLON_API_KEY` is removed before the daemon starts.
-
-### Connect
-
-Register this machine as the gateway client for an external agent.
-Most operators should prefer `gateway run` above. Use `connect` on its
-own when scripting or when you need to register a session without
-immediately starting the daemon.
-
-```bash
-kylon gateway connect \
-  --server-url https://api.p2.ai \
-  --api-key pak_xxxxx \
-  --provider codex
+# From an agent's page — register this machine AND assign that agent to it:
+npx --yes kylon-cli@latest connect --url 'https://api.kylon.io/docs/computer-setup/<opaque-token>'
 ```
 
-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
+Both forms browser-authenticate the operator (same PKCE flow as
+`kylon auth login`), enroll the machine as a **computer** keyed on its stable
+install id (re-running is idempotent), persist the machine-scoped credential,
+and start the host daemon. The `--url` form resolves the setup link to a
+workspace + agent and, after enrollment, assigns that agent to this computer —
+authorized as the signed-in user, so an account that cannot manage the agent
+gets a clear error and the computer registration still stands.
+
+The daemon then reconciles the computer's assigned agents from the server:
+each agent gets an isolated state root under `~/.kylon/agents/<agent-id>/`,
+provider readiness (Codex / Claude Code install + authentication) is reported
+per agent, and assignments arrive over the computer's single SSE stream.
+Assigning, moving, or unassigning agents later happens in the web UI; the
+daemon picks the change up without re-running `connect`.
+
+Use `--no-start` to register without starting the daemon, `--json` for
+machine-readable output, and `--server-url` to target a non-default API origin
+(the `--url` form resolves the origin from the setup link itself).
 
-Create or update a logical session binding for an agent. Run from the
-target working directory:
-
-```bash
-kylon gateway bind \
-  --agent agent_123 \
-  --provider codex
-```
+### Run
 
-Switch an existing binding to a different directory:
+`gateway run` starts the host daemon from this machine's saved computer
+registration. It is the command the installed `launchd` / `systemd --user`
+service execs; run it manually to host agents in the foreground.
 
 ```bash
-cd /path/to/other/repo
-kylon gateway bind --agent agent_123 --workdir .
+kylon gateway run
 ```
 
-Bindings are keyed by `(gateway session, agent)`. The same agent
-behaves the same way regardless of which channel an assignment
-arrives on — see
-[`docs/journal_docs/05_27_gateway_routing_simplification.md`](../../docs/journal_docs/05_27_gateway_routing_simplification.md).
+It takes no connection flags: register first with `kylon connect`. Without a
+saved computer registration it exits with an error pointing there.
 
 ### Commands
 
 | Command | Description |
 |---|---|
-| `kylon gateway run` | **Recommended.** Connect + start in one step; idempotent when a session already exists. |
-| `kylon gateway connect` | Register this machine as the gateway client for an agent (API key identifies which), without starting the daemon. |
-| `kylon gateway bind` | Create or update a logical session binding. |
-| `kylon gateway start` | Start the gateway daemon from a saved session — opens the SSE stream and executes assignments. Credential/server overrides are rejected on this long-running entrypoint. |
-
-### Run Options
-
-| Flag | Description |
-|---|---|
-| `--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` satisfies first-run setup and is removed from the daemon environment after the key is persisted) |
-| `--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>`) |
+| `kylon connect` | **Recommended.** Register this computer (browser auth + enrollment) and run the host daemon. `--url` also assigns one agent. |
+| `kylon gateway run` | Run the host daemon from the saved computer registration (service entrypoint). |
 
 ### Connect Options
 
 | Flag | Description |
 |---|---|
-| `--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
-
-| Flag | Description |
-|---|---|
-| `--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 |
-|---|---|
-| `--session-dir <path>` | Isolated state directory containing this agent's saved session, bindings, and provider runtime cache |
-
-`gateway start` accepts credentials and the server origin only from the saved
-session. Use `gateway run` when a credential or origin must be supplied or
-changed; it persists the session and replaces the process with a credential-free
-daemon image before opening SSE.
+| `--workspace <id>` | Workspace to register this computer with |
+| `--url <setup url>` | Agent setup link from Kylon; implies the workspace and assigns that agent after enrollment (alternative to `--workspace`) |
+| `--server-url <url>` | API server URL (defaults to `https://api.kylon.io`; ignored in favor of the origin resolved from `--url`) |
+| `--no-start` | Register only; do not start the daemon |
+| `--json` | Emit machine-readable JSON |
 
 ### Supported Providers