Skip to content

Commit 869bdf1

Browse files
committed
fix(mcp): expire dead tabs on time, name forms past the cap, and cap the scan tools
Forms and router kept a page for 150 seconds after its last report, while the other stores used 15. Every per-page store now uses one expiry of 30 seconds, three heartbeat intervals, and the docs say so (#422). The forms collector keeps 100 children per group, and a failing field past that was dropped without a trace, so `explain-invalid-forms` could say no field has an error. A cut group now carries the invalid fields it left out, and the form tools name them (#423). `scan-signals` and `scan-components` answered with the whole scan. They now cap their answer, say how many items they left out, and take `filter`, `offset` and `limit` (#429).
1 parent c560c0b commit 869bdf1

31 files changed

Lines changed: 689 additions & 87 deletions

‎apps/docs/src/content/agents/mcp-server.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -271,7 +271,7 @@ The server registers tools with a colon, as `pangular:scan-routes`. MCP clients
271271

272272
Each tool also has a short title, such as **List connected pages** for `pangular_list-pages`. The server sends it as the tool's `title` and `annotations.title`, and clients show it in their tool lists and approval prompts.
273273

274-
Every tool answers with one plain text block, the answer as written: markdown for the live tools, and compact JSON for the source scans (`scan-*` and `ngrx-scan`). No tool declares an `outputSchema`, so no answer comes with `structuredContent`. `screenshot-component` adds an image block after its text. A refusal is one text block with `isError: true`.
274+
Every tool answers with one plain text block, the answer as written: markdown for the live tools, and compact JSON for the source scans (`scan-*` and `ngrx-scan`). A cut `scan-components` or `scan-signals` answer adds a note after its JSON with the `offset` of the next part. No tool declares an `outputSchema`, so no answer comes with `structuredContent`. `screenshot-component` adds an image block after its text. A refusal is one text block with `isError: true`.
275275

276276
### Read and action tools
277277

‎apps/docs/src/content/agents/tools.md‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ When the page's Angular lacks the debug API a tool needs, the tool answers **Uns
9999

100100
Lists the tabs, [Angular Native](../getting-started/angular-native.md) apps, [NativeScript](../getting-started/nativescript.md) apps and [Capacitor](../guides/capacitor.md) apps that report to the server, default page first (see [The page argument](#the-page-argument)): page id, URL, title, platform (`browser`, `Angular Native`, `NativeScript`, or `Capacitor (android)` and `Capacitor (ios)` for an app in a native WebView, followed by the page's Angular version when it reported one, as in `browser, Angular 15.2`), seconds since the last report or heartbeat, and which inspectors report. Takes no arguments. Reads: page. Use it to find the id to pass as `page`.
101101

102-
The URL comes from the HTTP or router report. A page that sends neither (no router, and no [HTTP setup](../getting-started/express.md)) still shows the URL its component tree reports, which also stands in when the other reports are more than 15 seconds older. A tab in the background stops reporting until it is shown again, so its last report is marked `(background)`: an old time there means the data is the last known state, not that the page is gone.
102+
The URL comes from the HTTP or router report. A page that sends neither (no router, and no [HTTP setup](../getting-started/express.md)) still shows the URL its component tree reports, which also stands in when the other reports are more than 30 seconds older. A tab in the background stops reporting until it is shown again, so its last report is marked `(background)`: an old time there means the data is the last known state, not that the page is gone. A tab that closes leaves the list at once. A tab that crashes or is killed without closing leaves it, with all its data, 30 seconds after its last report or heartbeat.
103103

104104
### snapshot
105105

@@ -188,17 +188,19 @@ The server decides which tools exist. Set `agent.readOnly` to keep only the `rea
188188

189189
## Source scan
190190

191-
These seven tools take no arguments. They all read your source, and answer compact JSON. Every tool that reads only your files starts with `scan-` (after its library prefix, as in `ngrx-scan` and `analog-scan-routes`).
191+
These seven tools read your source and answer compact JSON. Every tool that reads only your files starts with `scan-` (after its library prefix, as in `ngrx-scan` and `analog-scan-routes`).
192192

193-
| Tool | What it answers |
194-
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
195-
| `scan-routes` | Angular routes from your route files, with full URL path (parents and `loadChildren` prefixes included), kind (page, group, redirect or wildcard), guards, resolvers, and file and line. |
196-
| `scan-components` | Components and directives from `@Component` and `@Directive` classes, with class name, selector, kind, inputs, outputs, change detection (components only), and file and line. |
197-
| `scan-signals` | `signal()`, `computed()`, `linkedSignal()`, `effect()`, `toSignal()` and resource declarations (`resource`, `httpResource`, `rxResource`), plus signal inputs, models and queries. |
198-
| `scan-providers` | DI providers: `@Injectable` services, `inject()` calls, constructor parameters and `providers` arrays, with token, file and where each one is provided. |
199-
| `ngrx-scan` | NgRx declarations: `@ngrx/store` actions (with their type strings in `types`), reducers, effects, selectors, features and store setup, and `@ngrx/signals` `signalStore` (with its members), `signalState` and `signalMethod`. |
200-
| `scan-pipes` | Custom `@Pipe` classes, and built-in pipes from `@angular/common` in use in templates, with purity, standalone status, and where each is declared or used. |
201-
| `scan-build` | The project name, the Angular and TypeScript versions, SSR status, the Analog version in Analog apps, and a `builtAt` timestamp. |
193+
| Tool | What it answers | Arguments |
194+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
195+
| `scan-routes` | Angular routes from your route files, with full URL path (parents and `loadChildren` prefixes included), kind (page, group, redirect or wildcard), guards, resolvers, and file and line. | None |
196+
| `scan-components` | Components and directives from `@Component` and `@Directive` classes, with class name, selector, kind, inputs, outputs, change detection (components only), and file and line. | `filter`, `offset`, `limit` |
197+
| `scan-signals` | `signal()`, `computed()`, `linkedSignal()`, `effect()`, `toSignal()` and resource declarations (`resource`, `httpResource`, `rxResource`), plus signal inputs, models and queries. | `filter`, `offset`, `limit` |
198+
| `scan-providers` | DI providers: `@Injectable` services, `inject()` calls, constructor parameters and `providers` arrays, with token, file and where each one is provided. | None |
199+
| `ngrx-scan` | NgRx declarations: `@ngrx/store` actions (with their type strings in `types`), reducers, effects, selectors, features and store setup, and `@ngrx/signals` `signalStore` (with its members), `signalState` and `signalMethod`. | None |
200+
| `scan-pipes` | Custom `@Pipe` classes, and built-in pipes from `@angular/common` in use in templates, with purity, standalone status, and where each is declared or used. | None |
201+
| `scan-build` | The project name, the Angular and TypeScript versions, SSR status, the Analog version in Analog apps, and a `builtAt` timestamp. | None |
202+
203+
`scan-components` and `scan-signals` answer at most `limit` items (default 200, at most 1,000) and at most 20,000 characters. A list that fits is the JSON array alone. A cut list is followed by a note with the items shown, the total and the `offset` of the next part, such as `Showing signals 1-200 of 450; 250 more not shown. Pass offset: 200 for the next part`. `filter` keeps the items whose fields contain the text, in any case: class name, selector, kind and file for components, and name, kind, file and component for signals.
202204

203205
## Components, signals and DI
204206

@@ -756,6 +758,8 @@ Answers about large forms are cut to keep an agent's context small. Each cut end
756758

757759
With `path`, `inspect-forms`, `explain-invalid-forms` and `inspect-form-payload` start at that group or field, so a cut part of the form can be read one group at a time.
758760

761+
The page itself reads at most 100 fields per group or array, and 8 levels deep. A group cut there carries `truncated` (the fields left out) and `truncatedInvalid` (up to 20 paths of invalid fields left out). The tools then say which group was cut, as in `keeps the first 100 of 150 fields (50 more not read)`, and `path` can't reach those fields. `explain-invalid-forms` and `explain-submit` name each invalid field past the cap, with its error when a Signal Form's `errorSummary` has it. If the form is invalid and no field the page read has an error, `explain-invalid-forms` says the failing field may be past the cap.
762+
759763
### Track changes
760764

761765
| Tool | What it answers | Arguments |

‎apps/docs/src/content/getting-started/popup-and-hub.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -211,7 +211,7 @@ Without the hub (for example the standalone CLI, or a panel mounted with `initDe
211211

212212
### Tab hashes
213213

214-
The URL hash selects a tab. Open `/__devframes/pangular/#tab=signals` to land on the Signals tab. Switching tabs updates the hash, so you can copy the URL at any time.
214+
The URL hash selects a tab. Open `/__devframes/pangular/#tab=signals` to land on the Signals tab. Switching tabs updates the hash, so you can copy the URL at any time. The panel also follows a hash that changes after it loads, such as a link inside the panel or `location.hash = '#tab=forms'`.
215215

216216
| Tab | Hash |
217217
| ---------- | ----------------- |
@@ -265,7 +265,7 @@ If the panel cannot reach the server when it opens, it says so and tries again a
265265

266266
### Tabs in the background
267267

268-
A browser tab in the background runs its timers about once a minute. The app page stops reading itself while its tab is hidden and tells the server, and the server keeps its last data instead of dropping it. The panel then says **Page in background, showing the last data.** When you switch back, the page sends fresh data. If a hidden tab stops answering for 5 minutes, the server drops it.
268+
A browser tab in the background runs its timers about once a minute. The app page stops reading itself while its tab is hidden and tells the server, and the server keeps its last data instead of dropping it. The panel then says **Page in background, showing the last data.** When you switch back, the page sends fresh data. If a hidden tab stops answering for 5 minutes, the server drops it. A visible tab that crashes or is killed without closing is dropped, with the data of every inspector, 30 seconds after its last report or heartbeat.
269269

270270
## Troubleshooting
271271

‎apps/docs/src/content/guides/write-a-plugin.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -304,7 +304,7 @@ A `read` tool that calls `runPageAction` gets a refusal instead. Every answer st
304304
| Concern | How |
305305
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
306306
| Redaction | The page and the server run every view through `serialize()`, so `redaction.secretNames`, JWTs and bearer tokens are masked. |
307-
| Pages | Each report carries the page id. The server keeps one entry per page, drops it 15 seconds after the page's last report or heartbeat, and forgets it when the tab closes. |
307+
| Pages | Each report carries the page id. The server keeps one entry per page, drops it 30 seconds after the page's last report or heartbeat, and forgets it when the tab closes. |
308308
| Cost | `collect` runs while someone watches, at most once a second for page updates and `refresh()`. It also runs right away for the first report, even while nobody watches, and when someone starts watching. While someone watches, a finished page action or a plugin registering runs it right away too. An unchanged report is skipped, and the page heartbeat keeps an idle page listed. |
309309
| Size | Up to 20 sections, 12 columns, 200 rows or items per section, and 2,000 characters per text. Unknown section kinds are dropped. |
310310
| Failures | A plugin that throws shows as **Failed** with its message. The other plugins keep running. |

‎apps/docs/src/content/inspectors/components.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ Each row shows the class name and the host tag. Routed components get a chip wit
2525
- **Click** a row, or press Enter or Space, to select it. Click it again to clear the selection.
2626
- **Expand all** opens every row and **Collapse all** closes them down to the top level. Both are off while you filter, because the filter already opens every row that leads to a match.
2727
- **Pick component on page** selects the component behind an element you click in the app. See [Pick a component on the page](#pick-a-component-on-the-page).
28+
- In a panel narrower than 600px, **Directive hosts**, **Expand all**, **Collapse all** and **Pick component on page** show as icons next to the count. Hover an icon to see its name. Screen readers still hear the full name.
29+
- A name or tag that doesn't fit its row ends with an ellipsis. Hover it to see the full text, or focus the row to show the full name and tag below it. Press Escape to hide it.
2830

2931
### Directive hosts
3032

@@ -317,7 +319,7 @@ The live tree reads `window.ng`, which only development builds expose. It uses t
317319

318320
### Refresh rate
319321

320-
On Angular 20 and later, the page reads the tree about 250 ms after Angular runs change detection, and every 4 seconds as a heartbeat. Until the app bootstraps, it reads the tree every 3 seconds. It also reads it at once when you select an instance. It reads the detail block only for the selected instance. The server drops a page after 15 seconds without a report or a heartbeat, unless its tab is in the background. See [Tabs in the background](../getting-started/popup-and-hub.md#tabs-in-the-background).
322+
On Angular 20 and later, the page reads the tree about 250 ms after Angular runs change detection, and every 4 seconds as a heartbeat. Until the app bootstraps, it reads the tree every 3 seconds. It also reads it at once when you select an instance. It reads the detail block only for the selected instance. The server drops a page after 30 seconds without a report or a heartbeat, unless its tab is in the background. See [Tabs in the background](../getting-started/popup-and-hub.md#tabs-in-the-background).
321323

322324
## How to use it
323325

‎apps/docs/src/content/inspectors/forms.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,8 @@ If you load `/examples/forms` directly, the form registers before the overlay lo
261261

262262
The agent tools cut answers about large forms, so one form cannot fill an agent's context. A cut answer says how many fields or lines it left out and how to narrow the answer, for example with `path`, `form` or a later `since` marker. See [Tools](../agents/tools.md#read-form-state) for each limit.
263263

264+
The page reads at most 100 fields per group or array, so a form with a wider group never sends the rest. The agent tools say which group was cut and how many fields it left out, and `explain-invalid-forms` names the invalid fields past the cap.
265+
264266
### Snapshot limits
265267

266268
The page keeps up to 20 snapshots, and a reload clears them. Restore fails when the form's shape has changed, and it keeps the current value of secret fields.

‎apps/docs/src/content/inspectors/signals.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -246,7 +246,7 @@ The `pangular:highlight` tool also switches the graph to the component it highli
246246

247247
| Tool or resource | Kind | What it does |
248248
| -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
249-
| `pangular:scan-signals` | tool | Signal declarations from source, with signal inputs, models and queries. |
249+
| `pangular:scan-signals` | tool | Signal declarations from source, with signal inputs, models and queries. Pages through a large project with `filter` and `offset`. |
250250
| `pangular:inspect-signals` | tool | The graph the page reported, with edges, resources and history. Takes a host tag, class name, instance id, `root` or a route path. |
251251
| `pangular:watch-signal` | tool | Watches a signal and turns write stacks on or off on a page. |
252252
| `pangular:highlight` | tool | Highlights a component and makes it the target of the graph. |

0 commit comments

Comments
 (0)