feat(#60): integrate OpenDeepWiki code context layer into Research Supervisor

[Benmuiruri]

Description

• Add CodeContextAgent that queries OpenDeepWiki MCP endpoints for code architecture insights, module relationships, and Mermaid diagrams across CHT repos (cht-core, cht-conf, cht-watchdog)
• Wire the new agent into the Research Supervisor's LangGraph pipeline as a new node between documentation search and context analysis
• Feed code context findings into plan generation (prompt, key findings, and risk factors)
• Add research-results utility to save combined research output to outputs/context-results/
• Update CLI and example script to display code context results
• MCP responses are currently mocked until OpenDeepWiki is deployed (Deploy self-hosted OpenDeepWiki for CHT Code Context Layer cht-ai-tools#1)

Closes #60

Code review checklist

• Readable: Concise, well named, follows the style guide, documented if necessary.
• Tested: Unit and/or e2e where appropriate

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

[Benmuiruri]

@Hareet two comments related to this work.

1. I changed how errors propagate through the LangGraph pipeline.

Previously, when a node failed (e.g., doc search), it set currentPhase to the current phase name (like 'doc-search'). Downstream nodes had no way to detect this (explicitly). The final currentPhase could end up as 'plan-generation' even though the pipeline was broken. A caller checking result.currentPhase === 'complete' wouldn't know anything went wrong.

I made the change to have error cases consistently set currentPhase: 'error', and every node checks if (state.currentPhase === 'error') to skip execution. This means:

• Failures cascade cleanly
• The final state reliably reflects whether the pipeline succeeded or not
• Callers can trust currentPhase === 'complete' as a success indicator

2. The duplication between research.ts and research-supervisor-example.ts is significant. I suggest opening an issue to extract a shared display utility to DRY it up.

[Hareet]

@Benmuiruri Thanks for the PR!!

Just wanted to drop a note that I saw this, and I'll begin my review during my tomorrow and should be ready for you early next week.

[Hareet]

@Benmuiruri

Sorry for the delay! Did a preliminary review run through of this PR, and have finished deploying opendeepwiki

I'll edit my notes and finish the review early next week

[Hareet]

Should we change this to Promise.allSettled to parallelize during real MCP calls?

[Hareet]

Awesome @Benmuiruri !! Thanks for adding all this in, and keeping things consistent with the DocumentationSearchAgent. A pleasure to navigate.

Agree on the error propagation change and your flagging of the duplicated display logic in research.ts and the example. Do you want to open a new issue to extract that into a shared display utility?

I'm going to approve this PR, and wasn't sure if you wanted to add the following parts in this particular branch or open a new one after merging this work. Some things have changed since our self-hosted OpenDeepWiki has been deployed, but I didn't want to request changes on things that were not present during time of this work.

Our main changes we want to immediately implement:

• This PR mocks 3 different tools (get_wiki_structure, search_code, get_architecture)
  • We now know the tools exposed: (get_document_catalog, search_documents, read_document, list_repositories)
  • the real integration will need to call search_documents/read_document and then parse the wiki content into ArchitectureInsight/ModuleRelationship structures. That parsing step and the OpenDeepWikiMCPToolCall and OpenDeepWikiMCPResponse types will need to be redesigned around the actual API.
• Unrelated to PR, but all this work is impacted by research-supervisor.ts:
  • buildPhases returns 4 hardcoded phases regardless of research findings
    • How do we want to refactor that?
  • OpenDeepWiki is configured to return 200 words per page. That will be increased immediately.

Next priority fixes after above:

• Should we extract this mock data and move it to fixtures in tests? (/tests/fixtures/)
• Extract shared display utility
• ZOD validation for MCP responses

[Benmuiruri]

Hi @Hareet Thanks for the review!

Although you approved the PR, my suggestion on how to complete this PR:

We open separate issues for:

• Shared display utility extraction. ( I will create and assign this to myself)
• buildPhases hardcoded phases refactor
• Zod validation for MCP responses

For this PR I would like to:

1. Clean up the mock data and move it to tests/fixtures/ as you suggest
2. Implement the actual calls to the deployed OpenDeepWiki
3. Parallelize the repo fetching loop as you suggested

That seems a better approach than merge this PR to main then have another one do the clean up of the mocked data. Do you agree with my plan ?

[Hareet]

That seems a better approach than merge this PR to main then have another one do the clean up of the mocked data. Do you agree with my plan ?

Sounds good! Sorry I missed the question at the end.

[Benmuiruri]

@Hareet rebased and ready to merge with the outstanding work to be created as separate issues.

Apologies for the delay with this.

[Hareet]

Approving as discussed

[Hareet]

@sugat009

Do you want me to get this passing the new CI before we merge or just admin-merge this?

[sugat009]

Hey @Hareet, the lint failure here is the Node 20 EOL fetch issue. PR #99 fixes it by bumping engines.node. Plan is to land #99 first, then @Benmuiruri can merge main into this branch and lint clears without any code changes on #68.