Fix issue #8419: Document get_impl and import_from

[openhands-agent]

The get_impl function is one of the extensibility mechanisms in the project. It allows applications built on openhands to customize behavior by redefining and substituting at runtime their own implementations of the classes that this function is used for.

The LLMs get confused by the current code, for example here. I also had a confused agent recently.

This PR proposes to add some clarification, specially docstrings, to make it easier to understand. It was primarily meant for LLMs, but humans can benefit too from clarity and consistency. 😄

---

This pull request fixes #8419.

The issue has been successfully resolved based on the following concrete changes and their impact:

1. Documentation:

• Added docstrings to both get_impl and import_from functions in import_utils.py, clearly explaining their purpose, usage, and type safety guarantees
• Added docstrings to ConversationManager and StandaloneConversationManager classes that use the extensibility mechanism
• Created a new README.md in the utils directory that provides a complete explanation of the runtime implementation substitution system

2. Implementation:

• The documentation clearly explains how to use the extensibility mechanism through concrete examples
• Covers all key aspects requested: how it works, how to customize behavior, and where it's used
• Includes code examples demonstrating practical usage

3. Documentation Placement:

• Correctly placed the main documentation in the utils directory since the mechanism is used across multiple modules, not just in server
• Added class-specific documentation where the mechanism is used (in conversation_manager classes)

The changes provide a clear, comprehensive, and properly placed documentation of the extensibility mechanism, making it easy for developers to understand and implement custom behaviors in OpenHands.

Automatic fix generated by OpenHands 🙌

---

To run this PR locally, use the following command:

docker run -it --rm   -p 3000:3000   -v /var/run/docker.sock:/var/run/docker.sock   --add-host host.docker.internal:host-gateway   -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:b8135bb-nikolaik   --name openhands-app-b8135bb   docker.all-hands.dev/all-hands-ai/openhands:b8135bb

[enyst]

@openhands-agent-exp

Read and understand this PR and linked issue. The current documentation has two problems:

• it shouldn't repeat itself! For example, it repeats in StandaloneConversationManager what it said already in ConversationManager. The superclass docstring will do, just reference it or keep a single phrase in the implementation class.
• it misses similar docstrings to the other uses of get_impl or import_from. Add them in a similar way, but keep it simple, to the point.

[openhands-agent]

OpenHands started fixing the pr! You can monitor the progress here.

[openhands-agent]

Based on the provided information, here's a concise overview:

✅ Successfully Resolved:

• Eliminated redundant docstring content
• Implemented consistent documentation pattern across all extensible classes
• Added clear 3-step implementation guides
• Maintained DRY principles while providing comprehensive guidance
• Documentation now covers all major system components (Git services, storage, auth, runtime, monitoring, conversation management, validation)

🔍 No Issues Remaining:
The changes appear to have comprehensively addressed all documentation-related concerns, with no outstanding issues mentioned. The documentation is now consistent, complete, and properly structured across all extension points.

Recommendation:
The changes can be considered complete and ready for implementation, as they provide a clear and consistent documentation framework that will help developers understand and extend the system effectively.

[enyst]

I didn't realize GitHubService was among these classes. It seems to break the pattern quite a bit, such as this or this. We could refactor it. I'm not even sure if it's reimplemented or what is reimplemented, that is, what are the abstract methods we should actually separate and implement here?

[rbren]

Thanks for doing this!

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • Docker

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #8420

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}