kylon-cli 0.2.4 → 0.2.5-next.456

package/README.md

@@ -1,7 +1,6 @@
 # kylon-cli
 
-Computer host CLI for running external agents on your own machine for a P2
-workspace.
+Local runtime CLI for running external agents for a P2 workspace.
 
 Requires Node.js 22.15.0 or newer.
 
@@ -16,31 +15,33 @@ two distinct copy-paste entry points:
   installation for human workspace commands. Its **Use with Your Agents**
   prompt teaches Claude Code, Codex, Hermes, or OpenClaw to discover and use
   `kylon workspace` commands without assuming a provider-specific interface.
-- **An external agent's Onboarding tab** shows
-  `npx --yes kylon-cli@<version> agent link --url '<one-time link>'`. The link
+- **An external agent's Profile** shows
+  `npx --yes kylon-cli@<version> agent link --url '<one-time link>'`. Custom
+  ACP agents append `-- <launch command> [args]` to that same line. The link
   embeds a short-lived credential, so the CLI does not open a browser or reuse
   a human workspace credential. It checks that the selected Claude Code or
   Codex CLI is installed and authenticated, shows the exact agent and
-  workspace for confirmation, registers this installation as a computer,
-  assigns the agent, and starts the host daemon. The credential expires after
-  30 minutes and can be redeemed only once; rerunning the same installation's
-  interrupted redemption is idempotent. Because the link carries the
-  credential, treat the command as a secret until it is used or expires.
-
-A machine may be registered with one Kylon server and workspace at a time.
+  workspace for confirmation, connects the agent, and starts its local
+  runtime. For ACP, the same operation also saves the selected launch command.
+  The credential expires after 30 minutes and can be redeemed only once;
+  rerunning the same installation's interrupted redemption is idempotent.
+  Because the link carries the credential, treat the command as a secret until
+  it is used or expires.
+
+A local runtime may be connected with one Kylon server and workspace at a time.
 Equivalent spellings of the same server (`https://dev.purework.ai/api` and
 `https://api.purework.ai`, `https://app.kylon.io/api` and
 `https://api.kylon.io`) count as the same registration; preview environments
 never do, even though they serve the same workspace ids as dev. Run
-`kylon computer unlink` to point a machine somewhere else — it forgets the
-local registration only, revoking nothing in the workspace and unassigning no
-agent.
+`kylon disconnect` before connecting it somewhere else. This forgets only the
+local runtime registration; it revokes nothing or changes any workspace-side
+agent configuration.
 
 `auth login` browser-authenticates the human operator for `kylon workspace`
 commands. `agent link` authenticates only the link operation with its embedded
-credential; it never creates a human CLI session. Linking mints or reuses a
-machine-scoped credential stored locally with mode `0600` and starts the host
-daemon. In release builds on supported hosts a user-level
+credential; it never creates a human CLI session. Linking mints or reuses an
+installation credential stored locally with mode `0600` and starts the local
+agent runtime. In release builds on supported environments 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`.
@@ -53,7 +54,7 @@ Requirements: Node.js 22.15.0+ (npm ships with Node). Linux / macOS only
 
 ### One managed `kylon` for humans and agents
 
-The bootstrap commands (`agent link`, `connect`, and `auth login`) pin the CLI under
+The bootstrap commands (`agent link` and `auth login`) pin the CLI under
 `~/.kylon/bin`: the exact bundle the daemon and its agents execute, exposed as
 the `kylon` command. After the bootstrap they offer to add that directory to
 your shell PATH (a marker-wrapped `. "$HOME/.kylon/env"` line in your shell rc,
@@ -63,23 +64,23 @@ artifact, one version, one upgrade.
 
 A leftover npm-global or npx-cached copy stays harmless: when it starts and
 finds a strictly newer pinned install, it defers to it automatically
-(installer commands — `agent …`, `connect`, and `gateway …` — always run as invoked, so a
+(installer commands — `agent …` and `gateway …` — always run as invoked, so a
 fresh `npx` can still install itself over an older pinned copy; set
 `KYLON_PINNED_TRAMPOLINE=0` to disable the deferral).
 
-### Upgrading a gateway host
+### Upgrading a local runtime
 
 ```bash
 npx --yes kylon-cli@latest gateway service upgrade
 ```
 
 (`@next` on dev.) The daemon and the pinned agent `kylon` both run the
-installed bundle under `~/.kylon/bin`, which only this command (or a
-re-connect) refreshes: the freshly-resolved CLI installs its own bundle and
+installed bundle under `~/.kylon/bin`, which only this command (or a fresh
+`agent link`) refreshes: the freshly-resolved CLI installs its own bundle and
 drain-restarts the running daemon onto it, moving both in lockstep.
 `npm install -g` alone updates the operator's terminal binary and leaves the
-gateway on the old build. The update notice the CLI prints on gateway hosts
-uses exactly this command; `kylon gateway service repair` is the same
+runtime service on the old build. The update notice the CLI prints for local
+runtimes uses exactly this command; `kylon gateway service repair` is the same
 reconciliation under its recovery-oriented name.
 
 The drain waits up to five minutes for in-flight agent work, and a drain that
@@ -181,8 +182,8 @@ state:
   workspace secret grants with browser authorization. Create API keys through
   the secure Connection flow in Kylon.
 - Use `kylon gateway secret list|set|delete --agent <agent-id>` for agent-local
-  records, authenticated by this machine's computer credential through the
-  per-agent computer routes.
+  records, authenticated by this installation's saved runtime credential
+  through agent-scoped runtime routes.
 
 This separation prevents browser credentials from reaching the
 daemon-authenticated secret endpoints and avoids state-dependent command
@@ -197,59 +198,33 @@ 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. This logout is deliberately credential-only: it does not
-disconnect a computer or unassign its agents. If that installation still hosts
-external agents, it remains listed as an **Authorized device** so its host
-authority can still be removed without signing the CLI in again.
+disconnect the local agent runtime or change connected agents. If that installation
+still runs external agents, it remains listed as an **Authorized device** so its
+runtime access can still be removed without signing the CLI in again.
 
 You can instead remove an **Authorized device** from **Settings → Kylon CLI**.
 After warning about the impact, that workspace-scoped action revokes any active
-installation credential, disconnects and revokes the computer host associated
-with the same installation, and unassigns every external agent hosted there.
-The device's authorizations and host registrations in other workspaces, browser
+installation credential, removes the local runtime access associated with the
+same installation, and disconnects every external agent using it. The device's
+authorizations and runtime access in other workspaces, browser
 sessions, 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.
 
-### Register a computer for manual placement
-
-`kylon connect` remains the advanced computer-first entrypoint when the user
-explicitly wants to register a host before choosing an agent:
-
-```bash
-npx --yes kylon-cli@latest connect --workspace <WORKSPACE_ID>
-```
-
-This browser-authenticates the operator (the same PKCE flow as `kylon auth
-login`), enrolls the machine as a **computer** keyed on its stable install id
-(re-running is idempotent), persists the machine-scoped credential, and starts
-the host daemon. New external-agent onboarding should use the agent-specific
-`agent link` command instead; creation never asks the user to select a computer.
-
-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.
-Linking or relinking an agent later happens from that agent's Onboarding tab;
-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
-for direct computer registration.
-
 ### Run
 
-`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.
+`gateway run` starts the local runtime service from this environment's saved
+connection. It is the command the installed `launchd` / `systemd --user`
+service execs; run it manually to keep connected agents available in the foreground.
 
 ```bash
 kylon gateway run
 ```
 
-It takes no connection flags: register first with `kylon connect`. Without a
-saved computer registration it exits with an error pointing there.
+It takes no connection flags: link an agent first with `kylon agent link`.
+Without a saved runtime connection it exits with guidance pointing there.
 
 ### Sleep, wake, and keep-awake (macOS)
 
@@ -272,7 +247,7 @@ seconds, no service restart required.
 When the machine does sleep (battery, lid closed, manual sleep), assignments
 dispatched to its agents queue server-side. The daemon detects the wake
 instantly (a wall-clock jump across its monitor tick) and recovers in one
-pass: it force-reconnects the computer event stream with reset backoff,
+pass: it force-reconnects the runtime event stream with reset backoff,
 re-asserts presence on the fresh connection, and claims the queued work —
 instead of waiting out inactivity timeouts and heartbeat intervals.
 
@@ -280,21 +255,11 @@ instead of waiting out inactivity timeouts and heartbeat intervals.
 
 | Command | Description |
 |---|---|
-| `kylon connect` | **Recommended.** Register this computer (browser auth + enrollment) and run the host daemon. `--url` also assigns one agent. |
-| `kylon computer unlink` | Forget this machine's saved computer registration so it can be linked elsewhere. Local only: revokes nothing and unassigns no agent. |
-| `kylon gateway run` | Run the host daemon from the saved computer registration (service entrypoint). |
+| `kylon agent link --url <link> [-- <launch command>]` | **Recommended.** Connect one agent and start its local runtime. ACP launch commands are saved in the same operation. |
+| `kylon disconnect` | Forget this environment's saved runtime connection. Local only: workspace-side agent configuration is unchanged. |
+| `kylon gateway run` | Run the local runtime service from the saved connection (service entrypoint). |
 | `kylon keep-awake [mode]` | Show or set macOS sleep prevention (`always` (default) / `while-busy` / `off`). |
 
-### Connect Options
-
-| Flag | Description |
-|---|---|
-| `--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
 
 - `codex` — OpenAI Codex CLI
@@ -599,5 +564,5 @@ npm deprecate kylon-cli@<bad> "Broken release — use <last-good>."
 
 Operators on `@latest` pick up the re-pointed version the next time they run
 `npx --yes kylon-cli@latest gateway service upgrade` (the command the update
-notice prints on gateway hosts); in-flight daemons keep their current pinned
+notice prints for local runtimes); in-flight daemons keep their current pinned
 bundle until that drain-restart. Do not `npm unpublish`.