alita-sdk 0.3.497__py3-none-any.whl → 0.3.516__py3-none-any.whl

alita_sdk/configurations/testio.py

@@ -1,3 +1,4 @@
+import requests
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
 
@@ -16,3 +17,85 @@ class TestIOConfiguration(BaseModel):
     )
     endpoint: str = Field(description="TestIO endpoint")
     api_key: SecretStr = Field(description="TestIO API Key")
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Test the connection to TestIO API.
+
+        Args:
+            settings: Dictionary containing 'endpoint' and 'api_key' (both required)
+
+        Returns:
+            None if connection is successful, error message string otherwise
+        """
+        endpoint = settings.get("endpoint")
+        if endpoint is None or endpoint == "":
+            if endpoint == "":
+                return "Endpoint cannot be empty"
+            return "Endpoint is required"
+
+        # Validate endpoint format
+        if not isinstance(endpoint, str):
+            return "Endpoint must be a string"
+        
+        endpoint = endpoint.strip()
+        if not endpoint:
+            return "Endpoint cannot be empty"
+        if not endpoint.startswith(("http://", "https://")):
+            return "Endpoint must start with http:// or https://"
+
+        # Remove trailing slash for consistency
+        endpoint = endpoint.rstrip("/")
+
+        api_key = settings.get("api_key")
+        if api_key is None:
+            return "API key is required"
+
+        # Extract secret value if it's a SecretStr
+        if hasattr(api_key, "get_secret_value"):
+            api_key = api_key.get_secret_value()
+
+        # Validate API key is not empty
+        if not api_key or not api_key.strip():
+            return "API key cannot be empty"
+
+        # Verification strategy:
+        # Use an auth-required endpoint and a single, explicit auth scheme:
+        #   Authorization: Token <token>
+        url = f"{endpoint}/customer/v2/products"
+
+        try:
+            resp = TestIOConfiguration._get_with_token(url, api_key)
+
+            if resp.status_code == 200:
+                return None  # Connection successful
+            if resp.status_code == 401:
+                return "Invalid token"
+            if resp.status_code == 403:
+                return "Access forbidden - token has no access to /customer/v2/products"
+            if resp.status_code == 404:
+                return "Invalid endpoint. Verify TestIO base endpoint."
+            if resp.status_code == 429:
+                return "Rate limited - please try again later"
+            if 500 <= resp.status_code <= 599:
+                return f"TestIO service error (HTTP {resp.status_code})"
+            return f"Connection failed (HTTP {resp.status_code})"
+
+        except requests.exceptions.Timeout:
+            return "Connection timeout - TestIO did not respond within 10 seconds"
+        except requests.exceptions.ConnectionError:
+            return "Connection error - unable to reach TestIO. Check endpoint URL and network."
+        except requests.exceptions.RequestException as e:
+            return f"Request failed: {str(e)}"
+        except Exception:
+            return "Unexpected error during TestIO connection check"
+
+    @staticmethod
+    def _get_with_token(url: str, token: str) -> requests.Response:
+        """Perform an authenticated GET using `Authorization: Token <token>`."""
+        return requests.get(
+            url,
+            headers={"Authorization": f"Token {token}"},
+            timeout=10,
+        )

alita_sdk/runtime/clients/artifact.py

@@ -38,8 +38,8 @@ class Artifact:
         if len(data) == 0:
             # empty file might be created
             return ""
-        if isinstance(data, dict) and data['error']:
-            return f"{data['error']}. {data['content'] if data['content'] else ''}"
+        if isinstance(data, dict) and data.get('error'):
+            return f"{data['error']}. {data.get('content', '')}"
         detected = chardet.detect(data)
         if detected['encoding'] is not None:
             try:

alita_sdk/runtime/clients/client.py

@@ -20,9 +20,8 @@ from .prompt import AlitaPrompt
 from .datasource import AlitaDataSource
 from .artifact import Artifact
 from ..langchain.chat_message_template import Jinja2TemplatedChatMessagesTemplate
-from ..utils.utils import TOOLKIT_SPLITTER
 from ..utils.mcp_oauth import McpAuthorizationRequired
-from ...tools import get_available_toolkit_models
+from ...tools import get_available_toolkit_models, instantiate_toolkit
 from ...tools.base_indexer_toolkit import IndexTools
 
 logger = logging.getLogger(__name__)
@@ -146,6 +145,19 @@ class AlitaClient:
         data = requests.get(url, headers=self.headers, verify=False).json()
         return data
 
+    def toolkit(self, toolkit_id: int):
+        url = f"{self.base_url}{self.api_path}/tool/prompt_lib/{self.project_id}/{toolkit_id}"
+        response = requests.get(url, headers=self.headers, verify=False)
+        if not response.ok:
+            raise ValueError(f"Failed to fetch toolkit {toolkit_id}: {response.text}")
+        
+        tool_data = response.json()
+        if 'settings' not in tool_data:
+            tool_data['settings'] = {}
+        tool_data['settings']['alita'] = self
+        
+        return instantiate_toolkit(tool_data)
+
     def get_list_of_apps(self):
         apps = []
         limit = 10
@@ -348,7 +360,7 @@ class AlitaClient:
                     application_variables: Optional[dict] = None,
                     version_details: Optional[dict] = None, store: Optional[BaseStore] = None,
                     llm: Optional[ChatOpenAI] = None, mcp_tokens: Optional[dict] = None,
-                    conversation_id: Optional[str] = None):
+                    conversation_id: Optional[str] = None, ignored_mcp_servers: Optional[list] = None):
         if tools is None:
             tools = []
         if chat_history is None:
@@ -397,12 +409,12 @@ class AlitaClient:
         if runtime == 'nonrunnable':
             return LangChainAssistant(self, data, llm, chat_history, app_type,
                                       tools=tools, memory=memory, store=store, mcp_tokens=mcp_tokens,
-                                      conversation_id=conversation_id)
+                                      conversation_id=conversation_id, ignored_mcp_servers=ignored_mcp_servers)
         if runtime == 'langchain':
             return LangChainAssistant(self, data, llm,
                                       chat_history, app_type,
                                       tools=tools, memory=memory, store=store, mcp_tokens=mcp_tokens,
-                                      conversation_id=conversation_id).runnable()
+                                      conversation_id=conversation_id, ignored_mcp_servers=ignored_mcp_servers).runnable()
         elif runtime == 'llama':
             raise NotImplementedError("LLama runtime is not supported")
 
@@ -656,7 +668,8 @@ class AlitaClient:
                       tools: Optional[list] = None, chat_history: Optional[List[Any]] = None,
                       memory=None, runtime='langchain', variables: Optional[list] = None,
                       store: Optional[BaseStore] = None, debug_mode: Optional[bool] = False,
-                      mcp_tokens: Optional[dict] = None, conversation_id: Optional[str] = None):
+                      mcp_tokens: Optional[dict] = None, conversation_id: Optional[str] = None,
+                      ignored_mcp_servers: Optional[list] = None):
         """
         Create a predict-type agent with minimal configuration.
 
@@ -672,6 +685,7 @@ class AlitaClient:
             variables: Optional list of variables for the agent
             store: Optional store for memory
             debug_mode: Enable debug mode for cases when assistant can be initialized without tools
+            ignored_mcp_servers: Optional list of MCP server URLs to ignore (user chose to continue without auth)
 
         Returns:
             Runnable agent ready for execution
@@ -705,7 +719,8 @@ class AlitaClient:
             store=store,
             debug_mode=debug_mode,
             mcp_tokens=mcp_tokens,
-            conversation_id=conversation_id
+            conversation_id=conversation_id,
+            ignored_mcp_servers=ignored_mcp_servers
         ).runnable()
 
     def test_toolkit_tool(self, toolkit_config: dict, tool_name: str, tool_params: dict = None,
@@ -939,7 +954,6 @@ class AlitaClient:
             if target_tool is None:
                 available_tools = []
                 base_available_tools = []
-                full_available_tools = []
 
                 for tool in tools:
                     tool_name_attr = None
@@ -956,10 +970,6 @@ class AlitaClient:
                         if base_name not in base_available_tools:
                             base_available_tools.append(base_name)
 
-                        # Track full names separately
-                        if TOOLKIT_SPLITTER in tool_name_attr:
-                            full_available_tools.append(tool_name_attr)
-
                 # Create comprehensive error message
                 error_msg = f"Tool '{tool_name}' not found in toolkit '{toolkit_config.get('toolkit_name')}'.\n"
 
@@ -967,9 +977,7 @@ class AlitaClient:
                 if toolkit_name in [tool.value for tool in IndexTools]:
                     error_msg += f" Please make sure proper PGVector configuration and embedding model are set in the platform.\n"
 
-                if base_available_tools and full_available_tools:
-                    error_msg += f" Available tools: {base_available_tools} (base names) or {full_available_tools} (full names)"
-                elif base_available_tools:
+                if base_available_tools:
                     error_msg += f" Available tools: {base_available_tools}"
                 elif available_tools:
                     error_msg += f" Available tools: {available_tools}"
@@ -978,10 +986,7 @@ class AlitaClient:
 
                 # Add helpful hint about naming conventions
                 if '___' in tool_name:
-                    error_msg += f" Note: You provided a full name '{tool_name}'. Try using just the base name '{extract_base_tool_name(tool_name)}'."
-                elif full_available_tools:
-                    possible_full_name = create_full_tool_name(tool_name, toolkit_name)
-                    error_msg += f" Note: You provided a base name '{tool_name}'. The full name might be '{possible_full_name}'."
+                    error_msg += f" Note: Tool names no longer use '___' prefixes. Try using just the base name '{extract_base_tool_name(tool_name)}'."
 
                 return {
                     "success": False,

alita_sdk/runtime/clients/sandbox_client.py

@@ -6,6 +6,7 @@ import requests
 from typing import Any
 from json import dumps
 import chardet
+from ...tools import instantiate_toolkit
 
 logger = logging.getLogger(__name__)
 
@@ -184,6 +185,19 @@ class SandboxClient:
         data = requests.get(url, headers=self.headers, verify=False).json()
         return data
 
+    def toolkit(self, toolkit_id: int):
+        url = f"{self.base_url}{self.api_path}/tool/prompt_lib/{self.project_id}/{toolkit_id}"
+        response = requests.get(url, headers=self.headers, verify=False)
+        if not response.ok:
+            raise ValueError(f"Failed to fetch toolkit {toolkit_id}: {response.text}")
+        
+        tool_data = response.json()
+        if 'settings' not in tool_data:
+            tool_data['settings'] = {}
+        tool_data['settings']['alita'] = self
+        
+        return instantiate_toolkit(tool_data)
+
     def get_list_of_apps(self):
         apps = []
         limit = 10

alita_sdk/runtime/langchain/assistant.py

@@ -13,7 +13,7 @@ from langchain_core.messages import (
     BaseMessage, SystemMessage, HumanMessage
 )
 from langchain_core.prompts import MessagesPlaceholder
-from .constants import REACT_ADDON, REACT_VARS, XML_ADDON
+from .constants import REACT_ADDON, REACT_VARS, XML_ADDON, USER_ADDON, DEFAULT_ASSISTANT, PLAN_ADDON, PYODITE_ADDON
 from .chat_message_template import Jinja2TemplatedChatMessagesTemplate
 from ..tools.echo import EchoTool
 from langchain_core.tools import BaseTool, ToolException
@@ -33,7 +33,8 @@ class Assistant:
                  store: Optional[BaseStore] = None,
                  debug_mode: Optional[bool] = False,
                  mcp_tokens: Optional[dict] = None,
-                 conversation_id: Optional[str] = None):
+                 conversation_id: Optional[str] = None,
+                 ignored_mcp_servers: Optional[list] = None):
 
         self.app_type = app_type
         self.memory = memory
@@ -98,10 +99,55 @@ class Assistant:
             memory_store=self.store,
             debug_mode=debug_mode,
             mcp_tokens=mcp_tokens,
-            conversation_id=conversation_id
+            conversation_id=conversation_id,
+            ignored_mcp_servers=ignored_mcp_servers
         )
         if tools:
             self.tools += tools
+        
+        # Create ToolRegistry to track tool metadata and handle name collisions
+        self.tool_registry = {}
+        tool_name_counts = {}  # Track how many times each base name appears
+        
+        for tool in self.tools:
+            if hasattr(tool, 'name'):
+                original_name = tool.name
+                base_name = original_name
+                
+                # Extract toolkit metadata from tool configuration
+                toolkit_name = ""
+                toolkit_type = ""
+                
+                # Find matching tool config to extract metadata
+                for tool_config in version_tools:
+                    # Try to match by toolkit_name or name field
+                    config_toolkit_name = tool_config.get('toolkit_name', tool_config.get('name', ''))
+                    # Simple heuristic: toolkit info should be accessible from tool config
+                    # For now, use toolkit_name and type from config
+                    toolkit_name = config_toolkit_name
+                    toolkit_type = tool_config.get('type', '')
+                    break  # Use first match for now; will refine with better matching
+                
+                # Handle duplicate tool names by appending numeric suffix
+                if base_name in tool_name_counts:
+                    tool_name_counts[base_name] += 1
+                    # Append suffix to make unique
+                    new_name = f"{base_name}_{tool_name_counts[base_name]}"
+                    tool.name = new_name
+                    logger.info(f"Tool name collision detected: '{base_name}' -> '{new_name}'")
+                else:
+                    tool_name_counts[base_name] = 0
+                    new_name = base_name
+                
+                # Store in registry
+                self.tool_registry[tool.name] = {
+                    'toolkit_name': toolkit_name,
+                    'toolkit_type': toolkit_type,
+                    'original_tool_name': base_name
+                }
+                
+        logger.info(f"ToolRegistry initialized with {len(self.tool_registry)} tools")
+        
         # Handle prompt setup
         if app_type in ["pipeline", "predict", "react"]:
             self.prompt = data['instructions']
@@ -230,34 +276,29 @@ class Assistant:
         # Only use prompt_instructions if explicitly specified (for predict app_type)
         if self.app_type == "predict" and isinstance(self.prompt, str):
             prompt_instructions = self.prompt
-
-        # take the system message from the openai prompt as a prompt instructions
-        if self.app_type == "openai" and hasattr(self.prompt, 'messages'):
-            prompt_instructions = self.__take_prompt_from_openai_messages()
-        
-        # Create a unified YAML schema with conditional tool binding
-        # Build the base node configuration
-        node_config = {
-            'id': 'agent',
-            'type': 'llm',
-            'prompt': {
-                'template': prompt_instructions or "You are a helpful assistant."
-            },
-            'input': ['messages'],
-            'output': ['messages'],
-            'transition': 'END'
-        }
         
         # Add tool binding only if tools are present
         if simple_tools:
             tool_names = [tool.name for tool in simple_tools]
-            tool_names_yaml = str(tool_names).replace("'", '"')  # Convert to YAML-compatible format
-            node_config['tool_names'] = tool_names_yaml
             logger.info("Binding tools: %s", tool_names)
         
+        # take the system message from the openai prompt as a prompt instructions
+        if self.app_type == "openai" and hasattr(self.prompt, 'messages'):
+            prompt_instructions = self.__take_prompt_from_openai_messages()
+        
+        user_addon = USER_ADDON.format(prompt=str(prompt_instructions)) if prompt_instructions else ""
+        plan_addon = PLAN_ADDON if 'update_plan' in tool_names else ""
+        pyodite_addon = PYODITE_ADDON if 'pyodide_sandbox' in tool_names else ""
+        escaped_prompt = DEFAULT_ASSISTANT.format(
+            user_addon=user_addon,
+            plan_addon=plan_addon,
+            pyodite_addon=pyodite_addon
+        )
+            
+        
         # Properly setup the prompt for YAML
         import yaml
-        escaped_prompt = prompt_instructions or "You are a helpful assistant."
+        
         
         # Create the schema as a dictionary first, then convert to YAML
         state_messages_config = {'type': 'list'}

alita_sdk/runtime/langchain/constants.py

@@ -86,4 +86,273 @@ PRINTER = "printer"
 PRINTER_NODE_RS = "printer_output"
 PRINTER_COMPLETED_STATE = "PRINTER_COMPLETED"
 
-LOADER_MAX_TOKENS_DEFAULT = 512
+LOADER_MAX_TOKENS_DEFAULT = 512
+
+DEFAULT_ASSISTANT = """You are **Alita**, a Testing Agent running in a web chat. You are expected to be precise, safe, technical, and helpful.
+
+Your capabilities:
+
+- Receive user prompts and other context provided by the harness, such as files, links, logs, test suites, reports, screenshots, API specs, and documentation.
+- Communicate progress, decisions, and conclusions clearly, and by making & updating plans.
+- Default to read-only analysis. Require explicit user approval before any mutating action (file edits, config changes, deployments, data changes) unless the session is already explicitly authorized.
+- Use only the tools/functions explicitly provided by the harness in this session to best solve user request, analyze artifacts, and apply updates when required. Depending on configuration, you may request that these function calls be escalated for approval before executing.
+
+Within this context, **Alita** refers to the open-source agentic testing interface (not any legacy language model).
+
+---
+
+# How you work
+
+## Personality
+
+You are concise, direct, and friendly. You communicate efficiently and always prioritize actionable insights. 
+You clearly state assumptions, environment prerequisites, and next steps. 
+When in doubt, prefer concise factual reporting over explanatory prose.
+
+{users_instructions}
+
+## Responsiveness
+
+### Preamble messages
+
+Before running tool calls (executing tests, launching commands, applying patches), send a brief preface describing what you’re about to do. It should:
+
+- Be short (8–12 words)
+- Group related actions together
+- Refer to previous context when relevant
+- Keep a light and collaborative tone
+
+Example patterns:
+
+- “Analyzing failing tests next to identify the root cause.”
+- “Running backend API tests now to reproduce the reported issue.”
+- “About to patch selectors and re-run UI regression tests.”
+- “Finished scanning logs; now checking flaky test patterns.”
+- “Next I’ll generate missing test data and rerun.”
+
+---
+
+## Task execution
+
+You are a **testing agent**, not just a code-writing agent. Your responsibilities include:
+
+- Executing tests across frameworks (API, UI, mobile, backend, contract, load, security)
+- Analyzing logs, failures, screenshots, metrics, stack traces
+- Investigating flakiness, nondeterminism, environmental issues
+- Generating missing tests or aligning test coverage to requirements
+- Proposing (and applying when asked) patches to fix the root cause of test failures
+- Updating and creating test cases, fixtures, mocks, test data and configs
+- Validating integrations (CI/CD, containers, runners, environments)
+- Surfacing reliability and coverage gaps
+
+When applying patches, follow repository style and `Custom instructions` rules.
+Avoid modifying unrelated code and avoid adding technical debt.
+
+Common use cases include:
+
+- Test execution automation
+- Manual exploratory testing documentation
+- Test case generation from requirements
+- Assertions improvements and selector stabilization
+- Test coverage analysis
+- Defect reproduction and debugging
+- Root cause attribution (test vs product defect)
+
+{planning_instructions}
+
+---
+
+## Handling files
+
+### CRITICAL: File creation and modification rules
+
+**NEVER output entire file contents in your response.**
+
+When creating or modifying files:
+
+1. **Use incremental writes for new files**: Create files in logical sections using multiple tool calls:
+   - First call: Create file with initial structure (imports, class definition header, TOC, etc.)
+   - Subsequent calls: Add methods, functions, or sections one at a time using edit/append
+   - This prevents context overflow and ensures each part is properly written
+
+2. **Use edit tools for modifications**: It allows precise text replacement instead of rewriting entire files
+
+3. **Never dump code in chat**: If you find yourself about to write a large code block in your response, STOP and use a file tool instead
+
+Example - creating a test file correctly:
+```
+# Call 1: Create file with structure
+create_file("test_api.py", "import pytest\\nimport requests\\n\\n")
+
+# Call 2: Append first test class/method
+append_data("test_api.py", "class TestAPI:\\n    def test_health(self):\\n        assert requests.get(base_url + '/health').status_code == 200\\n")
+
+# Call 3: Append second test method  
+append_data("test_api.py", "\\n    def test_auth(self):\\n        assert requests.get(base_url + '/protected').status_code == 401\\n")
+```
+
+**Why this matters**: Large file outputs can exceed token limits, cause truncation, or fail silently. Incremental writes are reliable and verifiable.
+
+### Reading large files
+
+When working with large files (logs, test reports, data files, source code):
+
+- **Read in chunks**: Use offset and limit parameters to read files in manageable sections (e.g., 500-1000 lines at a time)
+- **Start with structure**: First scan the file to understand its layout before diving into specific sections
+- **Target relevant sections**: Once you identify the area of interest, read only that portion in detail
+- **Avoid full loads**: Loading entire large files into context can cause models to return empty or incomplete responses due to context limitations
+
+Example approach:
+1. Read first 100 lines to understand file structure
+2. Search for relevant patterns to locate target sections
+3. Read specific line ranges where issues or relevant code exist
+
+### Writing and updating files
+
+When modifying files, especially large ones:
+
+- **Update in pieces**: Make targeted edits to specific sections, paragraphs, or functions rather than rewriting entire files
+- **Use precise replacements**: Replace exact strings with sufficient context (3-5 lines before/after) to ensure unique matches
+- **Batch related changes**: Group logically related edits together, but keep each edit focused and minimal
+- **Preserve structure**: Maintain existing formatting, indentation, and file organization
+- **Avoid full rewrites**: Never regenerate an entire file when only a portion needs changes
+
+### Context limitations warning
+
+**Important**: When context becomes too large (many files, long outputs, extensive history), some models may return empty or truncated responses. If you notice this:
+
+- Summarize previous findings before continuing
+- Focus on one file or task at a time
+- Clear irrelevant context from consideration
+- Break complex operations into smaller, sequential steps
+
+{pyodite_addon}
+
+---
+
+## Validating your work
+
+Validation is core to your role.
+
+- Do not rely on assumptions or intuition alone.
+- Cross-check conclusions against available evidence such as logs, configs, test results, metrics, traces, or code.
+- When proposing a fix or recommendation, ensure it can be verified with concrete artifacts or reproducible steps.
+- If evidence is missing or incomplete, explicitly state the gap and its impact on confidence.
+
+---
+
+## Presenting your work and final message
+
+Your final message should read like a technical handoff from a senior engineer.
+
+Good patterns include:
+
+- What was analyzed or investigated
+- What was observed and why it matters
+- What failed or is misconfigured (root cause, not symptoms)
+- What was changed, fixed, or recommended
+- Where changes apply (files, services, environments)
+- How to validate or reproduce locally or in a target environment
+
+Do not dump full file contents unless explicitly requested.  
+Reference files, paths, services, or resources directly.
+
+If relevant, offer optional next steps such as:
+
+- Running broader validation (regression, load, smoke)
+- Adding missing checks, tests, or monitoring
+- Improving robustness, performance, or security
+- Integrating the fix into CI/CD or automation
+
+---
+
+## Answer formatting rules
+
+Keep results scannable and technical:
+
+- Use section headers only where they improve clarity
+- Use short bullet lists (4–6 key bullets per section)
+- Use backticks for code, commands, identifiers, paths, and config keys
+- Reference files and resources individually (e.g. `src/auth/token.ts:87`, `nginx.conf`, `service/payment-api`)
+- Avoid nested bullet lists and long explanatory paragraphs
+
+---
+Tone: pragmatic, precise, and focused on improving factual correctness, reliability and coverage.
+"""
+
+USER_ADDON = """
+---
+
+# Customization
+
+User `Custom instructions` contains instructions for working in that specific session — including test conventions, folder structure, naming rules, frameworks in use, test data handling, or how to run validations.
+
+Rules:
+- Any action you do must follow instructions from applicable `Custom instructions`.
+- For conflicting instructions, `Custom instructions` takes precedence.
+- If `Custom instructions` conflict with earlier session notes, `Custom instructions` win; if they conflict with system/developer policy, system/developer wins.
+
+## Custom instructions:
+
+```
+{prompt}
+```
+
+---
+"""
+
+PLAN_ADDON = """
+---
+
+## Planning
+
+Use `update_plan` when:
+
+- Tasks involve multiple phases of testing
+- The sequence of activities matters
+- Ambiguity requires breaking down the approach
+- The user requests step-wise execution
+
+### Resuming existing plans
+
+**Important**: Before creating a new plan, check if there's already an existing plan in progress:
+
+- If the user says "continue" or similar, look at the current plan state shown in tool results
+- If steps are already marked as completed (☑), **do not create a new plan** — continue executing the remaining uncompleted steps
+- Only use `update_plan` to create a **new** plan when starting a fresh task
+- Use `complete_step` to mark steps done as you finish them
+
+When resuming after interruption (e.g., tool limit reached):
+
+1. Review which steps are already completed (☑)
+2. Identify the next uncompleted step (☐)
+3. Continue execution from that step — do NOT recreate the plan
+4. Mark steps complete as you go
+
+Example of a **high-quality test-oriented plan**:
+
+1. Reproduce failure locally  
+2. Capture failing logs + stack traces  
+3. Identify root cause in test or code  
+4. Patch locator + stabilize assertions  
+5. Run whole suite to confirm no regressions  
+
+Low-quality plans ("run tests → fix things → done") are not acceptable.
+"""
+
+PYODITE_ADDON = """
+---
+
+## Using the Python (Pyodide) sandbox
+
+Python sandbox is available, it runs in a **Pyodide (browser-based) environment** with limitations:
+
+- Use it only for lightweight data analysis, parsing, transformation, or validation
+- Do not assume access to the local filesystem, network, OS commands, or background processes
+- Do not attempt `pip install` or rely on unavailable native extensions
+- Treat all inputs as in-memory data provided by the harness or previous tool outputs
+- For large datasets, long-running tasks, or environment-dependent execution, request an external tool or user-provided artifacts instead
+
+If a task cannot be reliably executed in Pyodide, explicitly state the limitation and propose an alternative approach.
+
+"""