openhands-sdk 1.7.0__py3-none-any.whl

openhands/sdk/context/prompts/prompt.py

@@ -0,0 +1,114 @@
+# prompt_utils.py
+import os
+import re
+import sys
+from functools import lru_cache
+
+from jinja2 import (
+    BaseLoader,
+    Environment,
+    FileSystemBytecodeCache,
+    Template,
+    TemplateNotFound,
+)
+
+
+class FlexibleFileSystemLoader(BaseLoader):
+    """A Jinja2 loader that supports both relative paths (within a base directory)
+    and absolute paths anywhere on the filesystem.
+    """
+
+    def __init__(self, searchpath: str):
+        self.searchpath = os.path.abspath(searchpath)
+
+    def get_source(self, environment, template):  # noqa: ARG002
+        # If template is an absolute path, use it directly
+        if os.path.isabs(template):
+            path = template
+        else:
+            # Otherwise, look for it in the searchpath
+            path = os.path.join(self.searchpath, template)
+
+        if not os.path.exists(path):
+            raise TemplateNotFound(template)
+
+        mtime = os.path.getmtime(path)
+        with open(path, encoding="utf-8") as f:
+            source = f.read()
+
+        def uptodate():
+            try:
+                return os.path.getmtime(path) == mtime
+            except OSError:
+                return False
+
+        return source, path, uptodate
+
+
+def refine(text: str) -> str:
+    if sys.platform == "win32":
+        text = re.sub(r"\bterminal\b", "execute_powershell", text, flags=re.IGNORECASE)
+        text = re.sub(
+            r"(?<!execute_)(?<!_)\bbash\b", "powershell", text, flags=re.IGNORECASE
+        )
+    return text
+
+
+@lru_cache(maxsize=64)
+def _get_env(prompt_dir: str) -> Environment:
+    if not prompt_dir:
+        raise ValueError("prompt_dir is required")
+    # BytecodeCache avoids reparsing templates across processes
+    # Use user-specific cache directory to avoid permission issues
+    # in multi-user environments
+    cache_folder = os.path.join(os.path.expanduser("~"), ".openhands", "cache", "jinja")
+    os.makedirs(cache_folder, exist_ok=True)
+    bcc = FileSystemBytecodeCache(directory=cache_folder)
+    env = Environment(
+        loader=FlexibleFileSystemLoader(prompt_dir),
+        bytecode_cache=bcc,
+        autoescape=False,
+    )
+    # Optional: expose refine as a filter so templates can use {{ text|refine }}
+    env.filters["refine"] = refine
+    return env
+
+
+@lru_cache(maxsize=256)
+def _get_template(prompt_dir: str, template_name: str) -> Template:
+    env = _get_env(prompt_dir)
+    try:
+        return env.get_template(template_name)
+    except Exception:
+        raise FileNotFoundError(
+            f"Prompt file {os.path.join(prompt_dir, template_name)} not found"
+        )
+
+
+def render_template(prompt_dir: str, template_name: str, **ctx) -> str:
+    """Render a Jinja2 template.
+
+    Args:
+        prompt_dir: The base directory for relative template paths.
+        template_name: The template filename. Can be either:
+            - A relative filename (e.g., "system_prompt.j2") loaded from prompt_dir
+            - An absolute path (e.g., "/path/to/custom_prompt.j2")
+        **ctx: Template context variables.
+
+    Returns:
+        Rendered template string.
+
+    Raises:
+        FileNotFoundError: If the template file cannot be found.
+    """
+    # If template_name is an absolute path, extract directory and filename
+    if os.path.isabs(template_name):
+        # Check if the file exists before trying to load it
+        if not os.path.isfile(template_name):
+            raise FileNotFoundError(f"Prompt file {template_name} not found")
+        actual_dir = os.path.dirname(template_name)
+        actual_filename = os.path.basename(template_name)
+        tpl = _get_template(actual_dir, actual_filename)
+    else:
+        tpl = _get_template(prompt_dir, template_name)
+    return refine(tpl.render(**ctx).strip())

openhands/sdk/context/prompts/templates/ask_agent_template.j2

@@ -0,0 +1,11 @@
+<QUESTION>
+Based on the activity so far answer the following question
+
+## Question
+{{ question }}
+
+
+<IMPORTANT>
+This is a question, do not make any tool call and just answer my question.
+</IMPORTANT>
+</QUESTION>

openhands/sdk/context/prompts/templates/skill_knowledge_info.j2

@@ -0,0 +1,8 @@
+{% for agent_info in triggered_agents %}
+<EXTRA_INFO>
+The following information has been included based on a keyword match for "{{ agent_info.trigger }}".
+It may or may not be relevant to the user's request.
+
+{{ agent_info.content }}
+</EXTRA_INFO>
+{% endfor %}

openhands/sdk/context/prompts/templates/system_message_suffix.j2

@@ -0,0 +1,32 @@
+{% if repo_skills %}
+<REPO_CONTEXT>
+The following information has been included based on several files defined in user's repository.
+Please follow them while working.
+
+{% for agent_info in repo_skills %}
+[BEGIN context from [{{ agent_info.name }}]]
+{{ agent_info.content }}
+[END Context]
+{% endfor %}
+</REPO_CONTEXT>
+{% endif %}
+{% if system_message_suffix %}
+
+{{ system_message_suffix }}
+{% endif %}
+{% if secret_infos %}
+<CUSTOM_SECRETS>
+### Credential Access
+* Automatic secret injection: When you reference a registered secret key in your bash command, the secret value will be automatically exported as an environment variable before your command executes.
+* How to use secrets: Simply reference the secret key in your command (e.g., `echo ${GITHUB_TOKEN:0:8}` or `curl -H "Authorization: Bearer $API_KEY" https://api.example.com`). The system will detect the key name in your command text and export it as environment variable before it executes your command.
+* Secret detection: The system performs case-insensitive matching to find secret keys in your command text. If a registered secret key appears anywhere in your command, its value will be made available as an environment variable.
+* Security: Secret values are automatically masked in command output to prevent accidental exposure. You will see `<secret-hidden>` instead of the actual secret value in the output.
+* Refreshing expired secrets: Some secrets (like GITHUB_TOKEN) may be updated periodically or expire over time. If a secret stops working (e.g., authentication failures), try using it again in a new command - the system should automatically use the refreshed value. For example, if GITHUB_TOKEN was used in a git remote URL and later expired, you can update the remote URL with the current token: `git remote set-url origin https://${GITHUB_TOKEN}@github.com/username/repo.git` to pick up the refreshed token value.
+* If it still fails, report it to the user.
+
+You have access to the following environment variables
+{% for secret_info in secret_infos %}
+* **${{ secret_info.name }}**{% if secret_info.description %} - {{ secret_info.description }}{% endif %}
+{% endfor %}
+</CUSTOM_SECRETS>
+{% endif %}

openhands/sdk/context/skills/__init__.py

@@ -0,0 +1,28 @@
+from openhands.sdk.context.skills.exceptions import SkillValidationError
+from openhands.sdk.context.skills.skill import (
+    Skill,
+    load_project_skills,
+    load_public_skills,
+    load_skills_from_dir,
+    load_user_skills,
+)
+from openhands.sdk.context.skills.trigger import (
+    BaseTrigger,
+    KeywordTrigger,
+    TaskTrigger,
+)
+from openhands.sdk.context.skills.types import SkillKnowledge
+
+
+__all__ = [
+    "Skill",
+    "BaseTrigger",
+    "KeywordTrigger",
+    "TaskTrigger",
+    "SkillKnowledge",
+    "load_skills_from_dir",
+    "load_user_skills",
+    "load_project_skills",
+    "load_public_skills",
+    "SkillValidationError",
+]

openhands/sdk/context/skills/exceptions.py

@@ -0,0 +1,11 @@
+class SkillError(Exception):
+    """Base exception for all skill errors."""
+
+    pass
+
+
+class SkillValidationError(SkillError):
+    """Raised when there's a validation error in skill metadata."""
+
+    def __init__(self, message: str = "Skill validation failed") -> None:
+        super().__init__(message)