kylon-cli 0.4.1-next.740 → 0.4.1-next.741

package/README.md

@@ -537,6 +537,81 @@ 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 sends selected structured lifecycle events to the same API-to-Grafana
+Loki pipeline as web/mobile (`POST /client-logs/cli`, `service=cli-client`,
+`client_kind=cli`). This is event logging, not OpenTelemetry/Tempo tracing.
+It uses the credential selected by the running command or computer daemon;
+it never ships Grafana credentials or falls back to another saved identity.
+Status (`status`/`auth status`, `gateway status`), `diagnose`, and upgrade commands
+(`upgrade`, `provider update`, `gateway service`) use a fixed unauthenticated
+diagnostic path on the same URL. Login failures use that path too; successful
+login selects its issued credential. Other commands never fall back to anonymous
+submission when authentication fails. The anonymous handler reuses support-report
+IP resolution/rate-limiting but has a separate quota and never creates support
+reports or uploads diagnostic bundles.
+
+Telemetry initialization calls the existing installation store's `ensure()`:
+`install.json` in the CLI configuration directory contains the random `installId`,
+which is included as `install_id` on both authenticated and anonymous records.
+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 physical device or authenticated person. With a stable identifier these are
+pseudonymous diagnostics, not unlinkable anonymous data. No hardware fingerprint
+is collected. If the installation cannot be read/created, telemetry stays off.
+Opt-out is checked before initializing the installation for telemetry.
+
+Set `KYLON_TELEMETRY_DISABLED=1` in the CLI/daemon process environment to disable
+remote diagnostics; local diagnostic logs are unchanged. Restart an already
+running daemon after changing its environment. This optional client-only switch
+does not require any server/Doppler configuration.
+
+Only events and fields listed in `@p2/types/cli-telemetry` are accepted on both
+ends. Metadata includes CLI version (`app_version`), OS, architecture, client
+timestamp, operation ID, existing task/request IDs, durations and error codes.
+Raw argv, URLs, paths, hostname, prompts, provider output and credentials are
+not uploaded. Identity/workspace attribution comes from server authentication,
+not client fields. These are untrusted diagnostics, not an audit log.
+
+The queue holds at most 100 records, sends at most 20 every five seconds, and
+drops failed batches without retrying. Requests have an 800 ms timeout and do
+not follow redirects. Normal command completion flushes the latest batch;
+shutdown can wait for an in-flight request and one final request (up to roughly
+1.6 seconds). Hard kills and immediate `process.exit()` paths can lose events.
+The API limits each authenticated identity to 60 batches/minute and 32 KiB/batch.
+Anonymous diagnostics are limited separately to 20 batches/minute per source IP
+(hashed for the rate-limit key), with the same size cap. Only command lifecycle
+events and a narrower metadata allowlist are accepted; task/workspace/user IDs,
+arbitrary error text and request IDs are dropped. The installation ID is supplied
+by the client and is not an authentication or rate-limit credential. Existing
+infrastructure request logs may retain network metadata; this change does not
+introduce or alter a retention policy.
+
+### Event inventory
+
+This change adds **5 event names at 6 logging call sites**:
+
+- `cli.command.started`
+- `cli.command.completed` (includes nonzero `process.exitCode` outcomes)
+- `cli.api.failed` (network exception and HTTP failure call sites)
+- `computer.connection.opened`
+- `computer.connection.closed`
+
+It also forwards **25 existing event names**, covering command failure,
+gateway connection failures/reconnect scheduling, assignment receipt/acceptance,
+provider execution, cancellation, result delivery/outbox replay, supervisor
+lifecycle and upgrade outcomes. The shared allowlist is the exact inventory.
+Unexpected command exceptions now reuse `cli.command_failed` instead of an
+unstructured event name. Workspace API failures are captured in the shared
+workspace client; other HTTP clients retain their existing selected diagnostics.
+Successful HTTP requests are not uploaded in this first version.
+
+Validation extends the existing logger and API route tests, plus the real
+credential/middleware integration test for CLI/computer keys and forbidden
+sibling/read routes. Live customer-machine-to-Grafana verification is still
+required after deployment; these tests do not prove Grafana delivery.
+
 ## 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.1-next.740",
-  "fingerprint": "773368feba78a11fe7d89106f9800f3e61453a3f3000aff625f1b0c15e836e5a",
-  "source_commit": "5ed4b1657bc2887af0afe3323a5c354b43e4b237"
+  "version": "0.4.1-next.741",
+  "fingerprint": "e1e127852d0679e45bc6178d57a13f743f0482f1e76889ef799d99f5430643e6",
+  "source_commit": "4ddb875a1363443f2f3f515dd475a83fbd9be490"
 }