npm - kylon-cli - Versions diffs - 0.2.2 → 0.2.3-next.350 - Mend

kylon-cli 0.2.2 → 0.2.3-next.350

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -1,55 +1,99 @@
 # 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.
+[`kylon-cli`](https://www.npmjs.com/package/kylon-cli). The Web UI provides
+two distinct copy-paste entry points:
+- **Workspace Settings → Kylon CLI** shows
+  `npx --yes kylon-cli@<tag> auth login --workspace <id>` — authorizes this
+  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
+  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.
+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.
+`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
+`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`.
-### Step 1 — Install kylon (once per host, re-paste to upgrade)
+Requirements: Node.js 22.15.0+ (npm ships with Node). Linux / macOS only
+(Windows operators should use WSL).
-```bash
-npm install -g kylon-cli@latest
-```
+### One managed `kylon` for humans and agents
-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 bootstrap commands (`agent link`, `connect`, 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,
+or a fish `conf.d` drop-in; decline with `--no-modify-path`). From then on the
+human terminal, the agents, and the daemon all run the same file — one
+artifact, one version, one upgrade.
-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`.
+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
+fresh `npx` can still install itself over an older pinned copy; set
+`KYLON_PINNED_TRAMPOLINE=0` to disable the deferral).
-Requirements: Node.js 22.15.0+ (npm ships with Node). Linux / macOS only
-(Windows operators should use WSL).
-### Step 2 — Start the gateway daemon
+### Upgrading a gateway host
 ```bash
-kylon gateway run \
-  --session-dir ~/.kylon/agents/<agent-id> \
-  --server-url https://<origin>/api \
-  --provider codex \
-  --api-key <agent-api-key>
+npx --yes kylon-cli@latest gateway service upgrade
 ```
-`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`.
+(`@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
+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
+reconciliation under its recovery-oriented name.
+The drain waits up to five minutes for in-flight agent work, and a drain that
+exhausts its window rolls the upgrade back — so a persistently busy host would
+never upgrade without an operator interrupt. Two are available:
+- `kylon gateway service upgrade --force` skips the drain, or escalates one
+  already in progress: in-flight assignments are aborted with the same
+  recovery semantics as a daemon crash (the durable inbox re-drives
+  interrupted work on the restarted daemon), and the new version activates
+  immediately.
+- `kylon gateway service cancel` abandons an in-progress upgrade: the daemon
+  rolls back to the previous bundle and resumes accepting work on the old
+  version.
 ### Local development (contributors)
@@ -87,7 +131,7 @@ 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>
+npx --yes kylon-cli@latest auth login --workspace <WORKSPACE_ID>
 ```
 The CLI opens Kylon in your browser. After you sign in, confirm the installation
@@ -97,7 +141,9 @@ request but never receives the credential. The CLI proves possession of its PKCE
 verifier while polling Kylon over HTTPS, receives the credential directly from
 the API, and saves it in the versioned credential collection at
 `~/.kylon/workspace-auth.json` with mode `0600`. No loopback listener, incoming
-port, or browser request to localhost is used.
+port, or browser request to localhost is used. On success the CLI also pins
+itself under `~/.kylon/bin` and offers to put that directory on your PATH, so
+subsequent commands are plain `kylon workspace ...` with no npx.
 The collection keeps credentials separately by server and workspace, and
 `--scope-workspace` selects the matching entry.
@@ -128,11 +174,12 @@ state:
 - Use `kylon workspace secret list|set|delete` for canonical workspace secrets
   with browser authorization.
-- Use `kylon gateway secret list|set|delete` for agent-local records with an
-  external-agent gateway identity.
+- 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.
 This separation prevents browser credentials from reaching the
-agent-authenticated gateway secret endpoint and avoids state-dependent command
+daemon-authenticated secret endpoints and avoids state-dependent command
 routing.
 ```bash
@@ -143,169 +190,104 @@ 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.
+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.
+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
+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.
-### Onboard an invited external agent
+### Register a computer for manual placement
-The Web UI provides one operator-run command after an external agent is
-created:
+`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 onboard \
-  --url 'https://api.kylon.io/docs/agent-onboard/<opaque-token>'
+npx --yes kylon-cli@latest connect --workspace <WORKSPACE_ID>
 ```
-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.
+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.
-### Run
+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`.
-`gateway run` is the recommended entrypoint for external agent operators.
-It composes `connect` + `start` into a single command.
+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.
-```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 |
-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
+### Run
-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.
+`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
-kylon gateway connect \
-  --server-url https://api.p2.ai \
-  --api-key pak_xxxxx \
-  --provider codex
+kylon gateway run
 ```
-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.
+It takes no connection flags: register first with `kylon connect`. Without a
+saved computer registration it exits with an error pointing there.
-`--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.
+### Sleep, wake, and keep-awake (macOS)
-### Bind
-Create or update a logical session binding for an agent. Run from the
-target working directory:
+By default the daemon holds a macOS sleep assertion (the same mechanism as
+`caffeinate`) whenever it runs: on AC power the machine can turn its display
+off without ever going to sleep, so its agents stay online and dispatchable
+from the web at any time. Sleep is only prevented on AC power — on battery,
+and when the lid closes, normal sleep policy always wins. No effect on Linux.
 ```bash
-kylon gateway bind \
-  --agent agent_123 \
-  --provider codex
+kylon keep-awake            # show the current mode
+kylon keep-awake while-busy # prevent sleep only while assignments run
+kylon keep-awake off        # never prevent sleep
 ```
-Switch an existing binding to a different directory:
+Modes: `always` (default), `while-busy`, `off`. The setting persists in
+`~/.kylon/gateway-settings.json`; a running daemon hot-applies changes within
+seconds, no service restart required.
-```bash
-cd /path/to/other/repo
-kylon gateway bind --agent agent_123 --workdir .
-```
-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).
+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,
+re-asserts presence on the fresh connection, and claims the queued work —
+instead of waiting out inactivity timeouts and heartbeat intervals.
 ### 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 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 keep-awake [mode]` | Show or set macOS sleep prevention (`always` (default) / `while-busy` / `off`). |
 ### 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
@@ -609,6 +591,7 @@ npm dist-tag add kylon-cli@<last-good> latest   # move the channel back
 npm deprecate kylon-cli@<bad> "Broken release — use <last-good>."
 ```
-Operators on `@latest` pick up the re-pointed version the next time they
-`npm install -g kylon-cli@latest`; in-flight daemons keep their current CLI
-until they restart. Do not `npm unpublish`.
+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
+bundle until that drain-restart. Do not `npm unpublish`.