Merge branch 'main' into vasco/fix-subagent-registration-on-server

Author: enyst

.github/workflows/agent-server-rest-api-breakage.yml

@@ -38,8 +38,9 @@ jobs:
               continue-on-error: ${{ !startsWith(github.head_ref, 'rel-') }}
               run: |
                   uv run --with packaging python .github/scripts/check_agent_server_rest_api_breakage.py 2>&1 | tee api-breakage.log
-                  echo "exit_code=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT"
-                  exit "${PIPESTATUS[0]}"
+                  exit_code=${PIPESTATUS[0]}
+                  echo "exit_code=${exit_code}" >> "$GITHUB_OUTPUT"
+                  exit "${exit_code}"
 
             - name: Post REST API breakage report to PR
               if: ${{ always() && github.event_name == 'pull_request' }}

.github/workflows/api-breakage.yml

@@ -30,8 +30,9 @@ jobs:
               continue-on-error: ${{ !startsWith(github.head_ref, 'rel-') }}
               run: |
                   uv run python .github/scripts/check_sdk_api_breakage.py 2>&1 | tee api-breakage.log
-                  echo "exit_code=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT"
-                  exit "${PIPESTATUS[0]}"
+                  exit_code=${PIPESTATUS[0]}
+                  echo "exit_code=${exit_code}" >> "$GITHUB_OUTPUT"
+                  exit "${exit_code}"
             - name: Post API breakage report to PR
               if: ${{ always() && github.event_name == 'pull_request' }}
               uses: actions/github-script@v7

examples/05_skills_and_plugins/02_loading_plugins/main.py

@@ -1,78 +1,227 @@
-"""Example: Loading Plugins via Conversation
+"""Example: Loading and Managing Plugins
 
-Demonstrates the recommended way to load plugins using the `plugins` parameter
-on Conversation. Plugins bundle skills, hooks, and MCP config together.
+This example demonstrates plugin loading and management in the SDK:
+
+1. Loading plugins from GitHub via Conversation (PluginSource)
+2. Installing plugins to persistent storage (local and GitHub)
+3. Listing, loading, and uninstalling plugins
+
+Plugins bundle skills, hooks, and MCP config together.
+
+Supported plugin sources:
+- Local path: /path/to/plugin
+- GitHub shorthand: github:owner/repo
+- Git URL: https://github.com/owner/repo.git
+- With ref: branch, tag, or commit SHA
+- With repo_path: subdirectory for monorepos
 
 For full documentation, see: https://docs.all-hands.dev/sdk/guides/plugins
 """
 
 import os
-import sys
 import tempfile
 from pathlib import Path
 
 from pydantic import SecretStr
 
 from openhands.sdk import LLM, Agent, Conversation
-from openhands.sdk.plugin import PluginSource
+from openhands.sdk.plugin import (
+    PluginFetchError,
+    PluginSource,
+    install_plugin,
+    list_installed_plugins,
+    load_installed_plugins,
+    uninstall_plugin,
+)
 from openhands.sdk.tool import Tool
 from openhands.tools.file_editor import FileEditorTool
 from openhands.tools.terminal import TerminalTool
 
 
 # Locate example plugin directory
 script_dir = Path(__file__).parent
-plugin_path = script_dir / "example_plugins" / "code-quality"
-
-# Define plugins to load
-# Supported sources: local path, "github:owner/repo", or git URL
-# Optional: ref (branch/tag/commit), repo_path (for monorepos)
-plugins = [
-    PluginSource(source=str(plugin_path)),
-    # PluginSource(source="github:org/security-plugin", ref="v2.0.0"),
-    # PluginSource(source="github:org/monorepo", repo_path="plugins/logging"),
-]
-
-# Check for API key
-api_key = os.getenv("LLM_API_KEY")
-if not api_key:
-    print("Set LLM_API_KEY to run this example")
-    print("EXAMPLE_COST: 0")
-    sys.exit(0)
-
-# Configure LLM and Agent
-model = os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929")
-llm = LLM(
-    usage_id="plugin-demo",
-    model=model,
-    api_key=SecretStr(api_key),
-    base_url=os.getenv("LLM_BASE_URL"),
-)
-agent = Agent(
-    llm=llm, tools=[Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name)]
-)
+local_plugin_path = script_dir / "example_plugins" / "code-quality"
 
-# Create conversation with plugins - skills, MCP config, and hooks are merged
-# Note: Plugins are loaded lazily on first send_message() or run() call
-with tempfile.TemporaryDirectory() as tmpdir:
-    conversation = Conversation(
-        agent=agent,
-        workspace=tmpdir,
-        plugins=plugins,
-    )
 
-    # Test: The "lint" keyword triggers the python-linting skill
-    # This first send_message() call triggers lazy plugin loading
-    conversation.send_message("How do I lint Python code? Brief answer please.")
+def demo_conversation_with_github_plugin(llm: LLM) -> None:
+    """Demo 1: Load plugin from GitHub via Conversation.
+
+    This demonstrates loading a plugin directly from GitHub using PluginSource.
+    The plugin is fetched and loaded lazily when the conversation starts.
+
+    We load the anthropics/skills repository which contains the "document-skills"
+    plugin with skills for pptx, xlsx, docx, and pdf document processing.
+    """
+    print("\n" + "=" * 60)
+    print("DEMO 1: Loading plugin from GitHub via Conversation")
+    print("=" * 60)
+
+    # Load the anthropics/skills repository which contains the document-skills plugin
+    # This plugin bundles multiple document processing skills including pptx
+    plugins = [
+        PluginSource(
+            source="github:anthropics/skills",
+            ref="main",
+        ),
+    ]
 
-    # Verify skills were loaded from the plugin (after lazy loading)
-    skills = (
-        conversation.agent.agent_context.skills
-        if conversation.agent.agent_context
-        else []
+    agent = Agent(
+        llm=llm,
+        tools=[Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name)],
     )
-    print(f"Loaded {len(skills)} skill(s) from plugins")
 
-    conversation.run()
+    with tempfile.TemporaryDirectory() as tmpdir:
+        try:
+            conversation = Conversation(
+                agent=agent,
+                workspace=tmpdir,
+                plugins=plugins,
+            )
+
+            # Verify skills were loaded
+            skills = (
+                conversation.agent.agent_context.skills
+                if conversation.agent.agent_context
+                else []
+            )
+            print(f"✓ Loaded {len(skills)} skill(s) from GitHub plugin")
+            for skill in skills:
+                print(f"  - {skill.name}")
+
+            # Ask a question that uses the pptx skill
+            conversation.send_message(
+                "What's the best way to create a PowerPoint presentation "
+                "programmatically? Check the skill before you answer."
+            )
+
+            conversation.run()
+
+        except PluginFetchError as e:
+            print(f"⚠ Could not fetch from GitHub: {e}")
+            print("  Skipping this demo (network or rate limiting issue)")
+
+
+def demo_install_local_plugin(installed_dir: Path) -> None:
+    """Demo 2: Install a plugin from a local path.
+
+    Useful for development or local-only plugins.
+    """
+    print("\n" + "=" * 60)
+    print("DEMO 2: Installing plugin from local path")
+    print("=" * 60)
+
+    info = install_plugin(source=str(local_plugin_path), installed_dir=installed_dir)
+    print(f"✓ Installed: {info.name} v{info.version}")
+    print(f"  Source: {info.source}")
+    print(f"  Path: {info.install_path}")
+
+
+def demo_install_github_plugin(installed_dir: Path) -> None:
+    """Demo 3: Install a plugin from GitHub to persistent storage.
+
+    Demonstrates loading the anthropics/skills repository which contains
+    multiple document processing skills (pptx, xlsx, docx, pdf).
+    """
+    print("\n" + "=" * 60)
+    print("DEMO 3: Installing plugin from GitHub")
+    print("=" * 60)
+
+    try:
+        # Install the anthropics/skills repository (contains document-skills plugin)
+        info = install_plugin(
+            source="github:anthropics/skills",
+            ref="main",
+            installed_dir=installed_dir,
+        )
+        print(f"✓ Installed: {info.name} v{info.version}")
+        print(f"  Source: {info.source}")
+        print(f"  Resolved ref: {info.resolved_ref}")
+
+        # Show the skills loaded from the plugin
+        plugins = load_installed_plugins(installed_dir=installed_dir)
+        for plugin in plugins:
+            if plugin.name == info.name:
+                skills = plugin.get_all_skills()
+                print(f"  Skills: {len(skills)}")
+                for skill in skills[:5]:  # Show first 5 skills
+                    desc = skill.description or "(no description)"
+                    print(f"    - {skill.name}: {desc[:50]}...")
+                if len(skills) > 5:
+                    print(f"    ... and {len(skills) - 5} more skills")
+
+    except PluginFetchError as e:
+        print(f"⚠ Could not fetch from GitHub: {e}")
+        print("  (Network or rate limiting issue)")
+
+
+def demo_list_and_load_plugins(installed_dir: Path) -> None:
+    """Demo 4: List and load installed plugins."""
+    print("\n" + "=" * 60)
+    print("DEMO 4: List and load installed plugins")
+    print("=" * 60)
+
+    # List installed plugins
+    print("Installed plugins:")
+    for info in list_installed_plugins(installed_dir=installed_dir):
+        print(f"  - {info.name} v{info.version} ({info.source})")
+
+    # Load plugins as Plugin objects
+    plugins = load_installed_plugins(installed_dir=installed_dir)
+    print(f"\nLoaded {len(plugins)} plugin(s):")
+    for plugin in plugins:
+        skills = plugin.get_all_skills()
+        print(f"  - {plugin.name}: {len(skills)} skill(s)")
+
+
+def demo_uninstall_plugins(installed_dir: Path) -> None:
+    """Demo 5: Uninstall plugins."""
+    print("\n" + "=" * 60)
+    print("DEMO 5: Uninstalling plugins")
+    print("=" * 60)
+
+    for info in list_installed_plugins(installed_dir=installed_dir):
+        uninstall_plugin(info.name, installed_dir=installed_dir)
+        print(f"✓ Uninstalled: {info.name}")
+
+    remaining = list_installed_plugins(installed_dir=installed_dir)
+    print(f"\nRemaining plugins: {len(remaining)}")
+
+
+# Main execution
+if __name__ == "__main__":
+    api_key = os.getenv("LLM_API_KEY")
+    if not api_key:
+        print("Set LLM_API_KEY to run the full example")
+        print("Running install/uninstall demos only...")
+        llm = None
+    else:
+        model = os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929")
+        llm = LLM(
+            usage_id="plugin-demo",
+            model=model,
+            api_key=SecretStr(api_key),
+            base_url=os.getenv("LLM_BASE_URL"),
+        )
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        installed_dir = Path(tmpdir) / "installed"
+        installed_dir.mkdir()
+
+        # Demo 1: Conversation with GitHub plugin (requires LLM)
+        if llm:
+            demo_conversation_with_github_plugin(llm)
+
+        # Demo 2-5: Plugin management (no LLM required)
+        demo_install_local_plugin(installed_dir)
+        demo_install_github_plugin(installed_dir)
+        demo_list_and_load_plugins(installed_dir)
+        demo_uninstall_plugins(installed_dir)
+
+    print("\n" + "=" * 60)
+    print("EXAMPLE COMPLETED SUCCESSFULLY")
+    print("=" * 60)
 
-    print(f"EXAMPLE_COST: {llm.metrics.accumulated_cost:.4f}")
+    if llm:
+        print(f"EXAMPLE_COST: {llm.metrics.accumulated_cost:.4f}")
+    else:
+        print("EXAMPLE_COST: 0")

openhands-sdk/openhands/sdk/conversation/state.py

@@ -14,7 +14,12 @@
 from openhands.sdk.conversation.persistence_const import BASE_STATE, EVENTS_DIR
 from openhands.sdk.conversation.secret_registry import SecretRegistry
 from openhands.sdk.conversation.types import ConversationCallbackType, ConversationID
-from openhands.sdk.event import ActionEvent, ObservationEvent, UserRejectObservation
+from openhands.sdk.event import (
+    ActionEvent,
+    AgentErrorEvent,
+    ObservationEvent,
+    UserRejectObservation,
+)
 from openhands.sdk.event.base import Event
 from openhands.sdk.event.types import EventID
 from openhands.sdk.io import FileStore, InMemoryFileStore, LocalFileStore
@@ -437,8 +442,12 @@ def get_unmatched_actions(events: Sequence[Event]) -> list[ActionEvent]:
         """Find actions in the event history that don't have matching observations.
 
         This method identifies ActionEvents that don't have corresponding
-        ObservationEvents or UserRejectObservations, which typically indicates
-        actions that are pending confirmation or execution.
+        ObservationEvents, UserRejectObservations, or AgentErrorEvents,
+        which typically indicates actions that are pending confirmation or execution.
+
+        Note: AgentErrorEvent is matched by tool_call_id (not action_id) because
+        it doesn't have an action_id field. This is important for crash recovery
+        scenarios where an error event is emitted after a server restart.
 
         Args:
             events: List of events to search through
@@ -447,15 +456,24 @@ def get_unmatched_actions(events: Sequence[Event]) -> list[ActionEvent]:
             List of ActionEvent objects that don't have corresponding observations,
             in chronological order
         """
-        observed_action_ids = set()
+        observed_action_ids: set[EventID] = set()
+        observed_tool_call_ids: set[str] = set()
         unmatched_actions = []
         # Search in reverse - recent events are more likely to be unmatched
         for event in reversed(events):
             if isinstance(event, (ObservationEvent, UserRejectObservation)):
                 observed_action_ids.add(event.action_id)
+            elif isinstance(event, AgentErrorEvent):
+                # AgentErrorEvent doesn't have action_id, match by tool_call_id
+                observed_tool_call_ids.add(event.tool_call_id)
             elif isinstance(event, ActionEvent):
                 # Only executable actions (validated) are considered pending
-                if event.action is not None and event.id not in observed_action_ids:
+                # Check both action_id and tool_call_id for matching
+                if (
+                    event.action is not None
+                    and event.id not in observed_action_ids
+                    and event.tool_call_id not in observed_tool_call_ids
+                ):
                     # Insert at beginning to maintain chronological order in result
                     unmatched_actions.insert(0, event)