openhands-sdk 1.7.3__py3-none-any.whl

openhands/sdk/context/condenser/pipeline_condenser.py

@@ -0,0 +1,56 @@
+from openhands.sdk.context.condenser.base import CondenserBase
+from openhands.sdk.context.view import View
+from openhands.sdk.event.condenser import Condensation
+from openhands.sdk.llm import LLM
+
+
+class PipelineCondenser(CondenserBase):
+    """A condenser that applies a sequence of condensers in order.
+
+    All condensers are defined primarily by their `condense` method, which takes a
+    `View` and an optional `agent_llm` parameter, returning either a new `View` or a
+    `Condensation` event. That means we can chain multiple condensers together by
+    passing `View`s along and exiting early if any condenser returns a `Condensation`.
+
+    For example:
+
+        # Use the pipeline condenser to chain multiple other condensers together
+        condenser = PipelineCondenser(condensers=[
+            CondenserA(...),
+            CondenserB(...),
+            CondenserC(...),
+        ])
+
+        result = condenser.condense(view, agent_llm=agent_llm)
+
+        # Doing the same thing without the pipeline condenser requires more boilerplate
+        # for the monadic chaining
+        other_result = view
+
+        if isinstance(other_result, View):
+            other_result = CondenserA(...).condense(other_result, agent_llm=agent_llm)
+
+        if isinstance(other_result, View):
+            other_result = CondenserB(...).condense(other_result, agent_llm=agent_llm)
+
+        if isinstance(other_result, View):
+            other_result = CondenserC(...).condense(other_result, agent_llm=agent_llm)
+
+        assert result == other_result
+    """
+
+    condensers: list[CondenserBase]
+    """The list of condensers to apply in order."""
+
+    def condense(self, view: View, agent_llm: LLM | None = None) -> View | Condensation:
+        result: View | Condensation = view
+        for condenser in self.condensers:
+            if isinstance(result, Condensation):
+                break
+            result = condenser.condense(result, agent_llm=agent_llm)
+        return result
+
+    def handles_condensation_requests(self) -> bool:
+        return any(
+            condenser.handles_condensation_requests() for condenser in self.condensers
+        )

openhands/sdk/context/condenser/prompts/summarizing_prompt.j2

@@ -0,0 +1,59 @@
+You are maintaining a context-aware state summary for an interactive agent.
+You will be given a list of events corresponding to actions taken by the agent, and the most recent previous summary if one exists.
+If the events being summarized contain ANY task-tracking, you MUST include a TASK_TRACKING section to maintain continuity.
+When referencing tasks make sure to preserve exact task IDs and statuses.
+
+Track:
+
+USER_CONTEXT: (Preserve essential user requirements, goals, and clarifications in concise form)
+
+TASK_TRACKING: {Active tasks, their IDs and statuses - PRESERVE TASK IDs}
+
+COMPLETED: (Tasks completed so far, with brief results)
+PENDING: (Tasks that still need to be done)
+CURRENT_STATE: (Current variables, data structures, or relevant state)
+
+For code-specific tasks, also include:
+CODE_STATE: {File paths, function signatures, data structures}
+TESTS: {Failing cases, error messages, outputs}
+CHANGES: {Code edits, variable updates}
+DEPS: {Dependencies, imports, external calls}
+VERSION_CONTROL_STATUS: {Repository state, current branch, PR status, commit history}
+
+PRIORITIZE:
+1. Adapt tracking format to match the actual task type
+2. Capture key user requirements and goals
+3. Distinguish between completed and pending tasks
+4. Keep all sections concise and relevant
+
+SKIP: Tracking irrelevant details for the current task type
+
+Example formats:
+
+For code tasks:
+USER_CONTEXT: Fix FITS card float representation issue
+COMPLETED: Modified mod_float() in card.py, all tests passing
+PENDING: Create PR, update documentation
+CODE_STATE: mod_float() in card.py updated
+TESTS: test_format() passed
+CHANGES: str(val) replaces f"{val:.16G}"
+DEPS: None modified
+VERSION_CONTROL_STATUS: Branch: fix-float-precision, Latest commit: a1b2c3d
+
+For other tasks:
+USER_CONTEXT: Write 20 haikus based on coin flip results
+COMPLETED: 15 haikus written for results [T,H,T,H,T,H,T,T,H,T,H,T,H,T,H]
+PENDING: 5 more haikus needed
+CURRENT_STATE: Last flip: Heads, Haiku count: 15/20
+
+<PREVIOUS SUMMARY>
+{{ previous_summary }}
+</PREVIOUS SUMMARY>
+
+{% for event in events %}
+<EVENT>
+{{ event }}
+</EVENT>
+{% endfor %}
+
+Now summarize the events using the rules above.

openhands/sdk/context/condenser/utils.py

@@ -0,0 +1,149 @@
+from collections.abc import Sequence
+
+from openhands.sdk.event.base import LLMConvertibleEvent
+from openhands.sdk.llm import LLM
+
+
+def get_total_token_count(
+    events: Sequence[LLMConvertibleEvent],
+    llm: LLM,
+) -> int:
+    """Calculate the total token count for a list of LLM convertible events.
+
+    This function converts the events to LLM messages and uses the provided LLM
+    to count the total number of tokens. This is useful for understanding how many
+    tokens a sequence of events will consume in the context window.
+
+    Args:
+        events: List of LLM convertible events to count tokens for
+        llm: The LLM instance to use for token counting (uses the litellm's token
+            counting utilities)
+
+    Returns:
+        Total token count for all events converted to messages
+
+    Example:
+        >>> from openhands.sdk.llm import LLM
+        >>> from openhands.sdk.event.llm_convertible import MessageEvent
+        >>>
+        >>> llm = LLM(model="gpt-4")
+        >>> events = [
+        ...     MessageEvent.from_text("Hello, how are you?", source="user"),
+        ...     MessageEvent.from_text("I'm doing great!", source="agent"),
+        ... ]
+        >>> token_count = get_total_token_count(events, llm)
+        >>> print(f"Total tokens: {token_count}")
+    """
+    messages = LLMConvertibleEvent.events_to_messages(list(events))
+    return llm.get_token_count(messages)
+
+
+def get_shortest_prefix_above_token_count(
+    events: Sequence[LLMConvertibleEvent],
+    llm: LLM,
+    token_count: int,
+) -> int:
+    """Find the length of the shortest prefix whose token count exceeds the target.
+
+    This function performs a binary search to efficiently find the shortest prefix
+    of events that, when converted to messages, has a total token count greater than
+    the specified target token count.
+
+    Args:
+        events: List of LLM convertible events to search through
+        llm: The LLM instance to use for token counting (uses the model's tokenizer)
+        token_count: The target token count threshold
+
+    Returns:
+        The length of the shortest prefix that exceeds the token count.
+        Returns 0 if no events are provided.
+        Returns len(events) if all events combined don't exceed the token count.
+
+    Example:
+        >>> from openhands.sdk.llm import LLM
+        >>> from openhands.sdk.event.llm_convertible import MessageEvent
+        >>>
+        >>> llm = LLM(model="gpt-4")
+        >>> events = [
+        ...     MessageEvent.from_text("Hi", source="user"),
+        ...     MessageEvent.from_text("Hello", source="agent"),
+        ...     MessageEvent.from_text("How are you?", source="user"),
+        ...     MessageEvent.from_text("Great!", source="agent"),
+        ... ]
+        >>> prefix_len = get_shortest_prefix_above_token_count(events, llm, 20)
+        >>> # prefix_len might be 2 if first 2 events exceed 20 tokens
+    """
+    if not events:
+        return 0
+
+    # Check if all events combined don't exceed the token count
+    total_tokens = get_total_token_count(events, llm)
+    if total_tokens <= token_count:
+        return len(events)
+
+    # Binary search for the shortest prefix
+    left, right = 1, len(events)
+
+    while left < right:
+        mid = (left + right) // 2
+        prefix_tokens = get_total_token_count(events[:mid], llm)
+
+        if prefix_tokens > token_count:
+            # This prefix exceeds the count, try to find a shorter one
+            right = mid
+        else:
+            # This prefix doesn't exceed, we need a longer one
+            left = mid + 1
+
+    return left
+
+
+def get_suffix_length_for_token_reduction(
+    events: Sequence[LLMConvertibleEvent],
+    llm: LLM,
+    token_reduction: int,
+) -> int:
+    """Find how many suffix events can be kept while reducing tokens by target amount.
+
+    This function determines the maximum number of events from the end of the list
+    that can be retained while ensuring the total token count is reduced by at least
+    the specified amount. It uses the get_shortest_prefix_above_token_count function
+    to find the prefix that must be removed.
+
+    Args:
+        events: List of LLM convertible events
+        llm: The LLM instance to use for token counting (uses the model's tokenizer)
+        token_reduction: The minimum number of tokens to reduce by
+
+    Returns:
+        The number of events from the end that can be kept (suffix length).
+
+    Example:
+        >>> from openhands.sdk.llm import LLM
+        >>> from openhands.sdk.event.llm_convertible import MessageEvent
+        >>>
+        >>> llm = LLM(model="gpt-4")
+        >>> events = [
+        ...     MessageEvent.from_text("Event 1", source="user"),
+        ...     MessageEvent.from_text("Event 2", source="agent"),
+        ...     MessageEvent.from_text("Event 3", source="user"),
+        ...     MessageEvent.from_text("Event 4", source="agent"),
+        ... ]
+        >>> # Suppose total is 100 tokens, and we want to reduce by 40 tokens
+        >>> suffix_len = get_suffix_length_for_token_reduction(events, llm, 40)
+        >>> # suffix_len tells us how many events from the end we can keep
+        >>> # If first 2 events = 45 tokens, suffix_len = 2 (keep last 2 events)
+    """
+    if not events:
+        return 0
+
+    if token_reduction <= 0:
+        return len(events)
+
+    # Find the shortest prefix that exceeds the token reduction target
+    prefix_length = get_shortest_prefix_above_token_count(events, llm, token_reduction)
+
+    # The suffix length is what remains after removing the prefix
+    suffix_length = len(events) - prefix_length
+
+    return suffix_length

openhands/sdk/context/prompts/__init__.py

@@ -0,0 +1,6 @@
+from openhands.sdk.context.prompts.prompt import render_template
+
+
+__all__ = [
+    "render_template",
+]

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)