yaze 0.3.2
Link to the Past ROM Editor
 
Loading...
Searching...
No Matches
tool_registration.cc
Go to the documentation of this file.
3
14#ifdef YAZE_WITH_GRPC
16#endif
26
27namespace yaze {
28namespace cli {
29namespace agent {
30
31using namespace yaze::cli::handlers;
32using namespace yaze::cli::agent::tools;
33
34namespace {
35
36template <typename HandlerClass>
37void RegisterBuiltinTool(ToolRegistry& registry, ToolDefinition definition) {
38 registry.RegisterTool(std::move(definition),
39 []() { return std::make_unique<HandlerClass>(); });
40}
41
42#define REGISTER_BUILTIN_AGENT_TOOL(Name, Category, Desc, Usage, Examples, \
43 ReqRom, ReqProject, HandlerClass) \
44 RegisterBuiltinTool<HandlerClass>(registry, {Name, \
45 Category, \
46 Desc, \
47 Usage, \
48 Examples, \
49 ReqRom, \
50 ReqProject, \
51 ToolAccess::kReadOnly, \
52 {}, \
53 {}});
54
55} // namespace
56
57// Placeholder classes for meta-tools (they're handled specially in the
58// dispatcher) but still need handlers for registry metadata.
60 public:
61 std::string GetName() const override { return "tools-list"; }
62 std::string GetUsage() const override { return "tools-list"; }
63 bool RequiresRom() const override { return false; }
64
65 protected:
66 absl::Status ValidateArgs(const resources::ArgumentParser&) override {
67 return absl::OkStatus();
68 }
69 absl::Status Execute(Rom*, const resources::ArgumentParser&,
71 return absl::UnimplementedError(
72 "Handled by ToolDispatcher meta-tool handler");
73 }
74};
75
77 public:
78 std::string GetName() const override { return "tools-describe"; }
79 std::string GetUsage() const override {
80 return "tools-describe --name=<tool>";
81 }
82 bool RequiresRom() const override { return false; }
83
84 protected:
85 absl::Status ValidateArgs(const resources::ArgumentParser&) override {
86 return absl::OkStatus();
87 }
88 absl::Status Execute(Rom*, const resources::ArgumentParser&,
90 return absl::UnimplementedError(
91 "Handled by ToolDispatcher meta-tool handler");
92 }
93};
94
96 public:
97 std::string GetName() const override { return "tools-search"; }
98 std::string GetUsage() const override {
99 return "tools-search --query=<keyword>";
100 }
101 bool RequiresRom() const override { return false; }
102
103 protected:
104 absl::Status ValidateArgs(const resources::ArgumentParser&) override {
105 return absl::OkStatus();
106 }
107 absl::Status Execute(Rom*, const resources::ArgumentParser&,
108 resources::OutputFormatter&) override {
109 return absl::UnimplementedError(
110 "Handled by ToolDispatcher meta-tool handler");
111 }
112};
113
115 // Meta-tools (handled specially but registered for discovery)
116 REGISTER_BUILTIN_AGENT_TOOL("tools-list", "meta", "List all available tools",
117 "tools-list", {}, false, false,
119 REGISTER_BUILTIN_AGENT_TOOL("tools-describe", "meta",
120 "Get detailed information about a tool",
121 "tools-describe --name=<tool>", {}, false, false,
123 REGISTER_BUILTIN_AGENT_TOOL("tools-search", "meta", "Search tools by keyword",
124 "tools-search --query=<keyword>", {}, false,
126
127 // Resource commands
129 "resource-list", "resource", "List resource labels",
130 "resource-list --type=<type>", {"resource-list --type=dungeon"}, true,
133 "resource-search", "resource", "Search resource labels",
134 "resource-search --query=<query>", {"resource-search --query=castle"},
135 true, false, ResourceSearchCommandHandler)
136
137 // Dungeon commands
138 REGISTER_BUILTIN_AGENT_TOOL("dungeon-list-sprites", "dungeon",
139 "List sprites in a dungeon room",
140 "dungeon-list-sprites --room=<id>", {}, true,
142 REGISTER_BUILTIN_AGENT_TOOL("dungeon-describe-room", "dungeon",
143 "Describe a room",
144 "dungeon-describe-room --room=<id>", {}, true,
146 REGISTER_BUILTIN_AGENT_TOOL("dungeon-export-room", "dungeon",
147 "Export room data",
148 "dungeon-export-room --room=<id>", {}, true,
150 REGISTER_BUILTIN_AGENT_TOOL("dungeon-list-objects", "dungeon",
151 "List room objects",
152 "dungeon-list-objects --room=<id>", {}, true,
154 REGISTER_BUILTIN_AGENT_TOOL("dungeon-list-custom-collision", "dungeon",
155 "List custom collision tiles for a room",
156 "dungeon-list-custom-collision --room=<id>", {},
157 true, false,
160 "dungeon-export-custom-collision-json", "dungeon",
161 "Export custom collision maps to JSON",
162 "dungeon-export-custom-collision-json --out=<path> "
163 "[--room=<id>|--rooms=<ids>|--all] [--report=<path>]",
166 "dungeon-import-custom-collision-json", "dungeon",
167 "Import custom collision maps from JSON",
168 "dungeon-import-custom-collision-json --in=<path> "
169 "[--dry-run] [--replace-all --force] [--report=<path>]",
172 "dungeon-export-water-fill-json", "dungeon",
173 "Export water fill zones to JSON",
174 "dungeon-export-water-fill-json --out=<path> "
175 "[--room=<id>|--rooms=<ids>|--all] [--report=<path>]",
178 "dungeon-import-water-fill-json", "dungeon",
179 "Import water fill zones from JSON",
180 "dungeon-import-water-fill-json --in=<path> [--dry-run] "
181 "[--strict-masks] [--report=<path>]",
184 "dungeon-minecart-audit", "dungeon",
185 "Audit minecart-related room data (objects/sprites/collision)",
186 "dungeon-minecart-audit --room=<id>", {}, true, false,
189 "dungeon-minecart-map", "dungeon",
190 "Enumerate track tile positions/types with ASCII grid for "
191 "spatial reasoning",
192 "dungeon-minecart-map --room=<id>", {}, true, false,
194 REGISTER_BUILTIN_AGENT_TOOL("dungeon-get-room-tiles", "dungeon",
195 "Get room tiles",
196 "dungeon-get-room-tiles --room=<id>", {}, true,
199 "dungeon-set-room-property", "dungeon", "Set room property",
200 "dungeon-set-room-property --room=<id> --key=<key> --value=<val>", {},
202 REGISTER_BUILTIN_AGENT_TOOL("dungeon-room-header", "dungeon",
203 "Debug room header bytes",
204 "dungeon-room-header --room=<id>", {}, true,
206
207 // Overworld commands
208 REGISTER_BUILTIN_AGENT_TOOL("overworld-get-tile", "overworld",
209 "Get tile by map/x/y",
210 "overworld-get-tile --map=<id> --x=<x> --y=<y>",
211 {}, true, false, OverworldGetTileCommandHandler)
213 "overworld-set-tile", "overworld", "Set tile by map/x/y",
214 "overworld-set-tile --map=<id> --x=<x> --y=<y> --tile=<tile>", {}, true,
216 REGISTER_BUILTIN_AGENT_TOOL("overworld-find-tile", "overworld",
217 "Find tile locations",
218 "overworld-find-tile --tile=<id>", {}, true,
220 REGISTER_BUILTIN_AGENT_TOOL("overworld-describe-map", "overworld",
221 "Describe a map",
222 "overworld-describe-map --map=<id>", {}, true,
224 REGISTER_BUILTIN_AGENT_TOOL("overworld-list-warps", "overworld", "List warps",
225 "overworld-list-warps --map=<id>", {}, true,
227 REGISTER_BUILTIN_AGENT_TOOL("overworld-list-sprites", "overworld",
228 "List sprites",
229 "overworld-list-sprites --map=<id>", {}, true,
231 REGISTER_BUILTIN_AGENT_TOOL("overworld-get-entrance", "overworld",
232 "Get entrance info",
233 "overworld-get-entrance --id=<id>", {}, true,
235 REGISTER_BUILTIN_AGENT_TOOL("overworld-tile-stats", "overworld",
236 "Get tile statistics", "overworld-tile-stats", {},
238
239 // Message & Dialogue commands
240 REGISTER_BUILTIN_AGENT_TOOL("message-list", "message", "List messages",
241 "message-list", {}, true, false,
243 REGISTER_BUILTIN_AGENT_TOOL("message-read", "message", "Read message",
244 "message-read --id=<id>", {}, true, false,
246 REGISTER_BUILTIN_AGENT_TOOL("message-search", "message", "Search messages",
247 "message-search --query=<text>", {}, true, false,
249 REGISTER_BUILTIN_AGENT_TOOL("dialogue-list", "dialogue", "List dialogues",
250 "dialogue-list", {}, true, false,
252 REGISTER_BUILTIN_AGENT_TOOL("dialogue-read", "dialogue", "Read dialogue",
253 "dialogue-read --id=<id>", {}, true, false,
255 REGISTER_BUILTIN_AGENT_TOOL("dialogue-search", "dialogue", "Search dialogues",
256 "dialogue-search --query=<text>", {}, true, false,
258
259 // GUI Automation commands
260 REGISTER_BUILTIN_AGENT_TOOL("gui-place-tile", "gui", "Place a tile on canvas",
261 "gui-place-tile --x=<x> --y=<y> --tile=<id>", {},
262 false, false, GuiPlaceTileCommandHandler)
264 "gui-click", "gui", "Click GUI element",
265 "gui-click --target=<type:label> [--widget-key=<key>] "
266 "[--click-type=<left|right|middle|double>]",
267 {}, false, false, GuiClickCommandHandler)
268 REGISTER_BUILTIN_AGENT_TOOL("gui-type", "gui", "Type text into a GUI element",
269 "gui-type --target=<type:label> --text=<text> "
270 "[--widget-key=<key>] [--clear-first]",
271 {}, false, false, GuiTypeCommandHandler)
272 REGISTER_BUILTIN_AGENT_TOOL("gui-wait", "gui",
273 "Wait for GUI condition/widget",
274 "gui-wait --condition=<condition> "
275 "[--widget-key=<key>] [--timeout-ms=<ms>]",
276 {}, false, false, GuiWaitCommandHandler)
278 "gui-assert", "gui", "Assert GUI condition/widget",
279 "gui-assert --condition=<condition> [--widget-key=<key>]", {}, false,
281 REGISTER_BUILTIN_AGENT_TOOL("gui-discover-tool", "gui", "Discover GUI tools",
282 "gui-discover-tool", {}, false, false,
284 REGISTER_BUILTIN_AGENT_TOOL("gui-screenshot", "gui", "Take screenshot",
285 "gui-screenshot", {}, false, false,
287 REGISTER_BUILTIN_AGENT_TOOL("gui-summarize-widgets", "gui",
288 "Get a high-level summary of visible GUI widgets",
289 "gui-summarize-widgets", {}, false, false,
291
292 // Music commands
293 REGISTER_BUILTIN_AGENT_TOOL("music-list", "music", "List music tracks",
294 "music-list", {}, true, false,
296 REGISTER_BUILTIN_AGENT_TOOL("music-info", "music", "Get music info",
297 "music-info --id=<id>", {}, true, false,
299 REGISTER_BUILTIN_AGENT_TOOL("music-tracks", "music", "List tracks",
300 "music-tracks", {}, true, false,
302
303 // Sprite commands
304 REGISTER_BUILTIN_AGENT_TOOL("sprite-list", "sprite", "List sprites",
305 "sprite-list", {}, true, false,
307 REGISTER_BUILTIN_AGENT_TOOL("sprite-properties", "sprite",
308 "Get sprite properties",
309 "sprite-properties --id=<id>", {}, true, false,
311 REGISTER_BUILTIN_AGENT_TOOL("sprite-palette", "sprite", "Get sprite palette",
312 "sprite-palette --id=<id>", {}, true, false,
314
315 // Filesystem commands
317 "filesystem-list", "filesystem", "List directory contents",
318 "filesystem-list --path=<path>", {}, false, false, FileSystemListTool)
320 "filesystem-read", "filesystem", "Read file contents",
321 "filesystem-read --path=<path>", {}, false, false, FileSystemReadTool)
323 "filesystem-exists", "filesystem", "Check file existence",
324 "filesystem-exists --path=<path>", {}, false, false, FileSystemExistsTool)
325 REGISTER_BUILTIN_AGENT_TOOL("filesystem-info", "filesystem", "Get file info",
326 "filesystem-info --path=<path>", {}, false, false,
328
329 // Build commands
331 "build-configure", "build",
332 "Configure the build system with a CMake preset",
333 "build-configure --preset <preset> [--build-dir <dir>] "
334 "[--verbose]",
335 {}, false, false, BuildConfigureCommandHandler)
337 "build-compile", "build", "Build a specific target or all targets",
338 "build-compile [--target <target>] [--config <config>] "
339 "[--build-dir <dir>] [--verbose]",
340 {}, false, false, BuildCompileCommandHandler)
342 "build-test", "build", "Run tests with optional filter",
343 "build-test [--filter <pattern>] [--rom-path <path>] "
344 "[--build-dir <dir>] [--verbose]",
345 {}, false, false, BuildTestCommandHandler)
346 REGISTER_BUILTIN_AGENT_TOOL("build-status", "build",
347 "Get current build operation status",
348 "build-status [--build-dir <dir>]", {}, false,
350
351 // Memory inspector commands
352 REGISTER_BUILTIN_AGENT_TOOL("memory-analyze", "memory",
353 "Analyze memory region",
354 "memory-analyze --address=<addr> --length=<len>",
355 {}, true, false, MemoryAnalyzeTool)
357 "memory-search", "memory", "Search for byte pattern",
358 "memory-search --pattern=<hex>", {}, true, false, MemorySearchTool)
359 REGISTER_BUILTIN_AGENT_TOOL("memory-compare", "memory",
360 "Compare memory regions", "memory-compare", {},
361 true, false, MemoryCompareTool)
362 REGISTER_BUILTIN_AGENT_TOOL("memory-check", "memory", "Check memory",
363 "memory-check", {}, true, false, MemoryCheckTool)
364 REGISTER_BUILTIN_AGENT_TOOL("memory-regions", "memory",
365 "List known memory regions", "memory-regions", {},
366 false, false, MemoryRegionsTool)
367
368 // Test helper tools
369 REGISTER_BUILTIN_AGENT_TOOL("tools-helper-list", "tools",
370 "List test helper tools", "tools-helper-list", {},
371 false, false, ToolsListCommandHandler)
372 REGISTER_BUILTIN_AGENT_TOOL("tools-harness-state", "tools",
373 "Generate WRAM state", "tools-harness-state", {},
376 "tools-extract-values", "tools", "Extract vanilla ROM values",
377 "tools-extract-values", {}, true, false, ToolsExtractValuesCommandHandler)
378 REGISTER_BUILTIN_AGENT_TOOL("tools-extract-golden", "tools",
379 "Extract golden data", "tools-extract-golden", {},
381 REGISTER_BUILTIN_AGENT_TOOL("tools-patch-v3", "tools",
382 "Create v3 patched ROM", "tools-patch-v3", {},
383 true, false, ToolsPatchV3CommandHandler)
384
385 // Visual analysis tools
387 "visual-find-similar-tiles", "visual", "Find tiles with similar patterns",
388 "visual-find-similar-tiles", {}, true, false, TileSimilarityTool)
390 "visual-analyze-spritesheet", "visual", "Identify unused regions",
391 "visual-analyze-spritesheet", {}, true, false, SpritesheetAnalysisTool)
392 REGISTER_BUILTIN_AGENT_TOOL("visual-palette-usage", "visual",
393 "Analyze palette usage", "visual-palette-usage",
394 {}, true, false, PaletteUsageTool)
396 "visual-tile-histogram", "visual", "Generate tile usage histogram",
397 "visual-tile-histogram", {}, true, false, TileHistogramTool)
398
399 // Code generation tools
400 REGISTER_BUILTIN_AGENT_TOOL("codegen-asm-hook", "codegen",
401 "Generate ASM hook", "codegen-asm-hook", {}, true,
402 false, CodeGenAsmHookTool)
403 REGISTER_BUILTIN_AGENT_TOOL("codegen-freespace-patch", "codegen",
404 "Generate patch", "codegen-freespace-patch", {},
405 true, false, CodeGenFreespacePatchTool)
406 REGISTER_BUILTIN_AGENT_TOOL("codegen-sprite-template", "codegen",
407 "Generate sprite ASM", "codegen-sprite-template",
408 {}, false, false, CodeGenSpriteTemplateTool)
409 REGISTER_BUILTIN_AGENT_TOOL("codegen-event-handler", "codegen",
410 "Generate event handler", "codegen-event-handler",
411 {}, false, false, CodeGenEventHandlerTool)
412
413 // Project management tools
414 REGISTER_BUILTIN_AGENT_TOOL("project-status", "project",
415 "Show current project state", "project-status",
416 {}, true, true, ProjectStatusTool)
417 REGISTER_BUILTIN_AGENT_TOOL("project-snapshot", "project",
418 "Create named checkpoint", "project-snapshot", {},
419 true, true, ProjectSnapshotTool)
420 REGISTER_BUILTIN_AGENT_TOOL("project-restore", "project",
421 "Restore ROM to checkpoint", "project-restore",
422 {}, true, true, ProjectRestoreTool)
423 REGISTER_BUILTIN_AGENT_TOOL("project-export", "project", "Export project",
424 "project-export", {}, true, true,
426 REGISTER_BUILTIN_AGENT_TOOL("project-import", "project", "Import project",
427 "project-import", {}, false, true,
429 REGISTER_BUILTIN_AGENT_TOOL("project-diff", "project",
430 "Compare project states", "project-diff", {},
431 true, true, ProjectDiffTool)
433 "project-graph", "project",
434 "Query project graph info (files, symbols, config)",
435 "project-graph --query=<info|files|symbols|lookup|writes|bank> "
436 "[--path=<folder>] [--symbol=<name>] [--address=<hex>] [--bank=<hex>]",
437 {}, true, true, ProjectGraphTool)
438
439#ifdef YAZE_WITH_GRPC
440 REGISTER_BUILTIN_AGENT_TOOL("emulator-step", "emulator", "Step emulator",
441 "emulator-step", {}, true, false,
443 REGISTER_BUILTIN_AGENT_TOOL("emulator-run", "emulator", "Run emulator",
444 "emulator-run", {}, true, false,
446 REGISTER_BUILTIN_AGENT_TOOL("emulator-pause", "emulator", "Pause emulator",
447 "emulator-pause", {}, true, false,
449 REGISTER_BUILTIN_AGENT_TOOL("emulator-reset", "emulator", "Reset emulator",
450 "emulator-reset", {}, true, false,
452 REGISTER_BUILTIN_AGENT_TOOL("emulator-get-state", "emulator",
453 "Get emulator state", "emulator-get-state", {},
455 REGISTER_BUILTIN_AGENT_TOOL("emulator-set-breakpoint", "emulator",
456 "Set breakpoint", "emulator-set-breakpoint", {},
458 REGISTER_BUILTIN_AGENT_TOOL("emulator-clear-breakpoint", "emulator",
459 "Clear breakpoint", "emulator-clear-breakpoint",
460 {}, true, false,
462 REGISTER_BUILTIN_AGENT_TOOL("emulator-list-breakpoints", "emulator",
463 "List breakpoints", "emulator-list-breakpoints",
464 {}, true, false,
466 REGISTER_BUILTIN_AGENT_TOOL("emulator-read-memory", "emulator", "Read memory",
467 "emulator-read-memory", {}, true, false,
469 REGISTER_BUILTIN_AGENT_TOOL("emulator-write-memory", "emulator",
470 "Write memory", "emulator-write-memory", {}, true,
472 REGISTER_BUILTIN_AGENT_TOOL("emulator-get-registers", "emulator",
473 "Get registers", "emulator-get-registers", {},
475 REGISTER_BUILTIN_AGENT_TOOL("emulator-get-metrics", "emulator", "Get metrics",
476 "emulator-get-metrics", {}, true, false,
478#endif
479}
480
481#undef REGISTER_BUILTIN_AGENT_TOOL
482
483} // namespace agent
484} // namespace cli
485} // namespace yaze
The Rom class is used to load, save, and modify Rom data. This is a generic SNES ROM container and do...
Definition rom.h:28
std::string GetUsage() const override
Get the command usage string.
bool RequiresRom() const override
Check if the command requires a loaded ROM.
std::string GetName() const override
Get the command name.
absl::Status ValidateArgs(const resources::ArgumentParser &) override
Validate command arguments.
absl::Status Execute(Rom *, const resources::ArgumentParser &, resources::OutputFormatter &) override
Execute the command business logic.
std::string GetName() const override
Get the command name.
bool RequiresRom() const override
Check if the command requires a loaded ROM.
absl::Status Execute(Rom *, const resources::ArgumentParser &, resources::OutputFormatter &) override
Execute the command business logic.
std::string GetUsage() const override
Get the command usage string.
absl::Status ValidateArgs(const resources::ArgumentParser &) override
Validate command arguments.
std::string GetUsage() const override
Get the command usage string.
absl::Status Execute(Rom *, const resources::ArgumentParser &, resources::OutputFormatter &) override
Execute the command business logic.
bool RequiresRom() const override
Check if the command requires a loaded ROM.
std::string GetName() const override
Get the command name.
absl::Status ValidateArgs(const resources::ArgumentParser &) override
Validate command arguments.
Centralized registry for all agent tools.
void RegisterTool(const ToolDefinition &def, HandlerFactory factory)
Generate ASM hook at a specific ROM address.
Generate patch using detected freespace regions.
Check if a file or directory exists.
Get detailed information about a file or directory.
List files and directories in a given path.
Analyze a memory region with structure awareness.
Check memory for anomalies and corruption.
Compare memory regions or detect changes.
List known memory regions and their descriptions.
Search for byte patterns in memory.
Analyze palette usage across maps.
Export project as portable archive.
Provides the AI agent with structured information about the project.
Restore ROM to named checkpoint.
Create named checkpoint with edit deltas.
Show current project state and pending edits.
Analyze spritesheets for unused graphics regions.
Command handler for listing dialogue messages.
Command handler for reading dialogue messages.
Command handler for searching dialogue messages.
Command handler for describing a dungeon room.
Command handler for exporting room data.
Command handler for listing objects in a room.
Command handler for listing sprites in a dungeon room.
Command handler for reading raw room header bytes (diagnostic)
Command handler for setting room properties.
Command handler for GUI assertions.
Command handler for clicking GUI elements.
Command handler for discovering GUI tools.
Command handler for placing tiles via GUI automation.
Command handler for taking screenshots.
Command handler for summarizing GUI widgets.
Command handler for typing into GUI inputs.
Command handler for waiting on GUI conditions.
Command handler for listing messages.
Command handler for reading messages.
Command handler for searching messages.
Command handler for getting music track information.
Command handler for listing music tracks.
Command handler for getting detailed music track data.
Command handler for describing overworld maps.
Command handler for finding tiles in overworld.
Command handler for getting entrance information.
Command handler for listing sprites in overworld.
Command handler for listing warps in overworld.
Command handler for getting tile statistics.
Command handler for listing resource labels by type.
Command handler for searching resource labels.
Command handler for listing sprites.
Command handler for getting sprite palette information.
Command handler for getting sprite properties.
Extract comprehensive golden data from ROM.
Create v3 ZSCustomOverworld patched ROM.
Utility for parsing common CLI argument patterns.
Base class for CLI command handlers.
Utility for consistent output formatting across commands.
Code generation tools for AI agents.
void RegisterBuiltinTool(ToolRegistry &registry, ToolDefinition definition)
void RegisterBuiltinAgentTools(ToolRegistry &registry)
Project management tools for AI agents.
Metadata describing a tool for the LLM.
CLI command handlers for test helper tools.
#define REGISTER_BUILTIN_AGENT_TOOL(Name, Category, Desc, Usage, Examples, ReqRom, ReqProject, HandlerClass)
Visual analysis tools for AI agents.