kylon-cli 0.4.1-next.751 → 0.4.1-next.753

package/README.md

@@ -539,78 +539,71 @@ instead of waiting out inactivity timeouts and heartbeat intervals.
 
 ## 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.
+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 800 ms, the
+daemon's after 5 seconds. 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
 
-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.
+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
 

package/dist/kylon-bundle.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.1-next.751",
-  "fingerprint": "90173f552d94066c20203c6eed919ff58f5c14a0a85235114036aa3ed3996054",
-  "source_commit": "b01e85c9720cc5d32ccdb84f6e00d4cd4aba89df"
+  "version": "0.4.1-next.753",
+  "fingerprint": "7760d3eeb79fe68bca181900357f57ea9140747350e96d3b2c5e3d9aa4a37900",
+  "source_commit": "97b6dbbefb15e1787da6d45fe5ea4cfb6a4ffb5e"
 }