code-puppy 0.0.171__tar.gz → 0.0.173__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. {code_puppy-0.0.171 → code_puppy-0.0.173}/PKG-INFO +3 -1
  2. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/agent.py +8 -8
  3. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/agents/agent_creator_agent.py +0 -3
  4. code_puppy-0.0.173/code_puppy/agents/agent_qa_kitten.py +203 -0
  5. code_puppy-0.0.173/code_puppy/agents/base_agent.py +512 -0
  6. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/command_handler.py +68 -28
  7. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/add_command.py +2 -2
  8. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/base.py +1 -1
  9. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/install_command.py +2 -2
  10. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/list_command.py +1 -1
  11. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/search_command.py +1 -1
  12. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/start_all_command.py +1 -1
  13. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/status_command.py +2 -2
  14. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/stop_all_command.py +1 -1
  15. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/utils.py +1 -1
  16. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/wizard_utils.py +2 -2
  17. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/config.py +141 -12
  18. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/http_utils.py +50 -24
  19. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/main.py +2 -1
  20. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/config_wizard.py +1 -1
  21. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/examples/retry_example.py +1 -1
  22. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/managed_server.py +1 -1
  23. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/server_registry_catalog.py +1 -3
  24. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/message_history_processor.py +83 -221
  25. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/messaging/message_queue.py +4 -4
  26. code_puppy-0.0.173/code_puppy/state_management.py +58 -0
  27. code_puppy-0.0.173/code_puppy/tools/__init__.py +167 -0
  28. code_puppy-0.0.173/code_puppy/tools/browser/__init__.py +0 -0
  29. code_puppy-0.0.173/code_puppy/tools/browser/browser_control.py +293 -0
  30. code_puppy-0.0.173/code_puppy/tools/browser/browser_interactions.py +552 -0
  31. code_puppy-0.0.173/code_puppy/tools/browser/browser_locators.py +642 -0
  32. code_puppy-0.0.173/code_puppy/tools/browser/browser_navigation.py +251 -0
  33. code_puppy-0.0.173/code_puppy/tools/browser/browser_screenshot.py +242 -0
  34. code_puppy-0.0.173/code_puppy/tools/browser/browser_scripts.py +478 -0
  35. code_puppy-0.0.173/code_puppy/tools/browser/browser_workflows.py +196 -0
  36. code_puppy-0.0.173/code_puppy/tools/browser/camoufox_manager.py +194 -0
  37. code_puppy-0.0.173/code_puppy/tools/browser/vqa_agent.py +66 -0
  38. code_puppy-0.0.173/code_puppy/tools/browser_control.py +293 -0
  39. code_puppy-0.0.173/code_puppy/tools/browser_interactions.py +552 -0
  40. code_puppy-0.0.173/code_puppy/tools/browser_locators.py +642 -0
  41. code_puppy-0.0.173/code_puppy/tools/browser_navigation.py +251 -0
  42. code_puppy-0.0.173/code_puppy/tools/browser_screenshot.py +278 -0
  43. code_puppy-0.0.173/code_puppy/tools/browser_scripts.py +478 -0
  44. code_puppy-0.0.173/code_puppy/tools/browser_workflows.py +215 -0
  45. code_puppy-0.0.173/code_puppy/tools/camoufox_manager.py +150 -0
  46. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tools/command_runner.py +13 -8
  47. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tools/file_operations.py +7 -7
  48. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/app.py +1 -1
  49. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/components/custom_widgets.py +1 -1
  50. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/screens/mcp_install_wizard.py +8 -8
  51. code_puppy-0.0.173/code_puppy/tui_state.py +55 -0
  52. {code_puppy-0.0.171 → code_puppy-0.0.173}/pyproject.toml +3 -1
  53. code_puppy-0.0.171/code_puppy/agents/base_agent.py +0 -116
  54. code_puppy-0.0.171/code_puppy/state_management.py +0 -157
  55. code_puppy-0.0.171/code_puppy/tools/__init__.py +0 -70
  56. {code_puppy-0.0.171 → code_puppy-0.0.173}/.gitignore +0 -0
  57. {code_puppy-0.0.171 → code_puppy-0.0.173}/LICENSE +0 -0
  58. {code_puppy-0.0.171 → code_puppy-0.0.173}/README.md +0 -0
  59. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/__init__.py +0 -0
  60. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/__main__.py +0 -0
  61. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/agents/__init__.py +0 -0
  62. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/agents/agent_code_puppy.py +0 -0
  63. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/agents/agent_manager.py +0 -0
  64. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/agents/agent_orchestrator.json +0 -0
  65. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/agents/json_agent.py +0 -0
  66. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/agents/runtime_manager.py +0 -0
  67. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/callbacks.py +0 -0
  68. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/__init__.py +0 -0
  69. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/file_path_completion.py +0 -0
  70. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/load_context_completion.py +0 -0
  71. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/__init__.py +0 -0
  72. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/handler.py +0 -0
  73. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/help_command.py +0 -0
  74. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/logs_command.py +0 -0
  75. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/remove_command.py +0 -0
  76. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/restart_command.py +0 -0
  77. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/start_command.py +0 -0
  78. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/stop_command.py +0 -0
  79. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/mcp/test_command.py +0 -0
  80. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/meta_command_handler.py +0 -0
  81. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/model_picker_completion.py +0 -0
  82. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/motd.py +0 -0
  83. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/prompt_toolkit_completion.py +0 -0
  84. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/command_line/utils.py +0 -0
  85. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/__init__.py +0 -0
  86. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/async_lifecycle.py +0 -0
  87. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/blocking_startup.py +0 -0
  88. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/captured_stdio_server.py +0 -0
  89. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/circuit_breaker.py +0 -0
  90. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/dashboard.py +0 -0
  91. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/error_isolation.py +0 -0
  92. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/health_monitor.py +0 -0
  93. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/manager.py +0 -0
  94. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/registry.py +0 -0
  95. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/retry_manager.py +0 -0
  96. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/status_tracker.py +0 -0
  97. {code_puppy-0.0.171/code_puppy/mcp → code_puppy-0.0.173/code_puppy/mcp_}/system_tools.py +0 -0
  98. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/messaging/__init__.py +0 -0
  99. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/messaging/queue_console.py +0 -0
  100. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/messaging/renderers.py +0 -0
  101. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/messaging/spinner/__init__.py +0 -0
  102. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/messaging/spinner/console_spinner.py +0 -0
  103. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/messaging/spinner/spinner_base.py +0 -0
  104. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/messaging/spinner/textual_spinner.py +0 -0
  105. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/model_factory.py +0 -0
  106. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/models.json +0 -0
  107. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/plugins/__init__.py +0 -0
  108. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/reopenable_async_client.py +0 -0
  109. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/round_robin_model.py +0 -0
  110. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/status_display.py +0 -0
  111. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/summarization_agent.py +0 -0
  112. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tools/agent_tools.py +0 -0
  113. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tools/common.py +0 -0
  114. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tools/file_modifications.py +0 -0
  115. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tools/tools_content.py +0 -0
  116. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/__init__.py +0 -0
  117. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/components/__init__.py +0 -0
  118. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/components/chat_view.py +0 -0
  119. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/components/command_history_modal.py +0 -0
  120. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/components/copy_button.py +0 -0
  121. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/components/human_input_modal.py +0 -0
  122. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/components/input_area.py +0 -0
  123. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/components/sidebar.py +0 -0
  124. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/components/status_bar.py +0 -0
  125. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/messages.py +0 -0
  126. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/models/__init__.py +0 -0
  127. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/models/chat_message.py +0 -0
  128. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/models/command_history.py +0 -0
  129. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/models/enums.py +0 -0
  130. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/screens/__init__.py +0 -0
  131. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/screens/help.py +0 -0
  132. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/screens/settings.py +0 -0
  133. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/tui/screens/tools.py +0 -0
  134. {code_puppy-0.0.171 → code_puppy-0.0.173}/code_puppy/version_checker.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: code-puppy
3
- Version: 0.0.171
3
+ Version: 0.0.173
4
4
  Summary: Code generation agent
5
5
  Project-URL: repository, https://github.com/mpfaffenberger/code_puppy
6
6
  Project-URL: HomePage, https://github.com/mpfaffenberger/code_puppy
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.13
16
16
  Classifier: Topic :: Software Development :: Code Generators
17
17
  Requires-Python: >=3.11
18
18
  Requires-Dist: bs4>=0.0.2
19
+ Requires-Dist: camoufox>=0.4.11
19
20
  Requires-Dist: fastapi>=0.110.0
20
21
  Requires-Dist: httpx-limiter>=0.3.0
21
22
  Requires-Dist: httpx>=0.24.1
@@ -23,6 +24,7 @@ Requires-Dist: json-repair>=0.46.2
23
24
  Requires-Dist: logfire>=0.7.1
24
25
  Requires-Dist: openai>=1.99.1
25
26
  Requires-Dist: pathspec>=0.11.0
27
+ Requires-Dist: playwright>=1.40.0
26
28
  Requires-Dist: prompt-toolkit>=3.0.38
27
29
  Requires-Dist: pydantic-ai>=1.0.10
28
30
  Requires-Dist: pydantic>=2.4.0
@@ -7,10 +7,7 @@ from pydantic_ai import Agent
7
7
  from pydantic_ai.settings import ModelSettings
8
8
  from pydantic_ai.usage import UsageLimits
9
9
 
10
- from code_puppy.message_history_processor import (
11
- get_model_context_length,
12
- message_history_accumulator,
13
- )
10
+ from code_puppy.message_history_processor import message_history_accumulator
14
11
  from code_puppy.messaging.message_queue import (
15
12
  emit_error,
16
13
  emit_info,
@@ -48,7 +45,7 @@ _code_generation_agent = None
48
45
  def _load_mcp_servers(extra_headers: Optional[Dict[str, str]] = None):
49
46
  """Load MCP servers using the new manager while maintaining backward compatibility."""
50
47
  from code_puppy.config import get_value, load_mcp_server_configs
51
- from code_puppy.mcp import ServerConfig, get_mcp_manager
48
+ from code_puppy.mcp_ import ServerConfig, get_mcp_manager
52
49
 
53
50
  # Check if MCP servers are disabled
54
51
  mcp_disabled = get_value("disable_mcp_servers")
@@ -113,7 +110,7 @@ def _load_mcp_servers(extra_headers: Optional[Dict[str, str]] = None):
113
110
 
114
111
  def reload_mcp_servers():
115
112
  """Reload MCP servers without restarting the agent."""
116
- from code_puppy.mcp import get_mcp_manager
113
+ from code_puppy.mcp_ import get_mcp_manager
117
114
 
118
115
  manager = get_mcp_manager()
119
116
  # Reload configurations
@@ -167,14 +164,17 @@ def reload_code_generation_agent(message_group: str | None):
167
164
 
168
165
  # Configure model settings with max_tokens if set
169
166
  model_settings_dict = {"seed": 42}
170
- output_tokens = max(2048, min(int(0.05 * get_model_context_length()) - 1024, 16384))
167
+ # Get current agent to use its method
168
+ from code_puppy.agents import get_current_agent_config
169
+ current_agent = get_current_agent_config()
170
+ output_tokens = max(2048, min(int(0.05 * current_agent.get_model_context_length()) - 1024, 16384))
171
171
  console.print(f"Max output tokens per message: {output_tokens}")
172
172
  model_settings_dict["max_tokens"] = output_tokens
173
173
 
174
174
 
175
175
  model_settings = ModelSettings(**model_settings_dict)
176
176
  if "gpt-5" in model_name:
177
- model_settings_dict["openai_reasoning_effort"] = "high"
177
+ model_settings_dict["openai_reasoning_effort"] = "off"
178
178
  model_settings_dict["extra_body"] = {
179
179
  "verbosity": "low"
180
180
  }
@@ -245,9 +245,6 @@ Best-practice guidelines for `invoke_agent`:
245
245
  Your solutions should be production-ready, maintainable, and follow best practices for the chosen language.
246
246
 
247
247
  Return your final response as a string output
248
- Walmart specific rules:
249
- - You are operating inside Walmart Global Tech! Yay!
250
- - Always use uv when working with python, and always use --index-url https://pypi.ci.artifacts.walmart.com/artifactory/api/pypi/external-pypi/simple
251
248
 
252
249
  ## Tool Templates:
253
250
 
@@ -0,0 +1,203 @@
1
+ """Quality Assurance Kitten - Playwright-powered browser automation agent."""
2
+
3
+ from .base_agent import BaseAgent
4
+
5
+
6
+ class QualityAssuranceKittenAgent(BaseAgent):
7
+ """Quality Assurance Kitten - Advanced browser automation with Playwright."""
8
+
9
+ @property
10
+ def name(self) -> str:
11
+ return "qa-kitten"
12
+
13
+ @property
14
+ def display_name(self) -> str:
15
+ return "Quality Assurance Kitten 🐱"
16
+
17
+ @property
18
+ def description(self) -> str:
19
+ return "Advanced web browser automation and quality assurance testing using Playwright with VQA capabilities"
20
+
21
+ def get_available_tools(self) -> list[str]:
22
+ """Get the list of tools available to Web Browser Puppy."""
23
+ return [
24
+ # Core agent tools
25
+ "agent_share_your_reasoning",
26
+ # Browser control and initialization
27
+ "browser_initialize",
28
+ "browser_close",
29
+ "browser_status",
30
+ "browser_new_page",
31
+ "browser_list_pages",
32
+ # Browser navigation
33
+ "browser_navigate",
34
+ "browser_get_page_info",
35
+ "browser_go_back",
36
+ "browser_go_forward",
37
+ "browser_reload",
38
+ "browser_wait_for_load",
39
+ # Element discovery (semantic locators preferred)
40
+ "browser_find_by_role",
41
+ "browser_find_by_text",
42
+ "browser_find_by_label",
43
+ "browser_find_by_placeholder",
44
+ "browser_find_by_test_id",
45
+ "browser_find_buttons",
46
+ "browser_find_links",
47
+ "browser_xpath_query", # Fallback when semantic locators fail
48
+ # Element interactions
49
+ "browser_click",
50
+ "browser_double_click",
51
+ "browser_hover",
52
+ "browser_set_text",
53
+ "browser_get_text",
54
+ "browser_get_value",
55
+ "browser_select_option",
56
+ "browser_check",
57
+ "browser_uncheck",
58
+ # Advanced features
59
+ "browser_execute_js",
60
+ "browser_scroll",
61
+ "browser_scroll_to_element",
62
+ "browser_set_viewport",
63
+ "browser_wait_for_element",
64
+ "browser_highlight_element",
65
+ "browser_clear_highlights",
66
+ # Screenshots and VQA
67
+ "browser_screenshot_analyze",
68
+ # Workflow management
69
+ "browser_save_workflow",
70
+ "browser_list_workflows",
71
+ "browser_read_workflow",
72
+ ]
73
+
74
+ def get_system_prompt(self) -> str:
75
+ """Get Web Browser Puppy's specialized system prompt."""
76
+ return """
77
+ You are Quality Assurance Kitten 🐱, an advanced autonomous browser automation and QA testing agent powered by Playwright!
78
+
79
+ You specialize in:
80
+ 🎯 **Quality Assurance Testing** - automated testing of web applications and user workflows
81
+ 👁️ **Visual verification** - taking screenshots and analyzing page content for bugs
82
+ 🔍 **Element discovery** - finding elements using semantic locators and accessibility best practices
83
+ 📝 **Data extraction** - scraping content and gathering information from web pages
84
+ 🧪 **Web automation** - filling forms, clicking buttons, navigating sites with precision
85
+ 🐛 **Bug detection** - identifying UI issues, broken functionality, and accessibility problems
86
+
87
+ ## Core Workflow Philosophy
88
+
89
+ For any browser task, follow this approach:
90
+ 1. **Check Existing Workflows**: Use browser_list_workflows to see if similar tasks have been solved before
91
+ 2. **Learn from History**: If relevant workflows exist, use browser_read_workflow to review proven strategies
92
+ 3. **Plan & Reason**: Use share_your_reasoning to break down complex tasks and explain your approach
93
+ 4. **Initialize**: Always start with browser_initialize if browser isn't running
94
+ 5. **Navigate**: Use browser_navigate to reach the target page
95
+ 6. **Discover**: Use semantic locators (PREFERRED) for element discovery
96
+ 7. **Verify**: Use highlighting and screenshots to confirm elements
97
+ 8. **Act**: Interact with elements through clicks, typing, etc.
98
+ 9. **Validate**: Take screenshots or query DOM to verify actions worked
99
+ 10. **Document Success**: Use browser_save_workflow to save successful patterns for future reuse
100
+
101
+ ## Tool Usage Guidelines
102
+
103
+ ### Browser Initialization
104
+ - **ALWAYS call browser_initialize first** before any other browser operations
105
+ - Choose appropriate settings: headless=False for debugging, headless=True for production
106
+ - Use browser_status to check current state
107
+
108
+ ### Element Discovery Best Practices (ACCESSIBILITY FIRST! 🌟)
109
+ - **PREFER semantic locators** - they're more reliable and follow accessibility standards
110
+ - Priority order:
111
+ 1. browser_find_by_role (button, link, textbox, heading, etc.)
112
+ 2. browser_find_by_label (for form inputs)
113
+ 3. browser_find_by_text (for visible text)
114
+ 4. browser_find_by_placeholder (for input hints)
115
+ 5. browser_find_by_test_id (for test-friendly elements)
116
+ 6. browser_xpath_query (ONLY as last resort)
117
+
118
+ ### Visual Verification Workflow
119
+ - **Before critical actions**: Use browser_highlight_element to visually confirm
120
+ - **After interactions**: Use browser_screenshot_analyze to verify results
121
+ - **VQA questions**: Ask specific, actionable questions like "Is the login button highlighted?"
122
+
123
+ ### Form Input Best Practices
124
+ - **ALWAYS check current values** with browser_get_value before typing
125
+ - Use browser_get_value after typing to verify success
126
+ - This prevents typing loops and gives clear visibility into form state
127
+ - Clear fields when appropriate before entering new text
128
+
129
+ ### Error Handling & Troubleshooting
130
+
131
+ **When Element Discovery Fails:**
132
+ 1. Try different semantic locators first
133
+ 2. Use browser_find_buttons or browser_find_links to see available elements
134
+ 3. Take a screenshot with browser_screenshot_analyze to understand the page layout
135
+ 4. Only use XPath as absolute last resort
136
+
137
+ **When Page Interactions Fail:**
138
+ 1. Check if element is visible with browser_wait_for_element
139
+ 2. Scroll element into view with browser_scroll_to_element
140
+ 3. Use browser_highlight_element to confirm element location
141
+ 4. Try browser_execute_js for complex interactions
142
+
143
+ ### JavaScript Execution
144
+ - Use browser_execute_js for:
145
+ - Complex page state checks
146
+ - Custom scrolling behavior
147
+ - Triggering events that standard tools can't handle
148
+ - Accessing browser APIs
149
+
150
+ ### Workflow Management 📋
151
+
152
+ **ALWAYS start new tasks by checking for existing workflows!**
153
+
154
+ **At the beginning of any automation task:**
155
+ 1. **browser_list_workflows** - Check what workflows are already available
156
+ 2. **browser_read_workflow** - If you find a relevant workflow, read it to understand the proven approach
157
+ 3. Adapt and apply the successful patterns from existing workflows
158
+
159
+ **When to save workflows:**
160
+ - After successfully completing a complex multi-step task
161
+ - When you discover a reliable pattern for a common website interaction
162
+ - After troubleshooting and finding working solutions for tricky elements
163
+ - Include both the successful steps AND the challenges/solutions you encountered
164
+
165
+ **Workflow naming conventions:**
166
+ - Use descriptive names like "search_and_atc_walmart", "login_to_github", "fill_contact_form"
167
+ - Include the website domain for clarity
168
+ - Focus on the main goal/outcome
169
+
170
+ **What to include in saved workflows:**
171
+ - Step-by-step tool usage with specific parameters
172
+ - Element discovery strategies that worked
173
+ - Common pitfalls and how to avoid them
174
+ - Alternative approaches for edge cases
175
+ - Tips for handling dynamic content
176
+
177
+ ### Performance & Best Practices
178
+ - Use appropriate timeouts for element discovery (default 10s is usually fine)
179
+ - Take screenshots strategically - not after every single action
180
+ - Use browser_wait_for_load when navigating to ensure pages are ready
181
+ - Clear highlights when done for clean visual state
182
+
183
+ ## Specialized Capabilities
184
+
185
+ 🌐 **WCAG 2.2 Level AA Compliance**: Always prioritize accessibility in element discovery
186
+ 📸 **Visual Question Answering**: Use browser_screenshot_analyze for intelligent page analysis
187
+ 🚀 **Semantic Web Navigation**: Prefer role-based and label-based element discovery
188
+ ⚡ **Playwright Power**: Full access to modern browser automation capabilities
189
+ 📋 **Workflow Management**: Save, load, and reuse automation patterns for consistency
190
+
191
+ ## Important Rules
192
+
193
+ - **ALWAYS check for existing workflows first** - Use browser_list_workflows at the start of new tasks
194
+ - **ALWAYS use browser_initialize before any browser operations**
195
+ - **PREFER semantic locators over XPath** - they're more maintainable and accessible
196
+ - **Use visual verification for critical actions** - highlight elements and take screenshots
197
+ - **Be explicit about your reasoning** - use share_your_reasoning for complex workflows
198
+ - **Handle errors gracefully** - provide helpful debugging information
199
+ - **Follow accessibility best practices** - your automation should work for everyone
200
+ - **Document your successes** - Save working patterns with browser_save_workflow for future reuse
201
+
202
+ Your browser automation should be reliable, maintainable, and accessible. You are a meticulous QA engineer who catches bugs before users do! 🐱✨
203
+ """