feat(local): Add daemon-managed telemetry sessions

apps/cli-docs/src/content/docs/contributing.md

@@ -65,7 +65,7 @@ cli/
 │   │   ├── event/       # list, send, view
 │   │   ├── feedback/    # list, view
 │   │   ├── issue/       # archive, events, explain, list, merge, plan, resolve, unresolve, view
-│   │   ├── local/       # run, serve
+│   │   ├── local/       # close, create, list, reset, restart, run, serve, start, status, stop, view
 │   │   ├── log/         # list, view
 │   │   ├── monitor/     # list, run
 │   │   ├── org/         # list, view

apps/local/src/lib/spotlight.test.ts

@@ -45,6 +45,12 @@ describe("getStreamUrlFromHash", () => {
     ).toBe("http://localhost:8969/stream");
   });
 
+  test("accepts a loopback daemon session stream with a read capability", () => {
+    const url =
+      "http://127.0.0.1:8969/_local/v1/sessions/session/stream?cap=read";
+    expect(parseStreamEndpoint(url)).toEqual({ url, kind: "loopback" });
+  });
+
   test("rejects a non-loopback stream URL", () => {
     expect(
       getStreamUrlFromHash("#stream=http%3A%2F%2Fexample.com%2Fstream")

apps/local/src/lib/spotlight.ts

@@ -137,16 +137,16 @@ export function parseStreamEndpoint(stream: string | null): StreamEndpoint | und
   }
   try {
     const url = new URL(stream)
-    if (
-      url.pathname !== "/stream" ||
-      url.username ||
-      url.password ||
-      url.hash
-    ) {
+    const daemonStream = /^\/_local\/v1\/sessions\/[^/]+\/stream$/.test(url.pathname)
+    if ((!daemonStream && url.pathname !== "/stream") || url.username || url.password || url.hash) {
       return undefined
     }
     if (isLoopbackHost(url.hostname)) {
-      if ((url.protocol !== "http:" && url.protocol !== "https:") || url.search) {
+      if (
+        (url.protocol !== "http:" && url.protocol !== "https:") ||
+        (!daemonStream && url.search) ||
+        (daemonStream && !url.searchParams.get("cap"))
+      ) {
         return undefined
       }
       return { url: url.toString(), kind: "loopback" }

packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -690,7 +690,20 @@ Print configuration and verify authentication
 
 Sentry for local development
 
+- `sentry local daemon start` — Start the Local control-plane daemon
+- `sentry local daemon status` — Show Local control-plane status
+- `sentry local daemon stop` — Stop the Local control-plane daemon
+- `sentry local daemon restart` — Restart the Local control-plane daemon
+- `sentry local envelope list <session...>` — List retained envelopes for a Local session
+- `sentry local envelope view <session envelope...>` — View a raw Local envelope
+- `sentry local event list <session...>` — List decoded events for a Local session
+- `sentry local event view <session event...>` — View a decoded Local event
 - `sentry local serve` — Start the local dev server and tail events
+- `sentry local session create <name...>` — Create a Local telemetry session
+- `sentry local session list` — List Local telemetry sessions
+- `sentry local session view <session...>` — View a Local telemetry session
+- `sentry local session close <session...>` — Close a Local telemetry session
+- `sentry local session reset <session...>` — Clear a Local telemetry session
 - `sentry local run <command...>` — Run a command with the local dev server enabled
 
 → Full flags and examples: `references/local.md`

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/local.md

@@ -11,6 +11,43 @@ requires:
 
 Sentry for local development
 
+### `sentry local daemon start`
+
+Start the Local control-plane daemon
+
+**Flags:**
+- `--foreground - Run in the foreground`
+- `--host <value> - Loopback host - (default: "localhost")`
+- `--port <value> - Control-plane port - (default: "8969")`
+
+### `sentry local daemon status`
+
+Show Local control-plane status
+
+### `sentry local daemon stop`
+
+Stop the Local control-plane daemon
+
+### `sentry local daemon restart`
+
+Restart the Local control-plane daemon
+
+### `sentry local envelope list <session...>`
+
+List retained envelopes for a Local session
+
+### `sentry local envelope view <session envelope...>`
+
+View a raw Local envelope
+
+### `sentry local event list <session...>`
+
+List decoded events for a Local session
+
+### `sentry local event view <session event...>`
+
+View a decoded Local event
+
 ### `sentry local serve`
 
 Start the local dev server and tail events
@@ -23,6 +60,32 @@ Start the local dev server and tail events
 - `-F, --format <value> - Output format: human (default) or json (NDJSON on stdout) - (default: "human")`
 - `-a, --attributes - Show a grouped attribute table (user vs SDK) under each transaction`
 - `--open - Open Sentry Local UI in the browser`
+- `--session <value> - Create a daemon-owned telemetry session with this label`
+
+### `sentry local session create <name...>`
+
+Create a Local telemetry session
+
+**Flags:**
+- `--clientId <value> - Idempotency key for retried agent session creation`
+- `--host <value> - Loopback host - (default: "localhost")`
+- `--port <value> - Control-plane port - (default: "8969")`
+
+### `sentry local session list`
+
+List Local telemetry sessions
+
+### `sentry local session view <session...>`
+
+View a Local telemetry session
+
+### `sentry local session close <session...>`
+
+Close a Local telemetry session
+
+### `sentry local session reset <session...>`
+
+Clear a Local telemetry session
 
 ### `sentry local run <command...>`
 
@@ -37,6 +100,7 @@ Run a command with the local dev server enabled
 - `-F, --format <value> - Output format: human (default) or json (NDJSON on stdout) - (default: "human")`
 - `-a, --attributes - Include selected event attributes in output`
 - `--open - Open Sentry Local UI in the browser`
+- `--session <value> - Create a daemon-owned telemetry session with this label`
 
 **Examples:**