kylon-cli 0.4.2 → 0.4.3

package/README.md

@@ -428,9 +428,11 @@ state:
 - Use `kylon workspace secret list|share|unshare|delete|run` for canonical
   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
+- Use `kylon gateway secret list|delete --agent <agent-id>` for agent-local
   records, authenticated by this installation's saved runtime credential
-  through agent-scoped runtime routes.
+  through agent-scoped runtime routes. There is no `set`: a credential is
+  stored as a Custom API Service from the agent's setup card or from
+  Connections in Kylon, and the agent reads it from its environment.
 
 This separation prevents browser credentials from reaching the
 daemon-authenticated secret endpoints and avoids state-dependent command
@@ -537,6 +539,77 @@ instead of waiting out inactivity timeouts and heartbeat intervals.
   without the advertisement fails over-budget assignments with a named error
   instead of receiving flags it would misparse.
 
+## Remote diagnostics
+
+The CLI reports to the server through one channel (`src/lib/telemetry.ts`):
+every logger record passes through it after redaction, and what leaves the
+machine depends on the identity the running operation selected. This is event
+logging into the API-to-Grafana Loki pipeline (`service=cli-client`), not
+OpenTelemetry/Tempo tracing. It never ships Grafana credentials and never falls
+back to another saved identity.
+
+- **Machine identity** (the computer daemon and its supervisor, locked by the
+  computer session): posts to `POST /workspaces/:ws/computers/:id/client-events`
+  every `warn`/`error` record, the info-level names on the shared inventory, and
+  the daemon lifecycle events (`daemon.started`, `daemon.crash_detected`,
+  `daemon.system_wake`, `daemon.shutdown`). Fields are flattened one level and
+  bounded (32 keys, 300 characters); a prose message is normalized to a
+  snake_case name with the wording kept in `text`. The server stamps
+  `p2EventType=cli_daemon_event` and the machine's CLI version and OS, holds
+  each machine to 300 events per 5 minutes, and announces what it dropped or
+  rejected. The operator's `remoteDiagnostics` gateway setting is the consent
+  for this path, read at every flush.
+- **User identity** (any other command once it has a credential): posts to
+  `POST /client-logs/cli` under the event and field allowlists in
+  `@p2/types/cli-telemetry`, so a command never uploads paths, prompts, argv,
+  or arbitrary error text. Identity and workspace attribution come from server
+  authentication, not client fields.
+- **Anonymous** (status (`status`/`auth status`, `gateway status`), `diagnose`,
+  the upgrade commands (`upgrade`, `provider update`, `gateway service`)): the
+  same URL without a credential, command outcomes only, with an even narrower
+  metadata allowlist. The setup commands (`auth login`, `agent link`, `connect`,
+  `onboard`) report anonymously only when they fail, with the setup session id
+  from the link inspection and the stage they reached, and switch to the
+  credential they obtain. Other commands never fall back to anonymous
+  submission when authentication fails.
+
+Telemetry initialization calls the installation store's `ensure()`:
+`install.json` in the CLI configuration directory holds the random `installId`,
+sent as `install_id` on every record. It is created before login and reused
+across runs; deleting the file resets it, copying the configuration can
+duplicate it. It identifies an installation, not a device or a person, so these
+are pseudonymous diagnostics. If the installation cannot be read or created,
+telemetry stays off.
+
+Set `KYLON_TELEMETRY_DISABLED=1` in the CLI/daemon process environment to turn
+the whole channel off; local diagnostic logs are unchanged. Restart a running
+daemon after changing its environment.
+
+Delivery: a bounded queue of 200 records (oldest dropped first, the count
+announced as `gateway.remote_events.dropped_locally`), one batch of up to 20
+every five seconds, plus an immediate flush for the daemon lifecycle events. A
+`401`, `403`, or `404` stops the channel for the rest of the process; any other
+failure keeps the batch and backs off, doubling from 30 seconds to 5 minutes.
+Requests do not follow redirects; a command's request is cut after 2.5 seconds
+(a cold connection to the API takes 0.5–0.7 s, and a failed command uploads
+at exit with no connection to reuse), the daemon's after 5 seconds. A
+`cli.command_failed` record starts its upload at once rather than at the
+next interval. Normal command completion flushes the latest batch;
+hard kills can lose events. The API limits each user identity to 60 batches per
+minute and 32 KiB per batch, anonymous sources to 20 batches per minute per
+hashed IP.
+
+### Event inventory
+
+Info-level names are the shared inventory in `@p2/types/cli-telemetry`:
+command lifecycle (`cli.command.started`, `cli.command.completed`,
+`cli.command_failed`, `cli.api.failed`), connection open/close, gateway
+connection failures and reconnect scheduling, assignment receipt and
+acceptance, provider execution, cancellation, result delivery and outbox
+replay, supervisor lifecycle, and upgrade outcomes. A machine identity adds
+every warn/error record and the daemon lifecycle; a user identity is limited to
+the inventory on both ends.
+
 ## State Model
 
 The CLI uses a per-agent installation profile and three runtime-state layers:

package/dist/kylon-bundle.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.2",
-  "fingerprint": "62cd57e7980a237a26ea6161139b0a915aa5acaefa66eb3a2c0047f909a38054",
-  "source_commit": "ab7d78b1937c39c33e4fed04c164fb6e18f45d61"
+  "version": "0.4.3",
+  "fingerprint": "cd38846706877e4d392bf64014fa0bc18d8b4aa2a6ec1b3b501ba2f2fe5ab124",
+  "source_commit": "da7a3a625fa473b90ec331fba12933cf2ffa4335"
 }