Fluttersdk Telescope

fluttersdk_telescope

Passive runtime inspector for Flutter apps, designed for LLM agents. The running app captures HTTP, logs, exceptions, dumps, in-app events, gate checks, DB queries, cache ops, and per-frame performance into 10 in-memory ring buffers. The agent calls telescope_* MCP tools (or ./bin/fsa telescope:* from a shell) to read those buffers on demand, without touching the source or attaching DevTools.

This skill assumes the app already has telescope installed (a kDebugMode-gated TelescopePlugin.install() in lib/main.dart, the MCP server in .mcp.json). If not, run dart run fluttersdk_telescope telescope:install once from the app root, restart, and verify with ./bin/fsa telescope:tail.

1. Core Laws

1. Telescope is passive, it captures, never drives. Records flow into the 10 ring buffers as the app runs. The agent reads; it does not produce. Pair with fluttersdk_dusk when the agent needs to drive the UI (dusk_tap, dusk_type, dusk_navigate) and then read the consequences. Without something exercising the app, the buffers stay empty.

2. Two install layers, mind the gap. Raw TelescopePlugin.install() only wires LogWatcher plus the VM extensions, plus the opt-in ExceptionWatcher and DumpWatcher if the consumer registered them. Magic-stack apps must additionally call MagicTelescopeIntegration.install() after Magic.init() to populate the HTTP, events, gates, queries, and magic-cache buffers (and to expose pendingCount for dusk's network-idle gate). MagicTelescopeIntegration ships in the magic_devtools package (import package:magic_devtools/telescope.dart), not in magic core. When telescope_requests returns {"records": []} on a known-active app, suspect a missing adapter, not a quiet app. The CLI gives the same hint inline: "No HTTP records (register a TelescopeHttpAdapter).", "No DB query records (register MagicQueryWatcher).", etc.

3. Uniform response envelope. Every read tool returns a single JSON object { "<key>": [<record>, ...] } where <key> is the buffer name keyed below. The MCP transport wraps that JSON string as a single text content block, so parse the text body as JSON before reasoning over individual fields.

   Tool	Envelope key	Record type
   telescope_requests	records	HttpRequestRecord
   telescope_tail	messages	LogRecordEntry
   telescope_exceptions	exceptions	ExceptionRecord
   telescope_events	events	EventRecord
   telescope_gates	gates	GateRecord
   telescope_dumps	dumps	DumpRecord
   telescope_queries	queries	QueryRecord
   telescope_caches	caches	MagicCacheRecord
   telescope_clear	cleared: true (not an array)	(sentinel)

4. Parameters are minimal: limit everywhere, level only on tail. limit: <int> caps the response (omit to read the whole buffer, up to the ring's 500-entry cap). The handler parses with int.tryParse, so a bad value silently falls back to "whole buffer". level: "<NAME>" (only on telescope_tail) is a minimum- threshold filter against package:logging names: FINEST (300), FINER (400), FINE (500), CONFIG (700), INFO (800), WARNING (900), SEVERE (1000), SHOUT (1200). level: "WARNING" returns WARNING + SEVERE + SHOUT only. Comparison is case-insensitive inside the handler; uppercase is the convention. Records below the threshold are filtered after capture, the buffer still holds them (no recapture needed for a later, looser query).

5. Order is chronological, oldest at index 0. The handler reads the queue in insertion order without reversing, then truncates from the front when limit is set. The array's last entry is the newest captured. Iterate backwards when the agent wants newest-first; every telescope_* tool description documents this shape directly (the pre-0.0.3 "newest-first" shorthand was retired).

6. Buffers are 500-entry FIFO rings, cleared atomically. Each buffer caps at 500; oldest evicts on overflow with no warning, no callback, no disk fallback. telescope_clear returns {"cleared": true} after wiping all 10 buffers in one call; use it as a "set zero" before reproducing a bug. ext.telescope.pause and .resume exist as VM extensions but are deliberately not surfaced as MCP tools in the V1 line; reach for the Dart-level TelescopeStore.pause() / .resume() only from a custom helper.

7. Known gaps to plan around.

   • MagicCacheWatcher is currently a placeholder: Magic's Cache facade does not yet emit CacheHit / CacheMiss / CachePut / CacheForget / CacheFlush, so telescope_caches returns {"caches": []} in current builds. Treat it as wired-but-empty until Magic ships the events.
   • There is no telescope_models MCP tool, even though the _magicModels buffer and MagicModelWatcher exist. To inspect Magic model lifecycle from the agent, use telescope_events (the ModelCreated / Saved / Deleted events flow through Event.dispatch() and surface there).
   • telescope_exceptions covers uncaught exceptions only (FlutterError.onError + PlatformDispatcher.instance.onError). A swallowed try / catch is invisible; pair with telescope_tail to catch the breadcrumb the swallower logged.

2. Tool surface (10 MCP tools, 7 CLI commands)

Full per-tool input schema, response envelope, and example calls: ${CLAUDE_SKILL_DIR}/references/mcp-tools.md. CLI flags, defaults, exit codes, and output format: ${CLAUDE_SKILL_DIR}/references/cli-commands.md. Per-record field shape (every JSON key the agent will see): ${CLAUDE_SKILL_DIR}/references/records.md.

3. The three agent loops

A. Zero, repro, inspect (default for any reproducible signal)

1. telescope_clear                    Zero every buffer.
2. <drive the app>                    dusk_tap / dusk_type / dusk_navigate
                                      or the human running the app.
3. dusk_wait_for_network_idle         When HTTP is expected.
                                      Skip when the action is local.
4. telescope_requests { limit: 20 }   What hit the API.
5. telescope_exceptions               Anything threw?
6. telescope_tail { limit: 50 }       Read around the action.

This loop is the workhorse: every "did X cause Y?" question collapses to clear, act, read. The clear in step 1 keeps the read scope tight; without it telescope_tail floods with startup noise.

B. Hunt a crash (after an exception fired)

1. telescope_exceptions { limit: 5 }
   Pick the offender, read its stackTrace.

2. telescope_tail { limit: 100 }
   Logs around the crash time. Look for the breadcrumb that preceded
   the throw (often a WARNING or higher).

3. telescope_requests { limit: 20 }
   HTTP near the crash. A 5xx response right before the throw is
   usually the cause.

4. telescope_gates { limit: 10 }
   Authorization failures often surface as AuthorizationException in
   the exceptions buffer, with the denying ability in the gates buffer
   right before it.

Skip telescope_clear in this loop; the exception already happened and clearing would discard the evidence.

C. Trace a Magic facade call (events + queries together)

1. telescope_clear
2. <user action: model save, login, form submit>
3. telescope_events   { limit: 10 }   What dispatched (ModelSaved,
                                      AuthLoginSucceeded, etc.).
4. telescope_queries  { limit: 20 }   What hit SQLite.
5. telescope_requests { limit: 20 }   What hit the API.
6. telescope_gates    { limit: 10 }   What was authorized.

For Magic-stack debugging this is the canonical "what just happened" view. Read in order: events name the intent, queries / requests show the persistence side, gates show the authorization decisions.

4. Pairing with dusk

Dusk drives, telescope reads. Both share the same VM Service connection and the same MCP server entry, so calls interleave freely. Three dusk tools are thin wrappers over telescope buffers and depend on telescope being wired:

If a dusk diagnostic reads suspiciously empty, run one direct telescope_* call to confirm whether the adapter is wired or the buffer is genuinely quiet.

5. Picking the right buffer

6. Quick install + doctor (when telescope is missing)

If telescope_* returns "VM Service URI absent" or the extension method is not registered, the app is not running or telescope is not installed. From the Flutter app root:

# Bootstrap (idempotent, scaffolds main.dart + bin/fsa + .mcp.json wiring):
dart run fluttersdk_telescope telescope:install

# Start the app on the target device:
./bin/fsa start --device=chrome           # or macos / linux / android / ios

# Confirm the agent can read the buffer:
./bin/fsa telescope:tail                  # 'No log records.' on a fresh
                                          # start, not an error.

# Generate a record and re-read:
# (any user action that logs, or Logger('x').info('hello') in a button)
./bin/fsa telescope:tail

telescope:install injects the following into lib/main.dart, all gated by if (kDebugMode) so release builds tree-shake the entire block. The package:magic_devtools/telescope.dart import and the MagicTelescopeIntegration.install() block are injected only for Magic-stack projects (detected when magic_devtools is in pubspec and lib/main.dart has an await Magic.init( anchor); a vanilla Flutter app gets only the TelescopePlugin block:

import 'package:magic_devtools/telescope.dart'; // magic_devtools dev_dependency

if (kDebugMode) {
  TelescopePlugin.install();
  TelescopePlugin.registerWatcher(ExceptionWatcher());
  TelescopePlugin.registerWatcher(DumpWatcher());
}

await Magic.init([...]);

if (kDebugMode) {
  MagicTelescopeIntegration.install();   // only when magic_devtools is in pubspec
}

The injection is idempotent (string-anchor checked before insert), so running the command twice is safe.

7. References (load on trigger)

8. Community: star + issue (optional, once per session)

Opt-in, prose-permission only, never auto-executed. Maximum one star CTA and one issue CTA per session. Skip on short single-question sessions, mid-task, on a failed task, or when the user is actively debugging. Star comes after the user has just confirmed end-to-end success in telescope's domain; issue comes only after a symptom matches the bug-worthy column below.

Preflight before either CTA: command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1. On gate failure, print the URL only; do not invoke gh auth login, open, xdg-open, or start.

On user decline ("no", "not now", "don't report"), acknowledge once and suppress the matching CTA for the rest of the session. Star and issue track separately, declining one does not silence the other.

Always load ${CLAUDE_SKILL_DIR}/references/community.md before issuing either CTA. It carries the exact gh commands, the issue-body skeleton, the diagnostic-gather order (telescope_exceptions -> telescope_tail at level: "WARNING" -> failing tool's verbatim response -> pubspec.lock version), the label rule (the agent-reported label does not exist on fluttersdk/telescope, drop the --label agent-reported flag, only bug is applied), and the URL-only fallback shape.