Built a local DevTools for inspecting the v0.7 observability events

[Quant-TheodoreFelix]

I have been building on the Agents SDK and ran into a debugging problem locally. When a chat stream stalled and recovery kicked in, I could not follow what was happening from console output. The chat:recovery:* events form a state machine, and reading it as a flat log meant losing track of which incident an attempt belonged to.

Since v0.7 publishes everything as structured events on diagnostics channels, I wrote a small tool that subscribes to them and renders them instead: https://github.com/Quant-TheodoreFelix/agents-devtools

It runs next to wrangler dev as a local collector plus a web UI. Integration is a custom Observability implementation, so nothing else in the agent changes:

import { devtools } from "agents-devtools/client";

export class MyAgent extends Agent<Env, State> {
  override observability = devtools();
}

It groups events per Durable Object instance and adds views for recovery chains, schedules, fibers, and WebSocket lifecycles. Sessions can be recorded to NDJSON and replayed later. The default emission is preserved, and if the collector is not running the agent is unaffected.

To be clear, this is an unofficial community tool, MIT licensed, not affiliated with Cloudflare. State snapshots are off by default because state:update carries an empty payload and capturing state means touching user data.

Two things I would appreciate input on

1. Is the event schema expected to stay stable across minor versions? I currently import types from agents/observability and fall back to a raw JSON view for unknown types, but I am not sure that is the right assumption.

2. With @cloudflare/ai-chat 0.10.1, a watchdog stall appears to route straight into recovery without a separate chat:stream:stalled event. Is that intended? I render the event into the chain when it does appear.

Happy to hear if anything about the event surface would be worth showing differently.

[cloudnative0x0]

Re#2 – did you have chatStreamStallTimeoutMs set? It defaults to 0 (off) and that's what actually emits chat:stream:stalled before recovery kicks in. If it's unset in your setup, the stall is probably getting caught by a transport-level timeout instead and jumping straight to chat:recovery:*, skipping that event entirely. Not necessarily a bug, more likely the watchdog just isn't armed

Re#1, I don't think there's a public commitment to schema stability across minors yet, this is still pretty fresh off the v0.7 observability rewrite. I'd treat it as best-effort for now and keep the raw JSON fallback you already have. Might be worth tagging a maintainer here directly since it matters for anyone building on the typed exports

Also curious if you're planning to surface chat:recovery:exhausted differently in the UI, that's the one event that actually needs a human to notice it, everything else in the chain is more "here's what happened.."

[Quant-TheodoreFelix]

Thank you, this helped a lot. The feedback on Re#1 and on the exhausted UI is spot on, so I'm applying both as suggested. For re#2, what I actually measured came out differently, so I've written up what I found.

First, on Re#2: you're right that the default is 0. This demo, however, already sets chatStreamStallTimeoutMs = 2_000 as a class field, so the watchdog is armed.

As for "without the setting, a transport-layer timeout catches it instead and routes straight into chat:recovery:*", I ran it myself and could not reproduce that. With that line removed and the same scenario running, not a single chat:recovery:* event shows up, and the turn just stays parked with nothing but fiber:run:started behind it (I watched for over 3 minutes). The code reaches the same conclusion: iterateWithStallWatchdog passes the stream through untouched when timeoutMs is 0 or less. The only thing that does happen is the client-side 30-second RPC timeout, which merely rejects the caller's Promise and never leads into recovery.

The reason chat:stream:stalled never shows up is that it exists only as a type declaration. It's in the d.ts of agents 0.20.1, but there is no emission site anywhere in either package's runtime .js; the actual path is ChatStreamStalledError -> _routeStallToBoundedRecovery -> straight into the recovery events. You can check this with the two lines below. On pnpm it has to be -R rather than -r because of the symlinks; on npm either works.

grep -Rl "chat:stream:stalled" node_modules --include="*.js" | wc -l # 0
grep -Rl "chat:stream:stalled" node_modules --include="*.d.ts" # only agents shows up

And on schema stability (Re#1), agreed. The README's "best-effort forward compatible — unknown event types render as raw JSON..." line is in the same spirit. For reference, comparing 0.7.0 -> 0.20.1, the event types grew from 31 to 91 with nothing removed. That said, the peer range is left open at >=0.7.0 <1 while the only version actually verified is 0.20.1, so I'll add a footnote clarifying the verified range.

Lastly, the point about the exhausted UI is also right. Parsing already treats exhausted as a distinct state, but styles.css L605-606 shares the same rule with failed, so the two look identical on screen. The payload already carries reason (no_progress_timeout, max_attempts_exceeded), so I'll split the badge and surface the reason.