[DRAFT] [wrangler] Experimental local-dev observability (traces, spans, logs + MCP)

.changeset/local-dev-observability.md

@@ -0,0 +1,27 @@
+---
+"@cloudflare/vite-plugin": minor
+"miniflare": minor
+"wrangler": minor
+---
+
+Add experimental local-dev observability trace capture (`X_LOCAL_OBSERVABILITY`)
+
+When `X_LOCAL_OBSERVABILITY=true` is set, `wrangler dev` and the Cloudflare Vite
+plugin automatically capture structured traces for whatever worker you're
+developing — no extra config. Miniflare injects an internal trace collector as
+a streaming-tail consumer of your worker(s), enables the required compatibility
+flags, and persists each request's spans and logs to an internal D1 store that
+the Local Explorer's Observability tab reads. This is experimental and off by
+default; it can change without a major version bump.
+
+The MCP server (which lets an agent inspect the local dev environment over MCP)
+is now opt-in behind `X_LOCAL_OBSERVABILITY_MCP=true` and its Local Explorer tab
+is hidden unless enabled — the `wrangler observability` CLI is the primary way to
+inspect captured traces and logs, with MCP as an optional alternative.
+
+When enabled, the Local Explorer also hosts a "codemode" MCP endpoint at
+`/cdn-cgi/explorer/mcp`: rather than dumping the whole OpenAPI spec into an
+agent's context, it exposes a `run` tool that executes a JS snippet against a
+`cf` client (D1, KV, R2, Durable Objects, Workflows, and the trace store) and
+returns only the data the agent asked for. The snippet runs in-process via the
+worker's UnsafeEval capability, so it needs no separate install.

.changeset/wrangler-observability-cli.md

@@ -0,0 +1,17 @@
+---
+"wrangler": minor
+---
+
+Add experimental `wrangler observability` commands for inspecting local-dev traces and logs
+
+When you run `wrangler dev --experimental-observability`, traces, spans, and console logs are captured into a local store. These new commands let you — or a coding agent already running `wrangler` — query that captured data directly from the CLI, both while `wrangler dev` is running and after it has exited:
+
+- `wrangler observability logs --last N` — print the most recent console logs (`--level` to filter)
+- `wrangler observability traces --last N` — recent invocation summaries as CSV
+- `wrangler observability trace <trace_id>` — the spans of a single trace as CSV
+- `wrangler observability query "<SQL>"` — run a read-only SQL query against the trace store (CSV, or `--json`)
+- `wrangler observability skill` — print the schema and example queries as guidance for an agent (or `--install` to write it as a `SKILL.md` into detected AI agents' skills directories, reusing the same agent detection as `wrangler --install-skills`)
+
+The store is read read-only via Node's built-in SQLite, so querying does not require a running `wrangler dev` server. All commands accept `--persist-to` to match the directory used by `wrangler dev`.
+
+Under `vite dev`, `traces` and `trace` hide the Vite module-runner plumbing spans by default (so span counts reflect your worker's real spans); pass `--include-runner-spans` to show them.