Repository navigation
feat(mcp): derive an API surface view from retained web network captures - #1891
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8fcadbb06c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5d1ea92458
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 64dcd2412a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0a45482093
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
0a45482 to
0ee5971
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0ee597123c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b5c3b9a966
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Charge retained deduplication sets before allocation, advertise only each analysis operation's summary from its detail output, and document that any templated group makes every API-surface page inferred.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e848938506
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Charge retained literal path copies before allocation, publish only valid media-type essences, and deduplicate examined record limitations onto the view.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3e0a725f15
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…budget Sensitive-parent refusals now use the token sensitive_values_unretained so declared literals are not echoed. A later path split is charged against bytes already retained, and the published example includes the HAR record limitation with its matching digest.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ef7b437e9d
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Charge method and origin text against the reply budget before the group key is serialized. Document that samples merge only when method, origin, and exact segment rules match.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d926092969
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Reject authorities containing a tab or newline so WHATWG cannot move userinfo into the recorded path. Charge four path copies, two method and origin copies, and each distinct content type against bytes already retained.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e6050bed14
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Total path, method, origin, and segment charges before retaining a new group. Track content types in a set so distinct MIME essences are not compared quadratically.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2e74e96fe7
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Create the per-group content-type set when the first essence is retained, and charge it before allocation. Groups with no content type no longer keep an empty set.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 05e58952c4
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Own grouping, deduplication, and combined retained/temporary resource admission in one accumulator. Charge fixed group storage before allocation and materialize only the requested page. Share recorded URL parsing between capture redaction and projection, preserving source paths and excluding ambiguous credential fields. Cover resource admission invariants and the compiled HAR-to-view workflow.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a52a7deac4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 56e1dea0c3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 69d3d69fb8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 98dac582dc
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| parent_evidence_id: parent.evidenceId, | ||
| parent_operation: "inspect_web_network_capture", | ||
| parent_digest: parent.evidenceId.slice(3), | ||
| artifact: { path: capture.artifact.path, sha256: capture.artifact.sha256 }, |
There was a problem hiding this comment.
Charge artifact path text before sealing retained views
For a session record imported from a portable Evidence bundle, artifact.path is an unconstrained string and admitCaptureClone deliberately charges no scalar text. Placing a multi-megabyte path in the result here therefore leaves the accumulator counter nearly unchanged, while sealing the view and then creating the child Evidence each encode that path with the retained parent still live; the projection can bypass its 96 MiB representation budget and block or exhaust the synchronous process before MCP transport admission rejects the response. Charge projected identity text against the accumulator before returning it.
AGENTS.md reference: AGENTS.md:L44-L44
Useful? React with 👍 / 👎.
| method, | ||
| parsed.origin, | ||
| route.value, | ||
| typeof status === "number" && status !== 0 ? status : null, |
There was a problem hiding this comment.
Treat non-integer HAR statuses as unavailable
For portable inline capture Evidence with response.status: 200.5, the capture schema accepts the reported value as generic JSON and this condition publishes 200.5 in statuses (and can use it to set mixed-statuses). HAR response statuses are integers, so malformed numeric producer values should remain unknown just like status 0 and malformed MIME values rather than becoming response facts; require an integer before retaining the status.
AGENTS.md reference: AGENTS.md:L23-L23
Useful? React with 👍 / 👎.
Summary
Agents can now turn a retained HAR capture into its API surface:
inspect_analysis_viewwithview: {"kind": "api-surface"}groups recorded requests by method, origin and path template, and each group cites the parent record ordinals it came from. It builds on the retained-view workflow from #1180 and adds no new tool.No issue is linked. This is a new view kind on an existing tool, proposed here with the implementation.
Demo
Full-quality MP4
The sample is a generated 22-request HAR for a made-up
shop.example.test, not third-party traffic. Every number in the video is copied from the CLI output on this branch.Problem and expected behavior
inspect_web_network_capturereturns one record per request in producer order. On a single-page app that means many near-identical records (GET /v1/users/1042,/v1/users/2210, ...), and an agent has to read all of them to answer "which endpoints does this app call, with what statuses". Nothing in REA groups recorded requests today.With this change,
inspect_analysis_viewreads a retained (or inline)inspect_web_network_captureHAR Evidence and returnsgroups(method, origin,path_template,templated_segments,record_ordinals,statuses,content_typesand coarseflagssuch assingle-sample,mixed-statusesandmixed-content-types), arecordssummary of examined, total and excluded counts that stays separate from group pagingcoverage, andexcluded_recordswith a reason for each record whose URL is redacted (null) or unparseable, or whose request or method is missing.Change and scope
Path segments are templated only when they match one of four exact formats:
numeric(ASCII digits),uuid(RFC 9562 text form),hex(32+ hex digits) andiso-date(a valid calendarYYYY-MM-DD). Placeholders are named after the rule ({numeric}), never after a neighbouring segment, and there is no fuzzy or cross-sample matching. So/api/v1vs/api/v2, PascalCase routes like/api/CreateDocumentvs/api/ListDocuments, the invalid date2026-13-45and short ids likeabc123stay literal. I kept the rule set this narrow on purpose: anything looser starts inventing structure the capture doesn't show.A format match is still a pattern match, so each templated segment carries
basis: "inferred"with every observed literal, and the view Evidence usesconfidence: "inferred"when any segment on the page was templated. Pages with only literal paths stayderived, and the existing view kinds are unchanged. No header, body, query or fragment values are copied into groups, and query strings are not part of the group key.The
api-surfaceresult variant has its own artifact schema with a nullable digest, because a capture writesartifact.sha256: nullwhen the digest matched asensitive_valuesdeclaration. The parent-digest integrity check runs only when both digests exist, so the shared result schema used by the other views is not relaxed.The view reads the recorded path of canonical
scheme://authority/pathURLs before WHATWG dot-segment removal, so/a/%2e%2e/adminand/adminstay apart; other spellings (https:host/x,https:///user@host/x) are excluded asurl-unparseablerather than guessed. Parents inspected withsensitive_valuesare refused with a typed unsupported error, because the view writes templates and limitation text it cannot check against declarations the parent does not retain. Each path is bounded before splitting, and only newly retained templated segments and distinct observed values count against the capture's 96 MiB reply budget.Out of scope: native mitmproxy parents (typed unsupported error), body or schema inference (#882), handler identity or causality claims (#774), and any fetching or replay.
Contract and boundary impact
src/domain/analysisView/webNetworkApiSurfaceView.ts, dispatched fromprojectAnalysisView;AnalysisViewServicepicks the Evidence confidence.inspect_analysis_view/inspect-analysis-viewacceptview.kind: "api-surface"with optionaloffset/limit;parent_operationaddsinspect_web_network_capture. Contract example insrc/contracts/analysisViewApiSurfaceExample.tscomes from a fixture run.confidenceisinferredwhen templating fired; record ordinals, exclusions and parent limitations are preserved.docs/public/product-catalog.json), package, or installation impact: authored skill text in.agents/skills/reverse-engineer-anything/references/evidence-workflows.md; no version bump needed after rebasing on main (already 39), andmetadata:checkpasses. Build outputs not committed.Evidence and regression coverage
webNetworkApiSurfaceView.test.ts(sensitive parents refused; HARstatus: 0and empty MIME treated as unknown; per-path and retained-value budgets; slashless and authority-less URLs excluded; encoded dot segments kept; literal{numeric}paths kept apart from templated ones; each rule fires and nothing else does; v1/v2, Report2/Report3 and PascalCase pairs stay separate; deterministic result for the same parent; group paging exhausts; ordinal-subset parent; null/unparseable URLs excluded; mitmproxy parent unsupported);AnalysisViewService.test.ts(inferredvsderived, existing views unchanged, null-digest parent); MCP and CLI boundary tests;scripts/verify-web-network-captures.mjsgains an api-surface step.bcd350cthe view request union has noapi-surfacekind andparent_operationhas noinspect_web_network_capture, so a capture parent cannot be projected.records: {examined: 22, total: 22, excluded: 0}andconfidence: "inferred"; capture output 41,717 bytes, view output 6,673 bytes. Example group:GET /v1/users/{numeric},record_ordinals: [1, 2, 3, 4, 5],statuses: [200, 404],flags: ["mixed-statuses"], observed values1042, 2210, 3377, 4120, 9999.verify:web:network-capturesneeds Linux and mitmdump 12.2.3, so the new step did not run on this macOS host. The api-surface path is covered by the MCP and CLI boundary tests.For evidence-bearing changes:
Validation performed
All on macOS with Node 26 and the pinned npm 11.16.0.
npm run check:prhad six failures on the first run. Five (process and Hopper timing) passed on rerun. The remaining one,machoSliceReader.test.ts("checks real /bin/ls slice ranges against its FAT table"), fails the same way onbcd350cwithout this change on this host.Compatibility, safety, and release
Review checklist
type(scope): outcome.