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>]",
165 RegisterBuiltinTool<DungeonImportCustomCollisionJsonCommandHandler>(
166 registry,
167 {"dungeon-import-custom-collision-json",
168 "dungeon",
169 "Import custom collision maps and immediately save unless --dry-run",
170 "dungeon-import-custom-collision-json --in=<path> "
171 "[--dry-run [--report=<path>]] [--sandbox | --mock-rom] "
172 "[--replace-all --force]",
173 {},
174 true,
175 true,
177 {},
178 {"dry-run", "sandbox", "mock-rom", "replace-all", "force"}});
180 "dungeon-export-water-fill-json", "dungeon",
181 "Export water fill zones to JSON",
182 "dungeon-export-water-fill-json --out=<path> "
183 "[--room=<id>|--rooms=<ids>|--all] [--report=<path>]",
185 RegisterBuiltinTool<DungeonImportWaterFillJsonCommandHandler>(
186 registry,
187 {"dungeon-import-water-fill-json",
188 "dungeon",
189 "Import water fill zones and immediately save unless --dry-run",
190 "dungeon-import-water-fill-json --in=<path> "
191 "[--dry-run [--report=<path>]] [--sandbox | --mock-rom] "
192 "[--strict-masks]",
193 {},
194 true,
195 true,
197 {},
198 {"dry-run", "sandbox", "mock-rom", "strict-masks"}});
200 "dungeon-minecart-audit", "dungeon",
201 "Audit minecart-related room data (objects/sprites/collision)",
202 "dungeon-minecart-audit --room=<id>", {}, true, false,
205 "dungeon-minecart-map", "dungeon",
206 "Enumerate track tile positions/types with ASCII grid for "
207 "spatial reasoning",
208 "dungeon-minecart-map --room=<id>", {}, true, false,
210 REGISTER_BUILTIN_AGENT_TOOL("dungeon-get-room-tiles", "dungeon",
211 "Get room tiles",
212 "dungeon-get-room-tiles --room=<id>", {}, true,
215 "dungeon-set-room-property", "dungeon", "Set room property",
216 "dungeon-set-room-property --room=<id> --key=<key> --value=<val>", {},
218 REGISTER_BUILTIN_AGENT_TOOL("dungeon-room-header", "dungeon",
219 "Debug room header bytes",
220 "dungeon-room-header --room=<id>", {}, true,
222
223 // Overworld commands
224 REGISTER_BUILTIN_AGENT_TOOL("overworld-get-tile", "overworld",
225 "Get tile by map/x/y",
226 "overworld-get-tile --map=<id> --x=<x> --y=<y>",
227 {}, true, false, OverworldGetTileCommandHandler)
229 "overworld-set-tile", "overworld", "Set tile by map/x/y",
230 "overworld-set-tile --map=<id> --x=<x> --y=<y> --tile=<tile>", {}, true,
232 REGISTER_BUILTIN_AGENT_TOOL("overworld-find-tile", "overworld",
233 "Find tile locations",
234 "overworld-find-tile --tile=<id>", {}, true,
236 REGISTER_BUILTIN_AGENT_TOOL("overworld-describe-map", "overworld",
237 "Describe a map",
238 "overworld-describe-map --map=<id>", {}, true,
240 REGISTER_BUILTIN_AGENT_TOOL("overworld-list-warps", "overworld", "List warps",
241 "overworld-list-warps --map=<id>", {}, true,
243 REGISTER_BUILTIN_AGENT_TOOL("overworld-list-sprites", "overworld",
244 "List sprites",
245 "overworld-list-sprites --map=<id>", {}, true,
247 REGISTER_BUILTIN_AGENT_TOOL("overworld-get-entrance", "overworld",
248 "Get entrance info",
249 "overworld-get-entrance --id=<id>", {}, true,
251 REGISTER_BUILTIN_AGENT_TOOL("overworld-tile-stats", "overworld",
252 "Get tile statistics", "overworld-tile-stats", {},
254
255 // Message & Dialogue commands
256 REGISTER_BUILTIN_AGENT_TOOL("message-list", "message", "List messages",
257 "message-list", {}, true, false,
259 REGISTER_BUILTIN_AGENT_TOOL("message-read", "message", "Read message",
260 "message-read --id=<id>", {}, true, false,
262 REGISTER_BUILTIN_AGENT_TOOL("message-search", "message", "Search messages",
263 "message-search --query=<text>", {}, true, false,
265 REGISTER_BUILTIN_AGENT_TOOL("dialogue-list", "dialogue", "List dialogues",
266 "dialogue-list", {}, true, false,
268 REGISTER_BUILTIN_AGENT_TOOL("dialogue-read", "dialogue", "Read dialogue",
269 "dialogue-read --id=<id>", {}, true, false,
271 REGISTER_BUILTIN_AGENT_TOOL("dialogue-search", "dialogue", "Search dialogues",
272 "dialogue-search --query=<text>", {}, true, false,
274
275 // GUI Automation commands
276 REGISTER_BUILTIN_AGENT_TOOL("gui-place-tile", "gui", "Place a tile on canvas",
277 "gui-place-tile --x=<x> --y=<y> --tile=<id>", {},
278 false, false, GuiPlaceTileCommandHandler)
280 "gui-click", "gui", "Click GUI element",
281 "gui-click --target=<type:label> [--widget-key=<key>] "
282 "[--click-type=<left|right|middle|double>]",
283 {}, false, false, GuiClickCommandHandler)
284 REGISTER_BUILTIN_AGENT_TOOL("gui-type", "gui", "Type text into a GUI element",
285 "gui-type --target=<type:label> --text=<text> "
286 "[--widget-key=<key>] [--clear-first]",
287 {}, false, false, GuiTypeCommandHandler)
288 REGISTER_BUILTIN_AGENT_TOOL("gui-wait", "gui",
289 "Wait for GUI condition/widget",
290 "gui-wait --condition=<condition> "
291 "[--widget-key=<key>] [--timeout-ms=<ms>]",
292 {}, false, false, GuiWaitCommandHandler)
294 "gui-assert", "gui", "Assert GUI condition/widget",
295 "gui-assert --condition=<condition> [--widget-key=<key>]", {}, false,
297 REGISTER_BUILTIN_AGENT_TOOL("gui-discover-tool", "gui", "Discover GUI tools",
298 "gui-discover-tool", {}, false, false,
300 REGISTER_BUILTIN_AGENT_TOOL("gui-screenshot", "gui", "Take screenshot",
301 "gui-screenshot", {}, false, false,
303 REGISTER_BUILTIN_AGENT_TOOL("gui-summarize-widgets", "gui",
304 "Get a high-level summary of visible GUI widgets",
305 "gui-summarize-widgets", {}, false, false,
307
308 // Music commands
309 REGISTER_BUILTIN_AGENT_TOOL("music-list", "music", "List music tracks",
310 "music-list", {}, true, false,
312 REGISTER_BUILTIN_AGENT_TOOL("music-info", "music", "Get music info",
313 "music-info --id=<id>", {}, true, false,
315 REGISTER_BUILTIN_AGENT_TOOL("music-tracks", "music", "List tracks",
316 "music-tracks", {}, true, false,
318
319 // Sprite commands
320 REGISTER_BUILTIN_AGENT_TOOL("sprite-list", "sprite", "List sprites",
321 "sprite-list", {}, true, false,
323 REGISTER_BUILTIN_AGENT_TOOL("sprite-properties", "sprite",
324 "Get sprite properties",
325 "sprite-properties --id=<id>", {}, true, false,
327 REGISTER_BUILTIN_AGENT_TOOL("sprite-palette", "sprite", "Get sprite palette",
328 "sprite-palette --id=<id>", {}, true, false,
330
331 // Filesystem commands
333 "filesystem-list", "filesystem", "List directory contents",
334 "filesystem-list --path=<path>", {}, false, false, FileSystemListTool)
336 "filesystem-read", "filesystem", "Read file contents",
337 "filesystem-read --path=<path>", {}, false, false, FileSystemReadTool)
339 "filesystem-exists", "filesystem", "Check file existence",
340 "filesystem-exists --path=<path>", {}, false, false, FileSystemExistsTool)
341 REGISTER_BUILTIN_AGENT_TOOL("filesystem-info", "filesystem", "Get file info",
342 "filesystem-info --path=<path>", {}, false, false,
344
345 // Build commands
347 "build-configure", "build",
348 "Configure the build system with a CMake preset",
349 "build-configure --preset <preset> [--build-dir <dir>] "
350 "[--verbose]",
351 {}, false, false, BuildConfigureCommandHandler)
353 "build-compile", "build", "Build a specific target or all targets",
354 "build-compile [--target <target>] [--config <config>] "
355 "[--build-dir <dir>] [--verbose]",
356 {}, false, false, BuildCompileCommandHandler)
358 "build-test", "build", "Run tests with optional filter",
359 "build-test [--filter <pattern>] [--rom-path <path>] "
360 "[--build-dir <dir>] [--verbose]",
361 {}, false, false, BuildTestCommandHandler)
362 REGISTER_BUILTIN_AGENT_TOOL("build-status", "build",
363 "Get current build operation status",
364 "build-status [--build-dir <dir>]", {}, false,
366
367 // Memory inspector commands
368 REGISTER_BUILTIN_AGENT_TOOL("memory-analyze", "memory",
369 "Analyze memory region",
370 "memory-analyze --address=<addr> --length=<len>",
371 {}, true, false, MemoryAnalyzeTool)
373 "memory-search", "memory", "Search for byte pattern",
374 "memory-search --pattern=<hex>", {}, true, false, MemorySearchTool)
375 REGISTER_BUILTIN_AGENT_TOOL("memory-compare", "memory",
376 "Compare memory regions", "memory-compare", {},
377 true, false, MemoryCompareTool)
378 REGISTER_BUILTIN_AGENT_TOOL("memory-check", "memory", "Check memory",
379 "memory-check", {}, true, false, MemoryCheckTool)
380 REGISTER_BUILTIN_AGENT_TOOL("memory-regions", "memory",
381 "List known memory regions", "memory-regions", {},
382 false, false, MemoryRegionsTool)
383
384 // Test helper tools
385 REGISTER_BUILTIN_AGENT_TOOL("tools-helper-list", "tools",
386 "List test helper tools", "tools-helper-list", {},
387 false, false, ToolsListCommandHandler)
388 REGISTER_BUILTIN_AGENT_TOOL("tools-harness-state", "tools",
389 "Generate WRAM state", "tools-harness-state", {},
392 "tools-extract-values", "tools", "Extract vanilla ROM values",
393 "tools-extract-values", {}, true, false, ToolsExtractValuesCommandHandler)
394 REGISTER_BUILTIN_AGENT_TOOL("tools-extract-golden", "tools",
395 "Extract golden data", "tools-extract-golden", {},
397 REGISTER_BUILTIN_AGENT_TOOL("tools-patch-v3", "tools",
398 "Create v3 patched ROM", "tools-patch-v3", {},
399 true, false, ToolsPatchV3CommandHandler)
400
401 // Visual analysis tools
403 "visual-find-similar-tiles", "visual", "Find tiles with similar patterns",
404 "visual-find-similar-tiles", {}, true, false, TileSimilarityTool)
406 "visual-analyze-spritesheet", "visual", "Identify unused regions",
407 "visual-analyze-spritesheet", {}, true, false, SpritesheetAnalysisTool)
408 REGISTER_BUILTIN_AGENT_TOOL("visual-palette-usage", "visual",
409 "Analyze palette usage", "visual-palette-usage",
410 {}, true, false, PaletteUsageTool)
412 "visual-tile-histogram", "visual", "Generate tile usage histogram",
413 "visual-tile-histogram", {}, true, false, TileHistogramTool)
414
415 // Code generation tools
416 REGISTER_BUILTIN_AGENT_TOOL("codegen-asm-hook", "codegen",
417 "Generate ASM hook", "codegen-asm-hook", {}, true,
418 false, CodeGenAsmHookTool)
419 REGISTER_BUILTIN_AGENT_TOOL("codegen-freespace-patch", "codegen",
420 "Generate patch", "codegen-freespace-patch", {},
421 true, false, CodeGenFreespacePatchTool)
422 REGISTER_BUILTIN_AGENT_TOOL("codegen-sprite-template", "codegen",
423 "Generate sprite ASM", "codegen-sprite-template",
424 {}, false, false, CodeGenSpriteTemplateTool)
425 REGISTER_BUILTIN_AGENT_TOOL("codegen-event-handler", "codegen",
426 "Generate event handler", "codegen-event-handler",
427 {}, false, false, CodeGenEventHandlerTool)
428
429 // Project management tools
430 REGISTER_BUILTIN_AGENT_TOOL("project-status", "project",
431 "Show current project state", "project-status",
432 {}, true, true, ProjectStatusTool)
433 REGISTER_BUILTIN_AGENT_TOOL("project-snapshot", "project",
434 "Create named checkpoint", "project-snapshot", {},
435 true, true, ProjectSnapshotTool)
436 REGISTER_BUILTIN_AGENT_TOOL("project-restore", "project",
437 "Restore ROM to checkpoint", "project-restore",
438 {}, true, true, ProjectRestoreTool)
439 REGISTER_BUILTIN_AGENT_TOOL("project-export", "project", "Export project",
440 "project-export", {}, true, true,
442 REGISTER_BUILTIN_AGENT_TOOL("project-import", "project", "Import project",
443 "project-import", {}, false, true,
445 REGISTER_BUILTIN_AGENT_TOOL("project-diff", "project",
446 "Compare project states", "project-diff", {},
447 true, true, ProjectDiffTool)
449 "project-graph", "project",
450 "Query project graph info (files, symbols, config)",
451 "project-graph --query=<info|files|symbols|lookup|writes|bank> "
452 "[--path=<folder>] [--symbol=<name>] [--address=<hex>] [--bank=<hex>]",
453 {}, true, true, ProjectGraphTool)
454
455#ifdef YAZE_WITH_GRPC
456 REGISTER_BUILTIN_AGENT_TOOL("emulator-step", "emulator", "Step emulator",
457 "emulator-step", {}, true, false,
459 REGISTER_BUILTIN_AGENT_TOOL("emulator-run", "emulator", "Run emulator",
460 "emulator-run", {}, true, false,
462 REGISTER_BUILTIN_AGENT_TOOL("emulator-pause", "emulator", "Pause emulator",
463 "emulator-pause", {}, true, false,
465 REGISTER_BUILTIN_AGENT_TOOL("emulator-reset", "emulator", "Reset emulator",
466 "emulator-reset", {}, true, false,
468 REGISTER_BUILTIN_AGENT_TOOL("emulator-get-state", "emulator",
469 "Get emulator state", "emulator-get-state", {},
471 REGISTER_BUILTIN_AGENT_TOOL("emulator-set-breakpoint", "emulator",
472 "Set breakpoint", "emulator-set-breakpoint", {},
474 REGISTER_BUILTIN_AGENT_TOOL("emulator-clear-breakpoint", "emulator",
475 "Clear breakpoint", "emulator-clear-breakpoint",
476 {}, true, false,
478 REGISTER_BUILTIN_AGENT_TOOL("emulator-list-breakpoints", "emulator",
479 "List breakpoints", "emulator-list-breakpoints",
480 {}, true, false,
482 REGISTER_BUILTIN_AGENT_TOOL("emulator-read-memory", "emulator", "Read memory",
483 "emulator-read-memory", {}, true, false,
485 REGISTER_BUILTIN_AGENT_TOOL("emulator-write-memory", "emulator",
486 "Write memory", "emulator-write-memory", {}, true,
488 REGISTER_BUILTIN_AGENT_TOOL("emulator-get-registers", "emulator",
489 "Get registers", "emulator-get-registers", {},
491 REGISTER_BUILTIN_AGENT_TOOL("emulator-get-metrics", "emulator", "Get metrics",
492 "emulator-get-metrics", {}, true, false,
494#endif
495}
496
497#undef REGISTER_BUILTIN_AGENT_TOOL
498
499} // namespace agent
500} // namespace cli
501} // 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.