Implement a git and go native parallel coding agent based on the plan/execute example

[alexlovelltroy]

This pull request introduces a new GitGoAgent for autonomous development in git-managed Go repositories, adds comprehensive documentation and example usage, and improves path validation and agent modularity. The most important changes are grouped below:

New Agent and Modular Architecture

• Added GitAgent and GitGoAgent classes to provide git-aware agents with language-specific extensions, allowing easy specialization for Go projects and future extensibility for other languages. (src/ursa/agents/git_agent.py, src/ursa/agents/git_go_agent.py) [1] [2]
• Introduced prompt composition utilities for git and Go, enabling modular agent instructions and clearer separation of git and language-specific behaviors. (src/ursa/prompt_library/git_prompts.py, src/ursa/prompt_library/go_prompts.py, src/ursa/prompt_library/git_go_prompts.py) [1] [2] [3]

Documentation and Examples

• Added detailed documentation for GitGoAgent, including usage instructions, available tools, configuration, and common workflows. (docs/git_go_agent.md)
• Provided a runnable example demonstrating GitGoAgent usage for git status and Go file summarization. (examples/single_agent_examples/git_go_agent/git_go_agent_example.py)
• Registered the new agent in the documentation navigation. (mkdocs.yml)

Path Safety and Tool Improvements

• Improved file path validation for code writing tools, ensuring files are written only within the workspace and optionally within the repository boundary, preventing path traversal and unauthorized writes. (src/ursa/tools/write_code_tool.py) [1] [2] [3]

Multi-Repo Planning Example

• Added a YAML configuration example for orchestrating documentation generation across two repositories (boot-service and openchami.org), showcasing agent planning and execution capabilities in multi-repo scenarios. (examples/two_agent_examples/plan_execute/openchami_boot_docs_example.yaml)

Minor Improvements

• Standardized error reporting in several example scripts for improved debugging clarity. (examples/two_agent_examples/plan_execute/city_10_vowels.py, examples/two_agent_examples/plan_execute/quantum_Rabi_QuTiP.py, examples/two_agent_examples/plan_execute/scrabble.py) [1] [2] [3]

[alexlovelltroy]

The tests are passing on my dev host with python 3.12.10 and pytest 9.0.2. Is there a matrix of versions we're targeting for tool versions that I should be referencing?

[mikegros]

Reviewing this now - I think you forgot to commit a couple tools files in the tools folder. Ran into some test failures because of it:

    from ursa.tools.git_tools import GIT_TOOLS
E   ModuleNotFoundError: No module named 'ursa.tools.git_tools'

[alexlovelltroy]

Thanks @mikegros I think it is fixed now. It looks like I had overlapping python environments that masked the missing file.

[mikegros]

Not finished reviewing but wanted to get a couple comments up so @luiarthur and @ndebard might be able to chime in.

[alexlovelltroy]

I had more than one ursa workspace on my laptop and some of my tests were using the wrong one. I just added a few more commits to further rely on common utils for plan_execute loop scripts in the utils directory.

randomname is back everywhere!

I added simple test yaml(s) for both plan_execute and plan_execute_multi_repo

python plan_execute_multi_repo.py --config example_multi_repo.yaml

python plan_execute_from_yaml.py --config example_from_yaml.yaml

[mikegros]

I'll try to get this merged today after our team meeting. My only real holdup is the added path validation. I want to make sure that wont break anything existing workflows people know of.

We had talked before about whether or not we should add the hard restriction to stay in the workspace or if that should be an optional argument of the agent (have a flag to turn on that hard boundary).

I'd really like to clear this off today though. The basic PR is definitely worth working in. Its just some of the knock-on effects that this that have slowed it down (well that, along with the project appraisal).

[luiarthur]

I reviewed only write_code_tool.py and a handful of small sections. My main feedback is to permit writing outside of repo/workspace but default to permitting writes only within repo/workspace.

[alexlovelltroy]

Updated write_code_tool.py to allow for unsafe writes. Documented in my git_go_agent docs. I didn't see a better place for it.

Path validation is enabled by default. For trusted sandbox/container usage, you can opt in to unsafe writes by setting:

export URSA_ALLOW_UNSAFE_WRITES=1

When enabled, workspace and repository boundary checks are bypassed for write_code and edit_code.

I also ran a bug analyzer and found a few places where write_code_tool could fail without good feedback to the user so I updated error handling to address it and added tests for all this behavior.

[mikegros]

Sorry I thought I submitted the other comment yesterday but noticed I put the comments in, but didnt submit the review

[alexlovelltroy]

@mikegros the check for file location is now only in _validate_file_path which is called from both write_code and edit_code. It follows the environment variable which means that the agent can't influence the safety when calling the tool. Is this what you were hoping to see?

[mikegros]

@mikegros the check for file location is now only in _validate_file_path which is called from both write_code and edit_code. It follows the environment variable which means that the agent can't influence the safety when calling the tool. Is this what you were hoping to see?

@mikegros the check for file location is now only in _validate_file_path which is called from both write_code and edit_code. It follows the environment variable which means that the agent can't influence the safety when calling the tool. Is this what you were hoping to see?

I appreciate the update on the validation, but the real blocking thing is the extra arg to write_code (line 89 of the write_code tool file).

I might just make a second write_code tool called something like write_code_with_repo or something and update your cases to call that tool instead of the baseline write_code tool. Because I dont want to keep blocking this PR, but I also don't want to make such a fundamental change to a core tool for an edge case (in addition to the other concerns I addressed in the comment).

[mikegros]

I think this looks good. I will do some testing and make sure there are no usage gotchas. If i dont run into any problems I will merge.

Thanks for your effort and patience on this.

This was addressed but I dont want to bug you on your weekend to clear this off so I'll just do it.

[mikegros]

Thank you so much for your effort and patience. It's all set!