[PR #6995] [MERGED] feat(workflows): expose guided prompts through CLI and MCP #7558

New issue

Closed

opened 2026-11-03 13:38:42 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-03 13:38:42 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/6995
Author: @Deepak-Kambala
Created: 10/24/2026
Status: ✅ Merged
Merged: 10/28/2026
Merged by: @gensokyo-dev

Base: main ← Head: feat/6918-guided-workflows

📝 Commits (9)

392af8b feat(workflows): expose guided prompts through CLI and MCP
0037f1b fix(workflows): address guided workflow review findings
387ecae Merge remote-tracking branch 'origin/main' into fix/6918-guided-workflows-followup
24d131f fix(workflows): preserve scoped contracts and actionable validation
58a6b70 chore: merge latest main for guided workflow validation
92b6bec test(workflows): allow bounded CLI startup on shared hosts
265d136 test(workflows): audit guidance effects and content provenance
b2d02cc perf(workflows): defer rendering and separate catalog scope
3ea8d51 chore: sync main for guided workflow integration

📊 Changes

24 files changed (+904 additions, -46 deletions)

View changed files

📝 docs/mcp-prompts.md (+14 -0)
➕ src/application/GuidedWorkflowAccess.ts (+94 -0)
📝 src/catalogIdentity.ts (+1 -1)
📝 src/cli.ts (+2 -0)
➕ src/cli/guidedWorkflowCommands.ts (+68 -0)
📝 src/cliCommandNames.ts (+1 -0)
📝 src/contracts/applicationToolContracts.ts (+27 -0)
➕ src/contracts/guidedWorkflowSchemas.ts (+45 -0)
📝 src/contracts/promptContracts.ts (+51 -22)
➕ src/contracts/promptToolFamilyScope.ts (+23 -0)
📝 src/contracts/toolEffects.test.ts (+2 -0)
📝 src/contracts/toolEffects.ts (+2 -0)
📝 src/mcpDoctor.ts (+1 -1)
📝 src/server/promptArguments.ts (+6 -6)
📝 src/server/registerApplicationTools.ts (+2 -0)
➕ src/server/registerGuidedWorkflowTool.test.ts (+271 -0)
➕ src/server/registerGuidedWorkflowTool.ts (+20 -0)
📝 src/server/registerPrompts.ts (+3 -11)
📝 tests/boundary/cli/cliStartupImports.test.ts (+20 -0)
📝 tests/boundary/cli/directAnalysisStatus.test.ts (+1 -1)

...and 4 more files

📄 Description

Summary

Fixes #6918. Add rea guided-workflows and the target-free guided_workflows MCP tool so clients can list existing workflow requirements and render one workflow through the same contracts as native MCP prompts.

The shared typed application parser preserves nested error paths and rejects unknown context fields and every forbidden list field. MCP uses the native prompt family scope. Standalone request/result schemas avoid catalog initialization cycles; an explicit object output root prevents legacy SDK response wrapping. Template rendering is independent of catalog visibility, and CLI loads the application only when invoked, preserving existing lazy startup. Rendering produces guidance without target analysis or session changes; no new provider or execution authority is introduced.

Validation

Focused CLI startup, built guidance CLI, full/compact stdio MCP, native prompts/completion/lifecycle and scoped status tests: 35 passed across focused runs. Startup regressions verify both command registration and actual guidance rendering leave the tool catalog/provider composition unloaded.
Effects/provenance contract audits: 30 passed. The earlier eight in-memory ownership/adapter tests passed, including an execution spy and native completion availability.
Synced main b594fbc3e; repeated nine compiled startup/MCP boundary tests, npm run docs:check (nine conformance tests), and npm run check:fast: all passed. Bounded affected-file typed lint passed with existing warnings in untouched sections; 24-file formatting and diff checks passed. Full check:pr was not run locally. Full-profile MCP tests have a bounded 60 s budget after full-profile boundary cases took 22–39 s under concurrent shared-host work.

Performance and real input

Compared 265d13647 with the startup fix b2d02cca5 on the same pinned base/dependencies, before the final independent main sync: 18 alternating fresh CLI processes covered help, selected guidance rendering and inspect-elf-notes /usr/bin/true. All stdout SHA-256s matched between old/new lanes. Sampled process-family RSS fell from 230–253 to 208–212 MiB; mean CPU across the equally weighted tasks fell from 3.57 to 3.02 s. Mean elapsed help/render/ELF times were 3.37/3.28/3.43 s before and 2.73/2.76/2.97 s after, with overlapping ranges. Output tokenx estimates stayed 4,331/696/1,600. The real ELF SHA-256 was c79bf44242829108e323378531f4ac839513ca1fba45efd6583643526e1e9fd2.

On final 3ea8d5167, three alternating fresh SDK client/server sessions per entrypoint completed one scoped catalog discovery and three list/render pairs, then closed both processes. Native prompt and tool guidance/IDs matched exactly; /usr/bin/true was selection data only here. Tokenx estimates for one pair plus the complete scoped catalog were 69,831 native / 71,674 tool; the added tool advertisement was 306 tokens. These serialized estimates include structured-content/text duplication, not model billing. Warm pairs overlapped at 7–31 ms; first tool pair cost 665–704 ms versus native 18–30 ms. Complete client/session workloads took 5.7–7.0 / 6.1–9.0 s elapsed, 6.4–7.9 / 7.3–10.2 s CPU, and 433–434 / 463–470 MiB sampled family RSS (native/tool). Totals include SDK and measurement bookkeeping. This compatibility entrypoint has measured overhead; no general latency improvement is claimed. RSS sampling was every 10 ms on a shared Linux host; filesystem caches were not flushed, and no builds or heavy checks overlapped the profiles.

Author readiness

Human owner: @Deepak-Kambala

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

_{🔄 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/6995 **Author:** [@Deepak-Kambala](https://github.com/Deepak-Kambala) **Created:** 10/24/2026 **Status:** ✅ Merged **Merged:** 10/28/2026 **Merged by:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Base:** `main` ← **Head:** `feat/6918-guided-workflows` --- ### 📝 Commits (9) - [`392af8b`](https://github.com/morluto/rea/commit/392af8be821752331f902d54efa4f79ef589fc9c) feat(workflows): expose guided prompts through CLI and MCP - [`0037f1b`](https://github.com/morluto/rea/commit/0037f1b5135c55ba5385e995af9535cf30810fdc) fix(workflows): address guided workflow review findings - [`387ecae`](https://github.com/morluto/rea/commit/387ecae88802b9e9f1dc5dd0aa425ca4aeb8400e) Merge remote-tracking branch 'origin/main' into fix/6918-guided-workflows-followup - [`24d131f`](https://github.com/morluto/rea/commit/24d131f406fb218d9c8aa1863ff3776f1a0746c1) fix(workflows): preserve scoped contracts and actionable validation - [`58a6b70`](https://github.com/morluto/rea/commit/58a6b70e1e7da9252a26848c607993fbe948b0f4) chore: merge latest main for guided workflow validation - [`92b6bec`](https://github.com/morluto/rea/commit/92b6becef0f9b47c8493fe5051f9eb089e32a4ff) test(workflows): allow bounded CLI startup on shared hosts - [`265d136`](https://github.com/morluto/rea/commit/265d1364742986423d0a11ffce2b1122a8089c60) test(workflows): audit guidance effects and content provenance - [`b2d02cc`](https://github.com/morluto/rea/commit/b2d02cca5aaf2319eff035efd507080357542d07) perf(workflows): defer rendering and separate catalog scope - [`3ea8d51`](https://github.com/morluto/rea/commit/3ea8d5167a1e1253bd92f8f93626a0da0b64d816) chore: sync main for guided workflow integration ### 📊 Changes **24 files changed** (+904 additions, -46 deletions) <details> <summary>View changed files</summary> 📝 `docs/mcp-prompts.md` (+14 -0) ➕ `src/application/GuidedWorkflowAccess.ts` (+94 -0) 📝 `src/catalogIdentity.ts` (+1 -1) 📝 `src/cli.ts` (+2 -0) ➕ `src/cli/guidedWorkflowCommands.ts` (+68 -0) 📝 `src/cliCommandNames.ts` (+1 -0) 📝 `src/contracts/applicationToolContracts.ts` (+27 -0) ➕ `src/contracts/guidedWorkflowSchemas.ts` (+45 -0) 📝 `src/contracts/promptContracts.ts` (+51 -22) ➕ `src/contracts/promptToolFamilyScope.ts` (+23 -0) 📝 `src/contracts/toolEffects.test.ts` (+2 -0) 📝 `src/contracts/toolEffects.ts` (+2 -0) 📝 `src/mcpDoctor.ts` (+1 -1) 📝 `src/server/promptArguments.ts` (+6 -6) 📝 `src/server/registerApplicationTools.ts` (+2 -0) ➕ `src/server/registerGuidedWorkflowTool.test.ts` (+271 -0) ➕ `src/server/registerGuidedWorkflowTool.ts` (+20 -0) 📝 `src/server/registerPrompts.ts` (+3 -11) 📝 `tests/boundary/cli/cliStartupImports.test.ts` (+20 -0) 📝 `tests/boundary/cli/directAnalysisStatus.test.ts` (+1 -1) _...and 4 more files_ </details> ### 📄 Description ## Summary Fixes #6918. Add `rea guided-workflows` and the target-free `guided_workflows` MCP tool so clients can list existing workflow requirements and render one workflow through the same contracts as native MCP prompts. The shared typed application parser preserves nested error paths and rejects unknown context fields and every forbidden list field. MCP uses the native prompt family scope. Standalone request/result schemas avoid catalog initialization cycles; an explicit object output root prevents legacy SDK response wrapping. Template rendering is independent of catalog visibility, and CLI loads the application only when invoked, preserving existing lazy startup. Rendering produces guidance without target analysis or session changes; no new provider or execution authority is introduced. ## Validation - Focused CLI startup, built guidance CLI, full/compact stdio MCP, native prompts/completion/lifecycle and scoped status tests: 35 passed across focused runs. Startup regressions verify both command registration and actual guidance rendering leave the tool catalog/provider composition unloaded. - Effects/provenance contract audits: 30 passed. The earlier eight in-memory ownership/adapter tests passed, including an execution spy and native completion availability. - Synced main `b594fbc3e`; repeated nine compiled startup/MCP boundary tests, `npm run docs:check` (nine conformance tests), and `npm run check:fast`: all passed. Bounded affected-file typed lint passed with existing warnings in untouched sections; 24-file formatting and diff checks passed. Full `check:pr` was not run locally. Full-profile MCP tests have a bounded 60 s budget after full-profile boundary cases took 22–39 s under concurrent shared-host work. ## Performance and real input Compared `265d13647` with the startup fix `b2d02cca5` on the same pinned base/dependencies, before the final independent main sync: 18 alternating fresh CLI processes covered help, selected guidance rendering and `inspect-elf-notes /usr/bin/true`. All stdout SHA-256s matched between old/new lanes. Sampled process-family RSS fell from 230–253 to 208–212 MiB; mean CPU across the equally weighted tasks fell from 3.57 to 3.02 s. Mean elapsed help/render/ELF times were 3.37/3.28/3.43 s before and 2.73/2.76/2.97 s after, with overlapping ranges. Output tokenx estimates stayed 4,331/696/1,600. The real ELF SHA-256 was `c79bf44242829108e323378531f4ac839513ca1fba45efd6583643526e1e9fd2`. On final `3ea8d5167`, three alternating fresh SDK client/server sessions per entrypoint completed one scoped catalog discovery and three list/render pairs, then closed both processes. Native prompt and tool guidance/IDs matched exactly; `/usr/bin/true` was selection data only here. Tokenx estimates for one pair plus the complete scoped catalog were 69,831 native / 71,674 tool; the added tool advertisement was 306 tokens. These serialized estimates include structured-content/text duplication, not model billing. Warm pairs overlapped at 7–31 ms; first tool pair cost 665–704 ms versus native 18–30 ms. Complete client/session workloads took 5.7–7.0 / 6.1–9.0 s elapsed, 6.4–7.9 / 7.3–10.2 s CPU, and 433–434 / 463–470 MiB sampled family RSS (native/tool). Totals include SDK and measurement bookkeeping. This compatibility entrypoint has measured overhead; no general latency improvement is claimed. RSS sampling was every 10 ms on a shared Linux host; filesystem caches were not flushed, and no builds or heavy checks overlapped the profiles. ## Author readiness Human owner: @Deepak-Kambala - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-03 13:38:42 +00:00

closed this issue
added the
pull-request
label

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#7558

No description provided.

Rows
Columns