feat: GetFolderDescription tool — per-file description registry with LLM auto-generation#53
Draft
Simon-Free wants to merge 2 commits intoSafeRL-Lab:mainfrom
Draft
feat: GetFolderDescription tool — per-file description registry with LLM auto-generation#53Simon-Free wants to merge 2 commits intoSafeRL-Lab:mainfrom
Simon-Free wants to merge 2 commits intoSafeRL-Lab:mainfrom
Conversation
nekocheik
pushed a commit
to nekocheik/cheetahclaws-fork
that referenced
this pull request
Apr 19, 2026
… attribution Add SILVERHAWK-FORK.md explaining: - Why Silverhawk forks cheetahclaws (V2 chat brick pivot per user directive) - What's customized (5 commits mapped: license, MCP, Matrix, a2a, wiring) - Integration map pointers (docs/cheetahclaws-arch-map.md, docs-silverhawk/mcp-silverhawk-plug.md) - Upstream tracking + contribution-back candidates (license fix) - License Apache-2.0 matches upstream Separate from upstream README.md (preserved as-is) to keep delta clear. refs SafeRL-Lab#32 SafeRL-Lab#33 SafeRL-Lab#34 SafeRL-Lab#35 SafeRL-Lab#46 SafeRL-Lab#53
test_folder_description_e2e drives agent.run with a mocked stream: the LLM issues a GetFolderDescription tool_call against a real tmp_path tree, and the tool_result is inspected to assert both filenames and their inline [desc] tags appear in the returned tree. Also tighten extract_inline_desc: replace the `except OSError: pass` followed by an unconditional `return None` with an explicit `return None` inside the except -- same behaviour, no silent pass, and reads the first line via `next(iter(f), "")` instead of a for-loop-break so the control flow is a single straight line. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a
GetFolderDescriptiontool that returns a recursive tree of code files with one-line descriptions, and afolder_desc/package that backs it. Files get their description from either an inline# [desc] ... [/desc]tag on the first line (free, instant) or a cached LLM call (parallel, 8 workers). Useful for understanding a codebase at a glance without walking every file.Files
folder_desc/__init__.pyfolder_desc/cache.pyget_cached_desc/set_cached_descfolder_desc/describer.pyextract_inline_desc,_read_preview,describe_file,describe_files_parallel(ThreadPoolExecutor, 8 workers)folder_desc/tree.py_is_code_file,_collect_files,build_tree_string,get_folder_descriptionorchestratorfolder_desc/tools.pyGetFolderDescriptionToolDeftools/__init__.py"folder_desc.tools"to the extension module listtests/test_folder_desc.pytests/test_folder_description_e2e.pyproviders.stream? LLM calls GetFolderDescription against a tmp_path tree with inline tags ? tool_result contains both filenames and both [desc] tagsInline tag convention
First-line pattern:
# [desc] short one-line description [/desc]. Pattern is language-agnostic (#works for Python / Shell / Ruby / ...). The first line of a newly-created file is a cheap contract - no runtime cost, no LLM call, no cache invalidation needed. Files without the tag fall back to an LLM-generated description written into the JSON cache.Backwards compatibility
config["disabled_tools"] = ["GetFolderDescription"]will remove the schema from the LLM view once #55 lands (which adds the registry-level gate). Until then, the tool is always registered but only fires when the LLM calls it - no other tool / command invokes it.Minor cleanup
extract_inline_desclost itsexcept OSError: pass+ unconditionalreturn Nonepattern; the except nowreturn Nones explicitly, and the loop-break dance is replaced bynext(iter(f), "")to read the first line. Same behaviour, cleaner control flow, no silent pass.Ref #43