Repository navigation
fix(pcap): name the host tool to configure in capability refusals - #2507
Conversation
Missing or misconfigured tshark/capinfos, the unsupported macOS capture boundary and an unusable Linux prlimit were projected with the generic "unavailable for the current target; choose another target" advice, even for inspect_pcap_client, which has no target. Route tool refusals through one pcapToolUnavailable owner that names REA_TSHARK_COMMAND and REA_CAPINFOS_COMMAND, give host-boundary refusals their own reason, and keep the private workspace refusal's retryable flag like WABT and source maps do. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info
📝 Walkthrough
Merge Risk: ⚪ Minimal · up to
|
Summary
Every host-tool refusal in the new
inspect_pcap_capture/inspect_pcap_clientfamily (9581e06) told the caller "This analysis is unavailable for the current target. Choose another analysis or target." That includesinspect_pcap_client, which has no target at all. The real cause, such astsharkmissing from PATH, a relativeREA_TSHARK_COMMAND, the unsupported macOS capture boundary or an unusable Linuxprlimit, was available only indetails.reason. So an agent followingremediation.actionwould try another target instead of fixing the installation. The siblinginspect_packet_captureadapter (TsharkCaptureProvider) and sigrok/WABT already give these refusals auserMessage. The pcap family never did.No linked issue: found by a CLI sweep of new commands on a host without Wireshark.
Problem and expected behavior
Smallest trigger, on any host without Wireshark:
rea inspect-pcap-client --format jsonBefore:
{"code":"capability_unavailable","message":"This analysis is unavailable for the current target. Choose another analysis or target.", "remediation":{"action":"This analysis is unavailable for the current target. Choose another analysis or target."}, "details":{"reason":"Cannot run selected tool tshark: spawn tshark ENOENT"}}After:
{"code":"capability_unavailable","message":"Cannot run selected tool tshark: spawn tshark ENOENT. Supply Wireshark 4.x tshark and capinfos on PATH or through absolute REA_TSHARK_COMMAND and REA_CAPINFOS_COMMAND; REA does not install them.", "remediation":{"action":"<same>"}, ...}Violated invariant: a host or tool refusal names what to configure. It does not send the caller to another target (the #1224 precedent for pwntools/EVMole/firmware/LLDB, and
expectConfigurationRefusalin the CLI harness).Change and scope
src/pcap/PcapConfiguration.tsalready owns the tool environment names. It now also ownspcapToolUnavailable, the one constructor for tool refusals. All three tool-refusal sites use it: spawn ENOENT/EACCES/Windows batch and the version probe failure inPcapCommand, andPcapConfigurationFailureinPcapProvider. The reason is unchanged; onlyuserMessageis added. Missing terminal punctuation is completed so the two sentences don't run together.PcapNativeBound: the macOS/unsupported-host refusal uses its own reason asuserMessage, because it already states the Linux/Windows requirement. The Linux limiter refusal now includes the underlying cause (e.g.REA_TSHARK_PRLIMIT_COMMAND must be absolute.orENOENT … realpath '/usr/bin/prlimit') and namesREA_TSHARK_PRLIMIT_COMMAND. Before, it gave only a generic sentence.PcapSnapshot: aPrivateRuntimeRootUnavailableErrornow keeps itsretryableflag, as the WABT and source-map adapters already do. Before, a transient workspace refusal was projected as permanent.Not included: the two TShark adapters (
src/captures/TsharkCaptureProvider.tsandsrc/pcap/) duplicate tool selection and refusal wording. Merging them is a larger ownership decision. The generic projection for non-retryablePrivateRuntimeRootUnavailableErroris shared by every runtime-root consumer, so it is left unchanged here.Contribution scope: not applicable (an ordinary fix within existing boundaries).
Contract and boundary impact
Semantic owner and earliest changed stage: the pcap provider's capability refusal construction (
src/pcap).Contribution scope fit and linked maintainer decision: not applicable.
CLI and MCP/tool-catalog contract: no schema change. Error
message/remediation.actiontext changes forcapability_unavailablerefusals ofinspect_pcap_capture/inspect_pcap_client. Codes, categories anddetailsare unchanged.Provider, bridge, target-format, or platform compatibility: none.
Evidence, artifact, provenance, or reconstruction contract: none.
Target selection, authority, upstream behavior, and cleanup details: unchanged. Refusals still happen before any capture byte is read.
Generated metadata, package, or installation impact: none.
Documentation or usability only; no target interaction.
Evidence and regression coverage
tests/boundary/cli/pcapCli.test.ts: public CLI for both commands with missing tools, plus a relativeREA_TSHARK_COMMAND, through the sharedexpectConfigurationRefusalhelper.tests/boundary/pcap/pcapProviderCrossPlatform.test.ts: the unsupported-host refusal states the Linux/Windows requirement (runs on macOS).tests/boundary/pcap/pcapProvider.test.ts(Linux): tool configuration refusals carry the guidance, and a new case covers a relativeREA_TSHARK_PRLIMIT_COMMAND.src/pcapchanges stashed, the 3 new CLI cases fail (generic message); with them, all 5 pass.inspect_pcap_client/inspect_pcap_capturereturn the same text inerror.message.pcapProvider.test.tscases (including the prlimit case) did not run locally on macOS; they run in CI. I checked the prlimit message text againstdistby importingpreparePcapNativeBoundwithprocess.platformoverridden tolinux. Real Wireshark is not installed here, so no real-TShark run.Validation performed
npm run test:focused -- tests/boundary/cli/pcapCli.test.ts— 5 passed (3 failed with the fix stashed)npm run test:focused -- tests/boundary/pcap/*.test.ts tests/boundary/mcp/pcapMcp.test.ts tests/boundary/cli/pcapCli.test.ts— 11 passed, 19 skipped (Linux-only). One failure,pcapProviderCrossPlatform"rejects a path that is not a readable file", fails identically on unmodified main on macOS: the host-boundary refusal precedes the path check there.npm run test:local -- src/pcap/PcapConfiguration.test.ts src/pcap/PcapOutput.test.ts src/domain/analysisErrorProjection.test.ts src/domain/explicitSensitiveFailure.test.ts— 92 passednpm run check:fast,npm run typecheck,npm run format:check— passscripts/rea.mjs) and real MCP stdio client on macOS without Wireshark: missing tools, a version-less tool (/bin/echo), and version-reporting stubs that reach the macOS boundary refusal. All now print the specific guidance.Cost: each refusal gains about 100 characters, repeated in
messageandremediation.action(~200 bytes on a one-off error). In exchange, the agent no longer tries another target after a host refusal.Compatibility, safety, and release
details.reason, and explicit-value redaction still applies touserMessage.Before merge
type(scope): outcome.🤖 Generated with Claude Code
Summary by CodeRabbit