Skip to content

feat(http): add agent tools for HTTP fault rules #301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
erkamyaman merged 3 commits into from
Oct 11, 2026
Merged

feat(http): add agent tools for HTTP fault rules #301

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f8d2c5e
feat(http): add agent tools for HTTP fault rules
erkamyaman Oct 11, 2026
b439d20
fix(http): accept a null mock body and list rule tools under readOnly
erkamyaman Oct 11, 2026
9b9a5bd
Merge remote-tracking branch 'upstream/main' into http/agent-fault-rules
erkamyaman Oct 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion apps/docs/src/content/agents/mcp-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ The server registers tools with a colon, as `pangular:get-routes`. MCP clients s

### Read and action tools

The server marks read-only tools as read-only for your client. Six tools act on the app, so the server does not mark them:
The server marks read-only tools as read-only for your client. Eight tools act on the app, so the server does not mark them:

| Tool | Reference |
| ---------------------- | ------------------------------------------------------------------ |
Expand All @@ -217,6 +217,8 @@ The server marks read-only tools as read-only for your client. Six tools act on
| `dispatch-ngrx-action` | [Dispatch an action](./tools.md#dispatch-an-action) |
| `form-action` | [Act on a form](./tools.md#act-on-a-form) |
| `fill-form` | [Act on a form](./tools.md#act-on-a-form) |
| `set-http-rule` | [Fault rules](./tools.md#fault-rules) |
| `remove-http-rule` | [Fault rules](./tools.md#fault-rules) |
| `analog-call-api` | [Call a server route](./tools.md#call-a-server-route) |

Your client can ask you before it runs them. To drop them from the server, set `agent.readOnly`. See [Inspectors and agent tools](../getting-started/configuration.md#inspectors-and-agent-tools).
Expand Down
22 changes: 18 additions & 4 deletions apps/docs/src/content/agents/tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: Every agent tool the devtools expose, grouped by inspector, with wh
---

<ngmd-hero title="Tools" logo="https://cdn.simpleicons.org/modelcontextprotocol/71717A" gradient>
Fifty-five tools, grouped by inspector. Each one answers a question you would otherwise answer by clicking through the panel.
Fifty-eight tools, grouped by inspector. Each one answers a question you would otherwise answer by clicking through the panel.
</ngmd-hero>

# Tools
Expand Down Expand Up @@ -48,12 +48,12 @@ The URL comes from the HTTP or router report. A page that sends neither (no rout
### Action tools

<ngmd-alert severity="important">
<code>highlight</code>, <code>navigate</code>, <code>dispatch-ngrx-action</code>, <code>form-action</code>, <code>fill-form</code> and <code>analog-call-api</code> act on the app. Every other tool is marked read-only for your client.
<code>highlight</code>, <code>navigate</code>, <code>dispatch-ngrx-action</code>, <code>form-action</code>, <code>fill-form</code>, <code>set-http-rule</code>, <code>remove-http-rule</code> and <code>analog-call-api</code> act on the app. Every other tool is marked read-only for your client.
</ngmd-alert>

### Turn tools off

The server decides which tools exist. Set `agent.readOnly` to drop the six action tools. Set `agent.tools.<inspector>` to `false` to hide one inspector's tools and resources, and keep its tab. Turning an inspector off with `inspectors`, or blocking an action with `actions`, drops the matching tools too. `actions.router` is the exception: `navigate` stays and refuses `navigate`, `abort`, `replay` and `probe`. See [Inspectors and agent tools](../getting-started/configuration.md#inspectors-and-agent-tools).
The server decides which tools exist. Set `agent.readOnly` to drop the eight action tools. Set `agent.tools.<inspector>` to `false` to hide one inspector's tools and resources, and keep its tab. Turning an inspector off with `inspectors`, or blocking an action with `actions`, drops the matching tools too. `actions.router` is the exception: `navigate` stays and refuses `navigate`, `abort`, `replay` and `probe`. See [Inspectors and agent tools](../getting-started/configuration.md#inspectors-and-agent-tools).

## Source scan

Expand Down Expand Up @@ -368,6 +368,20 @@ These tools read the HttpClient calls that `withPangular()` recorded and the SSR

`list-http-calls` lists every tab and the server when you leave out `page`. With `page`, it lists that tab and the server calls of the SSR request that served it. `url` keeps calls whose URL contains the text. `failed` keeps calls with a status of 400 or more, no response, an error, or a cancel. `limit` defaults to 30 (at most 200). `preview` adds each call's response preview. Secrets in URLs, errors and previews are masked, and `url` matches the masked URL.

### Fault rules <ngmd-badge variant="alpha">Action</ngmd-badge>

These tools read and change the rules of [Fault injection](../inspectors/ssr-http.md#fault-injection), the same rules the panel shows. Rules live on the devtools server and apply to every connected tab, so the tools take no `page`. Reads: page.

| Tool | What it does | Arguments |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `list-http-rules` | Lists the rules in match order: id, on or off, method, URL pattern, where it applies (client, SSR or both) and its effect (status, delay, mock body). | none |
| `set-http-rule` | Adds a rule, or replaces the rule with `id`, and returns the saved rules. | `pattern` (required), `id`, `method`, `target`, `status`, `delayMs`, `body`, `enabled` |
| `remove-http-rule` | Removes the rule with `id` and returns the rules left. | `id` (required) |

`set-http-rule` checks its input the way the panel's form does. `pattern` is a substring or a glob where `*` matches anything, up to 500 characters. `target` is `client`, `server` or `both` (the default). `status` is one of the statuses the panel lists. `delayMs` runs from 0 to 10000. `body` is JSON text or a JSON value, up to 100,000 characters. A rule needs a `status`, a `delayMs` or a `body`, and there can be at most 50 rules. A rule that breaks one of these is refused with the reason, and nothing changes. A rule that applies to SSR takes effect on the next page load. Patterns and bodies in the answers are masked like recorded calls.

With [`actions.http`](../getting-started/configuration.md#actions) set to `false`, `set-http-rule` and `remove-http-rule` are dropped, and `list-http-rules` says that no rule applies.

## Analog

These tools cover *Analog apps. Most read your source. Some also read what the Vite plugin recorded.
Expand Down Expand Up @@ -419,7 +433,7 @@ These tools cover *Analog apps. Most read your source. Some also read what the V

`devframe_state_read` reads the devtools' live shared state. Call it without arguments to list the keys, then with `key` to read a value as JSON.

Use it for data that has no dedicated tool, such as fault rules and TransferState payloads (`pangular:http`, `pangular:http-payloads`) or live pipe usage (`pangular:pipe-usage`). See [Resources](./resources.md) for every key.
Use it for data that has no dedicated tool, such as hydration data and TransferState payloads (`pangular:http`, `pangular:http-payloads`) or live pipe usage (`pangular:pipe-usage`). See [Resources](./resources.md) for every key.

## Where to next

Expand Down
12 changes: 6 additions & 6 deletions apps/docs/src/content/getting-started/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,11 +121,11 @@ interface PangularConfig {

### Inspectors and agent tools

| Option | Default | What it does |
| -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inspectors.<name>` | `true` | `false` removes the inspector: no tab or dock, no page collector, no RPC functions, and no agent tools or resources. Its actions are blocked too. |
| `agent.readOnly` | `false` | `true` drops every agent tool that acts on the page or the server: `highlight`, `form-action`, `fill-form`, `navigate`, `dispatch-ngrx-action` and `analog-call-api`. |
| `agent.tools.<name>` | `true` | `false` hides one inspector's agent tools and resources. The tab stays. |
| Option | Default | What it does |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inspectors.<name>` | `true` | `false` removes the inspector: no tab or dock, no page collector, no RPC functions, and no agent tools or resources. Its actions are blocked too. |
| `agent.readOnly` | `false` | `true` drops every agent tool that acts on the page or the server: `highlight`, `form-action`, `fill-form`, `navigate`, `dispatch-ngrx-action`, `set-http-rule`, `remove-http-rule` and `analog-call-api`. |
| `agent.tools.<name>` | `true` | `false` hides one inspector's agent tools and resources. The tab stays. |

`agent.tools` has the same keys as `inspectors`. An inspector that is off has no agent tools, whatever `agent.tools` says.

Expand All @@ -140,7 +140,7 @@ Actions are the writes that the panel and agents make to your app or the server.
| `actions.forms` | `true` | Form writes: set value, fill, mark touched, untouched, dirty or pristine, touch all, revalidate, reset, enable, disable, submit and restore. Drops `form-action` and `fill-form`. |
| `actions.router` | `true` | Navigate, abort, replay and probe. Probe runs your app's `canMatch` guards. The `navigate` agent tool stays for `instrument` and `resolve-lazy` and refuses the other four. |
| `actions.ngrx` | `true` | Restoring NgRx state from the change log and dispatching `@ngrx/store` actions. Drops the `dispatch-ngrx-action` agent tool. |
| `actions.http` | `true` | Editing fault injection rules and SSR overrides, and clearing the HTTP timeline. |
| `actions.http` | `true` | Editing fault injection rules and SSR overrides, and clearing the HTTP timeline. Drops the `set-http-rule` and `remove-http-rule` agent tools. |
| `actions.analog` | `true` | The Analog request playground. Drops the `analog-call-api` agent tool. |
| `actions` | `true` | All of the above. |

Expand Down
15 changes: 10 additions & 5 deletions apps/docs/src/content/inspectors/ssr-http.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -271,11 +271,16 @@ The interceptor works in development builds only. In production it passes reques

## Agent tools

| Tool | What it answers | Arguments |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `pangular:list-ssr-requests` | Recent traced SSR requests: id, URL, status, render mode, render time, server calls, and whether a connected page loaded the response. | `limit` |
| `pangular:explain-ssr-request` | One request end to end: timings, kept response headers, the router's guard and resolver times, each server call with its transfer cache outcome, then the browser page with its hydration result and the calls the browser made again. | `id`, `url` |
| `pangular:list-http-calls` | The app's HttpClient calls, newest first: side (SSR or client), method, URL, status, duration, and flags for mocked, faulted, cancelled, transfer cache hit and the matched rule. | `page`, `url`, `failed`, `limit`, `preview` |
| Tool | What it answers | Arguments |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `pangular:list-ssr-requests` | Recent traced SSR requests: id, URL, status, render mode, render time, server calls, and whether a connected page loaded the response. | `limit` |
| `pangular:explain-ssr-request` | One request end to end: timings, kept response headers, the router's guard and resolver times, each server call with its transfer cache outcome, then the browser page with its hydration result and the calls the browser made again. | `id`, `url` |
| `pangular:list-http-calls` | The app's HttpClient calls, newest first: side (SSR or client), method, URL, status, duration, and flags for mocked, faulted, cancelled, transfer cache hit and the matched rule. | `page`, `url`, `failed`, `limit`, `preview` |
| `pangular:list-http-rules` | The [fault rules](#fault-injection) in match order: id, on or off, method, URL pattern, where it applies and its effect. | none |
| `pangular:set-http-rule` | Adds a fault rule, or replaces the rule with `id`. Checks the input like the form does. | `pattern`, `id`, `method`, `target`, `status`, `delayMs`, `body`, `enabled` |
| `pangular:remove-http-rule` | Removes the fault rule with `id`. | `id` |

`set-http-rule` and `remove-http-rule` change the same rules as this tab, so the rule list in this tab updates as an agent edits it. Both need `actions.http`. See [Fault rules](../agents/tools.md#fault-rules).

For the rest of this tab, agents read the `pangular:http` key with the `devframe_state_read` tool. See [Resources](../agents/resources.md).

Expand Down
15 changes: 14 additions & 1 deletion packages/devtools/src/__tests__/config.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -230,6 +230,8 @@ describe('agent tool and RPC registration', () => {
'form-action',
'highlight',
'navigate',
'remove-http-rule',
'set-http-rule',
].sort(),
);
expect(tools).toContain('inspect-forms');
Expand All @@ -244,7 +246,14 @@ describe('agent tool and RPC registration', () => {
it('drops the agent tools of a blocked action and keeps the rest', async () => {
const forms = await boot({ actions: { forms: false } });
expect(forms.actionTools.sort()).toEqual(
['analog-call-api', 'dispatch-ngrx-action', 'highlight', 'navigate'].sort(),
[
'analog-call-api',
'dispatch-ngrx-action',
'highlight',
'navigate',
'remove-http-rule',
'set-http-rule',
].sort(),
);
expect(forms.tools).toEqual(expect.arrayContaining(['inspect-forms', 'form-history']));
const router = await boot({ actions: { router: false } });
Expand All @@ -257,6 +266,10 @@ describe('agent tool and RPC registration', () => {
const ngrx = await boot({ actions: { ngrx: false } });
expect(ngrx.actionTools).not.toContain('dispatch-ngrx-action');
expect(ngrx.tools).toContain('get-ngrx-store');
const http = await boot({ actions: { http: false } });
expect(http.actionTools).not.toContain('set-http-rule');
expect(http.actionTools).not.toContain('remove-http-rule');
expect(http.tools).toContain('list-http-rules');
});

it('leaves out the RPC functions, tools and resources of a disabled inspector', async () => {
Expand Down
3 changes: 3 additions & 0 deletions packages/devtools/src/__tests__/docs-tool-count.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ const WORDS = [
'Fifty-three',
'Fifty-four',
'Fifty-five',
'Fifty-six',
'Fifty-seven',
'Fifty-eight',
];

it('states on the tools page how many tools the server registers', async () => {
Expand Down
Loading
Loading