[PR #2487] [MERGED] feat(signals): discover installed decoders and option help #5266

Closed
opened 2026-10-31 01:05:17 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2487
Author: @Olorinm
Created: 10/13/2026
Status: ✅ Merged
Merged: 10/13/2026
Merged by: @baron

Base: main ← Head: feat/signal-decoder-discovery


📝 Commits (5)

  • 18a0c05 feat(signals): discover installed decoders and selected option help
  • f6293f5 fix(signals): bound retained discovery data and preserve resource failures
  • c2d5bdf fix(signals): complete CLI help and portable decoder patterns
  • 4e76f3b test(signals): verify case-insensitive decoder help queries
  • 6a13062 fix(signals): retain discovery operation across cleanup retries

📊 Changes

19 files changed (+972 additions, -191 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+3 -0)
📝 .github/workflows/real-signal-recording.yml (+1 -1)
📝 docs/signal-recordings.md (+34 -0)
📝 scripts/verify-signal-recording.mjs (+104 -2)
📝 src/application/CapabilityInventory.ts (+1 -1)
📝 src/application/signals/SignalRecordingService.ts (+62 -8)
📝 src/cli/signalCommands.ts (+69 -26)
📝 src/cliCommandNames.ts (+1 -0)
📝 src/contracts/signals/signalToolContracts.ts (+20 -0)
📝 src/contracts/toolEffects.ts (+5 -0)
➕ src/domain/signals/signalDecoders.ts (+86 -0)
📝 src/process/ArtifactAnalysisResources.ts (+27 -18)
📝 src/server/registerSignalTools.ts (+13 -0)
📝 src/signals/SigrokRecordingProvider.ts (+178 -100)
➕ src/signals/parseDecoderDiscovery.ts (+79 -0)
📝 tests/boundary/cli/signalCleanup.test.ts (+6 -0)
📝 tests/boundary/mcp/signalRecordingMcp.test.ts (+47 -34)
➕ tests/boundary/signals/decoderDiscovery.test.ts (+48 -0)
📝 tests/boundary/signals/recordingProvider.test.ts (+188 -1)

📄 Description

Summary

Add inspect_signal_decoders / inspect-signal-decoders so an analyst can discover installed decoder IDs and read the selected decoder's channel/options help before calling decode_signal_recording. For example, { "decoder": "uart", "query": "baud" } returns the installed baud-rate option text with its original help-line number.

Problem and expected behavior

Recording decoding currently requires an exact decoder/settings string but provides no installation-specific discovery. Query either the installed ID/name catalog or one exact decoder's literal help; use case-insensitive substring selection and offset/limit paging (50 by default, explicit full output available). Return examined/matching/returned counts, warnings and executable provenance. No linked issue: this is a focused follow-up to #2339.

Change and scope

Extend the existing sigrok adapter, sharing its executable/version checks, one-operation admission, enforced Linux limits, owned command execution and cleanup. CLI/MCP share validation and Evidence. The common resource owner accepts a per-request operation so discovery failures are attributed correctly without creating an independent queue. This small common-owner change is identical to #2496; both PRs are independently based on main. Rejected version probes and malformed output retain captured diagnostics.

Contract and boundary impact

  • Semantic owner: strict discovery schemas; adapter parses the 0.7.2 catalog while help remains producer text, not an invented parameter schema.
  • Scope decision: not applicable to the new-provider/target-execution gate; this extends the already integrated sigrok provider's installation inspection. No recording, target execution, hardware scan/acquisition, raw flags or new engine.
  • CLI/MCP: additive named tool/command. decoder: null selects catalog; a decoder ID selects help. query, offset, limit apply to matches. CLI --all conflicts with --limit.
  • Compatibility: Linux, sigrok-cli 0.7.2 with libsigrokdecode and util-linux prlimit, as for recording analysis.
  • Provenance: configured/resolved executable and limiter paths/digests, complete version banner, exact argv, diagnostics and coverage. Modules/libraries remain trusted and not fully fingerprinted. Each call probes again; no cache/frozen-catalog claim.
  • Resources: existing 4 MiB command output/30-second deadline and inherited resource ceilings. Refuse excessive help-line expansion as a typed resource failure with captured output; copy retained page strings independently of the full producer buffer. Discovery and decoding share admission; failed cleanup remains owned and completed Evidence survives late cancellation/cleanup errors.
  • Generated/install impact: contract sources, existing guide, authored skill and real-provider lane updated. No dependency, installer or generated-output changes.

Expected effects:

  • Read existing tool files and installation metadata.
  • Launch an owned local analysis tool.
  • Create and clean a private temporary workspace.

Evidence and regression coverage

Provider-boundary tests cover catalog/help queries, paging, no matches, selector validation, malformed help identity, version/nonzero/output-limit failures, shared admission, shutdown, executable changes, cancellation and cleanup retry. SDK-converted schemas and actionable unavailable diagnostics are exercised through MCP. Existing capture regressions also pass after the shared-owner change.

The real verifier compares help lines against direct sigrok output, checks installed UART discovery, mixed-case search, pagination/negative queries, CLI/MCP parity and retained provenance, then verifies cleanup. Its existing recording workflow still passes.

  • Observed facts and interpretation remain distinguishable.
  • Provenance and failed attempts remain preserved.
  • Coverage and unavailable outcomes remain explicit.

Validation performed

Cleanup follow-up on 6a1306243: retained workspaces now keep the operation that acquired them alongside process ownership. Shutdown and pre-request cleanup retries use that identity, rather than the provider default or the next request's operation. Extended the existing decoder discovery boundary regression to reject a different operation while cleanup is pending, verify two failed shutdown attempts keep the original operation, and then complete cleanup. No public contract or execution scope changed.

  • Latest local validation: 62 focused regressions, npm run check, git diff --check, and a Gitleaks diff scan passed.
  • Native sigrok verification on 6a1306243 passed. Full CI is still running; the historical runs below apply to the preceding heads.

Earlier feature validation:

  • npm run check, npm run docs:check, npm run verify:test-discovery — passed; 1,023 test files discovered exactly once.
  • npm run jscpd — passed, 2.95% duplicated lines.
  • Focused local regression on the rebased head — 55 passed, including the product catalog, CLI help and portable advertised-pattern checks.
  • Linux verification on 4e76f3b64 — 57 tests and 16 real sigrok CLI/MCP cases passed.
  • Full upstream CI on 4e76f3b64 — passed.
  • Final staged-diff Gitleaks scan and git diff --check — passed.

Six discovery cases in that run measured 104–562 ms per MCP call and 5.9–11.0 KB response envelopes. tokenx estimates including one advertised definition, request and response were 6,020–7,758 tokens. Warm MCP server, fresh native processes, no filesystem-cache control; these are estimates, not billed usage or evidence of improved agent task completion. Model-driven selection, CPU time and peak process-family memory are unmeasured; no speedup claim.

Compatibility, safety, and release

No previously valid decoding call changes. macOS/Windows integration remains unsupported; local native output inspection does not establish those hosts. Caller-selected help may expose installation details; ambient environment is not serialized. Existing per-process limits are not an OS sandbox or aggregate quota.

Before merge

  • Concrete problem and one focused outcome.
  • Existing provider authority preserved; no material scope expansion.
  • No linked issue reason stated above.
  • Observable behavior and meaningful failures covered.
  • Owning contracts/docs updated and real public workflows executed.
  • Final diff checked for secrets, unrelated changes and unsupported claims.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2487 **Author:** [@Olorinm](https://github.com/Olorinm) **Created:** 10/13/2026 **Status:** ✅ Merged **Merged:** 10/13/2026 **Merged by:** [@baron](https://github.com/baron) **Base:** `main` ← **Head:** `feat/signal-decoder-discovery` --- ### 📝 Commits (5) - [`18a0c05`](https://github.com/morluto/rea/commit/18a0c057c6f971652e08ac1ac9908e5937dcc0ff) feat(signals): discover installed decoders and selected option help - [`f6293f5`](https://github.com/morluto/rea/commit/f6293f5a9802a3770751638ac64ef66c8a540051) fix(signals): bound retained discovery data and preserve resource failures - [`c2d5bdf`](https://github.com/morluto/rea/commit/c2d5bdf722900f2ff4b72b148f1db0885bc636e5) fix(signals): complete CLI help and portable decoder patterns - [`4e76f3b`](https://github.com/morluto/rea/commit/4e76f3b64d51dfc430f4bcac29b9e4b7f7498a38) test(signals): verify case-insensitive decoder help queries - [`6a13062`](https://github.com/morluto/rea/commit/6a130624334e50cc0244e28777812fe5780855ec) fix(signals): retain discovery operation across cleanup retries ### 📊 Changes **19 files changed** (+972 additions, -191 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+3 -0) 📝 `.github/workflows/real-signal-recording.yml` (+1 -1) 📝 `docs/signal-recordings.md` (+34 -0) 📝 `scripts/verify-signal-recording.mjs` (+104 -2) 📝 `src/application/CapabilityInventory.ts` (+1 -1) 📝 `src/application/signals/SignalRecordingService.ts` (+62 -8) 📝 `src/cli/signalCommands.ts` (+69 -26) 📝 `src/cliCommandNames.ts` (+1 -0) 📝 `src/contracts/signals/signalToolContracts.ts` (+20 -0) 📝 `src/contracts/toolEffects.ts` (+5 -0) ➕ `src/domain/signals/signalDecoders.ts` (+86 -0) 📝 `src/process/ArtifactAnalysisResources.ts` (+27 -18) 📝 `src/server/registerSignalTools.ts` (+13 -0) 📝 `src/signals/SigrokRecordingProvider.ts` (+178 -100) ➕ `src/signals/parseDecoderDiscovery.ts` (+79 -0) 📝 `tests/boundary/cli/signalCleanup.test.ts` (+6 -0) 📝 `tests/boundary/mcp/signalRecordingMcp.test.ts` (+47 -34) ➕ `tests/boundary/signals/decoderDiscovery.test.ts` (+48 -0) 📝 `tests/boundary/signals/recordingProvider.test.ts` (+188 -1) </details> ### 📄 Description ## Summary Add `inspect_signal_decoders` / `inspect-signal-decoders` so an analyst can discover installed decoder IDs and read the selected decoder's channel/options help before calling `decode_signal_recording`. For example, `{ "decoder": "uart", "query": "baud" }` returns the installed baud-rate option text with its original help-line number. ## Problem and expected behavior Recording decoding currently requires an exact decoder/settings string but provides no installation-specific discovery. Query either the installed ID/name catalog or one exact decoder's literal help; use case-insensitive substring selection and offset/limit paging (50 by default, explicit full output available). Return examined/matching/returned counts, warnings and executable provenance. No linked issue: this is a focused follow-up to #2339. ## Change and scope Extend the existing sigrok adapter, sharing its executable/version checks, one-operation admission, enforced Linux limits, owned command execution and cleanup. CLI/MCP share validation and Evidence. The common resource owner accepts a per-request operation so discovery failures are attributed correctly without creating an independent queue. This small common-owner change is identical to #2496; both PRs are independently based on main. Rejected version probes and malformed output retain captured diagnostics. ## Contract and boundary impact - Semantic owner: strict discovery schemas; adapter parses the 0.7.2 catalog while help remains producer text, not an invented parameter schema. - Scope decision: not applicable to the new-provider/target-execution gate; this extends the already integrated sigrok provider's installation inspection. No recording, target execution, hardware scan/acquisition, raw flags or new engine. - CLI/MCP: additive named tool/command. `decoder: null` selects catalog; a decoder ID selects help. `query`, `offset`, `limit` apply to matches. CLI `--all` conflicts with `--limit`. - Compatibility: Linux, sigrok-cli 0.7.2 with libsigrokdecode and util-linux prlimit, as for recording analysis. - Provenance: configured/resolved executable and limiter paths/digests, complete version banner, exact argv, diagnostics and coverage. Modules/libraries remain trusted and not fully fingerprinted. Each call probes again; no cache/frozen-catalog claim. - Resources: existing 4 MiB command output/30-second deadline and inherited resource ceilings. Refuse excessive help-line expansion as a typed resource failure with captured output; copy retained page strings independently of the full producer buffer. Discovery and decoding share admission; failed cleanup remains owned and completed Evidence survives late cancellation/cleanup errors. - Generated/install impact: contract sources, existing guide, authored skill and real-provider lane updated. No dependency, installer or generated-output changes. Expected effects: - [x] Read existing tool files and installation metadata. - [x] Launch an owned local analysis tool. - [x] Create and clean a private temporary workspace. ## Evidence and regression coverage Provider-boundary tests cover catalog/help queries, paging, no matches, selector validation, malformed help identity, version/nonzero/output-limit failures, shared admission, shutdown, executable changes, cancellation and cleanup retry. SDK-converted schemas and actionable unavailable diagnostics are exercised through MCP. Existing capture regressions also pass after the shared-owner change. The real verifier compares help lines against direct sigrok output, checks installed UART discovery, mixed-case search, pagination/negative queries, CLI/MCP parity and retained provenance, then verifies cleanup. Its existing recording workflow still passes. - [x] Observed facts and interpretation remain distinguishable. - [x] Provenance and failed attempts remain preserved. - [x] Coverage and unavailable outcomes remain explicit. ## Validation performed Cleanup follow-up on `6a1306243`: retained workspaces now keep the operation that acquired them alongside process ownership. Shutdown and pre-request cleanup retries use that identity, rather than the provider default or the next request's operation. Extended the existing decoder discovery boundary regression to reject a different operation while cleanup is pending, verify two failed shutdown attempts keep the original operation, and then complete cleanup. No public contract or execution scope changed. - Latest local validation: 62 focused regressions, `npm run check`, `git diff --check`, and a Gitleaks diff scan passed. - [Native sigrok verification on 6a1306243](https://github.com/morluto/rea/actions/runs/38356846409) passed. Full CI is still running; the historical runs below apply to the preceding heads. Earlier feature validation: - `npm run check`, `npm run docs:check`, `npm run verify:test-discovery` — passed; 1,023 test files discovered exactly once. - `npm run jscpd` — passed, 2.95% duplicated lines. - Focused local regression on the rebased head — 55 passed, including the product catalog, CLI help and portable advertised-pattern checks. - [Linux verification on 4e76f3b64](https://github.com/morluto/rea/actions/runs/38352271396) — 57 tests and 16 real sigrok CLI/MCP cases passed. - [Full upstream CI on 4e76f3b64](https://github.com/morluto/rea/actions/runs/38352271653) — passed. - Final staged-diff Gitleaks scan and `git diff --check` — passed. Six discovery cases in that run measured 104–562 ms per MCP call and 5.9–11.0 KB response envelopes. `tokenx` estimates including one advertised definition, request and response were 6,020–7,758 tokens. Warm MCP server, fresh native processes, no filesystem-cache control; these are estimates, not billed usage or evidence of improved agent task completion. Model-driven selection, CPU time and peak process-family memory are unmeasured; no speedup claim. ## Compatibility, safety, and release No previously valid decoding call changes. macOS/Windows integration remains unsupported; local native output inspection does not establish those hosts. Caller-selected help may expose installation details; ambient environment is not serialized. Existing per-process limits are not an OS sandbox or aggregate quota. ## Before merge - [x] Concrete problem and one focused outcome. - [x] Existing provider authority preserved; no material scope expansion. - [x] No linked issue reason stated above. - [x] Observable behavior and meaningful failures covered. - [x] Owning contracts/docs updated and real public workflows executed. - [x] Final diff checked for secrets, unrelated changes and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-10-31 01:05:17 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#5266
No description provided.