openhands-sdk 1.9.0__py3-none-any.whl → 1.10.0__py3-none-any.whl

openhands/sdk/conversation/conversation.py

@@ -16,6 +16,7 @@ from openhands.sdk.conversation.visualizer import (
 )
 from openhands.sdk.hooks import HookConfig
 from openhands.sdk.logger import get_logger
+from openhands.sdk.plugin import PluginSource
 from openhands.sdk.secret import SecretValue
 from openhands.sdk.workspace import LocalWorkspace, RemoteWorkspace
 
@@ -40,9 +41,14 @@ class Conversation:
 
     Example:
         >>> from openhands.sdk import LLM, Agent, Conversation
+        >>> from openhands.sdk.plugin import PluginSource
         >>> llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("key"))
         >>> agent = Agent(llm=llm, tools=[])
-        >>> conversation = Conversation(agent=agent, workspace="./workspace")
+        >>> conversation = Conversation(
+        ...     agent=agent,
+        ...     workspace="./workspace",
+        ...     plugins=[PluginSource(source="github:org/security-plugin", ref="v1.0")],
+        ... )
         >>> conversation.send_message("Hello!")
         >>> conversation.run()
     """
@@ -53,6 +59,7 @@ class Conversation:
         agent: AgentBase,
         *,
         workspace: str | Path | LocalWorkspace = "workspace/project",
+        plugins: list[PluginSource] | None = None,
         persistence_dir: str | Path | None = None,
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
@@ -75,6 +82,7 @@ class Conversation:
         agent: AgentBase,
         *,
         workspace: RemoteWorkspace,
+        plugins: list[PluginSource] | None = None,
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
@@ -95,6 +103,7 @@ class Conversation:
         agent: AgentBase,
         *,
         workspace: str | Path | LocalWorkspace | RemoteWorkspace = "workspace/project",
+        plugins: list[PluginSource] | None = None,
         persistence_dir: str | Path | None = None,
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
@@ -116,14 +125,14 @@ class Conversation:
         )
 
         if isinstance(workspace, RemoteWorkspace):
-            # For RemoteConversation, persistence_dir should not be used
-            # Only check if it was explicitly set to something other than the default
+            # For RemoteConversation, persistence_dir should not be used.
             if persistence_dir is not None:
                 raise ValueError(
                     "persistence_dir should not be set when using RemoteConversation"
                 )
             return RemoteConversation(
                 agent=agent,
+                plugins=plugins,
                 conversation_id=conversation_id,
                 callbacks=callbacks,
                 token_callbacks=token_callbacks,
@@ -138,6 +147,7 @@ class Conversation:
 
         return LocalConversation(
             agent=agent,
+            plugins=plugins,
             conversation_id=conversation_id,
             callbacks=callbacks,
             token_callbacks=token_callbacks,

openhands/sdk/conversation/exceptions.py

@@ -4,6 +4,24 @@ from openhands.sdk.conversation.types import ConversationID
 ISSUE_URL = "https://github.com/OpenHands/software-agent-sdk/issues/new"
 
 
+class WebSocketConnectionError(RuntimeError):
+    """Raised when WebSocket connection fails to establish within the timeout."""
+
+    def __init__(
+        self,
+        conversation_id: ConversationID,
+        timeout: float,
+        message: str | None = None,
+    ) -> None:
+        self.conversation_id = conversation_id
+        self.timeout = timeout
+        default_msg = (
+            f"WebSocket subscription did not complete within {timeout} seconds "
+            f"for conversation {conversation_id}. Events may be missed."
+        )
+        super().__init__(message or default_msg)
+
+
 class ConversationRunError(RuntimeError):
     """Raised when a conversation run fails.
 

openhands/sdk/conversation/impl/local_conversation.py

@@ -36,6 +36,12 @@ from openhands.sdk.llm import LLM, Message, TextContent
 from openhands.sdk.llm.llm_registry import LLMRegistry
 from openhands.sdk.logger import get_logger
 from openhands.sdk.observability.laminar import observe
+from openhands.sdk.plugin import (
+    Plugin,
+    PluginSource,
+    ResolvedPluginSource,
+    fetch_plugin_with_resolution,
+)
 from openhands.sdk.security.analyzer import SecurityAnalyzerBase
 from openhands.sdk.security.confirmation_policy import (
     ConfirmationPolicyBase,
@@ -59,11 +65,17 @@ class LocalConversation(BaseConversation):
     llm_registry: LLMRegistry
     _cleanup_initiated: bool
     _hook_processor: HookEventProcessor | None
+    # Plugin lazy loading state
+    _plugin_specs: list[PluginSource] | None
+    _resolved_plugins: list[ResolvedPluginSource] | None
+    _plugins_loaded: bool
+    _pending_hook_config: HookConfig | None  # Hook config to combine with plugin hooks
 
     def __init__(
         self,
         agent: AgentBase,
         workspace: str | Path | LocalWorkspace,
+        plugins: list[PluginSource] | None = None,
         persistence_dir: str | Path | None = None,
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
@@ -84,9 +96,15 @@ class LocalConversation(BaseConversation):
         """Initialize the conversation.
 
         Args:
-            agent: The agent to use for the conversation
+            agent: The agent to use for the conversation.
             workspace: Working directory for agent operations and tool execution.
                 Can be a string path, Path object, or LocalWorkspace instance.
+            plugins: Optional list of plugins to load. Each plugin is specified
+                with a source (github:owner/repo, git URL, or local path),
+                optional ref (branch/tag/commit), and optional repo_path for
+                monorepos. Plugins are loaded in order with these merge
+                semantics: skills override by name (last wins), MCP config
+                override by key (last wins), hooks concatenate (all run).
             persistence_dir: Directory for persisting conversation state and events.
                 Can be a string path or Path object.
             conversation_id: Optional ID for the conversation. If provided, will
@@ -94,7 +112,8 @@ class LocalConversation(BaseConversation):
                       suffix their persistent filestore with this ID.
             callbacks: Optional list of callback functions to handle events
             token_callbacks: Optional list of callbacks invoked for streaming deltas
-            hook_config: Optional hook configuration to auto-wire session hooks
+            hook_config: Optional hook configuration to auto-wire session hooks.
+                If plugins are loaded, their hooks are combined with this config.
             max_iteration_per_run: Maximum number of iterations per run
             visualizer: Visualization configuration. Can be:
                        - ConversationVisualizerBase subclass: Class to instantiate
@@ -117,6 +136,14 @@ class LocalConversation(BaseConversation):
         # initialized instances during interpreter shutdown.
         self._cleanup_initiated = False
 
+        # Store plugin specs for lazy loading (no IO in constructor)
+        # Plugins will be loaded on first run() or send_message() call
+        self._plugin_specs = plugins
+        self._resolved_plugins = None
+        self._plugins_loaded = False
+        self._pending_hook_config = hook_config  # Will be combined with plugin hooks
+        self._agent_ready = False  # Agent initialized lazily after plugins loaded
+
         self.agent = agent
         if isinstance(workspace, (str, Path)):
             # LocalWorkspace accepts both str and Path via BeforeValidator
@@ -172,18 +199,13 @@ class LocalConversation(BaseConversation):
 
         # Compose the base callback chain (visualizer -> user callbacks -> default)
         base_callback = BaseConversation.compose_callbacks(composed_list)
+        self._base_callback = base_callback  # Store for _ensure_plugins_loaded
 
-        # If hooks configured, wrap with hook processor that forwards to base chain
+        # Defer all hook setup to _ensure_plugins_loaded() for consistency
+        # This runs on first run()/send_message() call and handles both
+        # explicit hooks and plugin hooks in one place
         self._hook_processor = None
-        if hook_config is not None:
-            self._hook_processor, self._on_event = create_hook_callback(
-                hook_config=hook_config,
-                working_dir=str(self.workspace.working_dir),
-                session_id=str(desired_id),
-                original_callback=base_callback,
-            )
-        else:
-            self._on_event = base_callback
+        self._on_event = base_callback
         self._on_token = (
             BaseConversation.compose_callbacks(token_callbacks)
             if token_callbacks
@@ -208,18 +230,9 @@ class LocalConversation(BaseConversation):
         else:
             self._stuck_detector = None
 
-        if self._hook_processor is not None:
-            self._hook_processor.set_conversation_state(self._state)
-            self._hook_processor.run_session_start()
-
-        with self._state:
-            self.agent.init_state(self._state, on_event=self._on_event)
-
-        # Register existing llms in agent
+        # Agent initialization is deferred to _ensure_agent_ready() for lazy loading
+        # This ensures plugins are loaded before agent initialization
         self.llm_registry = LLMRegistry()
-        self.llm_registry.subscribe(self._state.stats.register_llm)
-        for llm in list(self.agent.get_all_llms()):
-            self.llm_registry.add(llm)
 
         # Initialize secrets if provided
         if secrets:
@@ -255,6 +268,154 @@ class LocalConversation(BaseConversation):
         """Get the stuck detector instance if enabled."""
         return self._stuck_detector
 
+    @property
+    def resolved_plugins(self) -> list[ResolvedPluginSource] | None:
+        """Get the resolved plugin sources after plugins are loaded.
+
+        Returns None if plugins haven't been loaded yet, or if no plugins
+        were specified. Use this for persistence to ensure conversation
+        resume uses the exact same plugin versions.
+        """
+        return self._resolved_plugins
+
+    def _ensure_plugins_loaded(self) -> None:
+        """Lazy load plugins and set up hooks on first use.
+
+        This method is called automatically before run() and send_message().
+        It handles both plugin loading and hook initialization in one place
+        for consistency.
+
+        The method:
+        1. Fetches plugins from their sources (network IO for remote sources)
+        2. Resolves refs to commit SHAs for deterministic resume
+        3. Loads plugin contents (skills, MCP config, hooks)
+        4. Merges plugin contents into the agent
+        5. Sets up hook processor with combined hooks (explicit + plugin)
+        6. Runs session_start hooks
+        """
+        if self._plugins_loaded:
+            return
+
+        all_plugin_hooks: list[HookConfig] = []
+
+        # Load plugins if specified
+        if self._plugin_specs:
+            logger.info(f"Loading {len(self._plugin_specs)} plugin(s)...")
+            self._resolved_plugins = []
+
+            # Start with agent's existing context and MCP config
+            merged_context = self.agent.agent_context
+            merged_mcp = dict(self.agent.mcp_config) if self.agent.mcp_config else {}
+
+            for spec in self._plugin_specs:
+                # Fetch plugin and get resolved commit SHA
+                path, resolved_ref = fetch_plugin_with_resolution(
+                    source=spec.source,
+                    ref=spec.ref,
+                    repo_path=spec.repo_path,
+                )
+
+                # Store resolved ref for persistence
+                resolved = ResolvedPluginSource.from_plugin_source(spec, resolved_ref)
+                self._resolved_plugins.append(resolved)
+
+                # Load the plugin
+                plugin = Plugin.load(path)
+                logger.debug(
+                    f"Loaded plugin '{plugin.manifest.name}' from {spec.source}"
+                    + (f" @ {resolved_ref[:8]}" if resolved_ref else "")
+                )
+
+                # Merge plugin contents
+                merged_context = plugin.add_skills_to(merged_context)
+                merged_mcp = plugin.add_mcp_config_to(merged_mcp)
+
+                # Collect hooks
+                if plugin.hooks and not plugin.hooks.is_empty():
+                    all_plugin_hooks.append(plugin.hooks)
+
+            # Update agent with merged content
+            self.agent = self.agent.model_copy(
+                update={
+                    "agent_context": merged_context,
+                    "mcp_config": merged_mcp,
+                }
+            )
+
+            # Also update the agent in _state so API responses reflect loaded plugins
+            with self._state:
+                self._state.agent = self.agent
+
+            logger.info(f"Loaded {len(self._plugin_specs)} plugin(s) via Conversation")
+
+        # Combine explicit hook_config with plugin hooks
+        # Explicit hooks run first (before plugin hooks)
+        final_hook_config = self._pending_hook_config
+        if all_plugin_hooks:
+            plugin_hooks = HookConfig.merge(all_plugin_hooks)
+            if plugin_hooks is not None:
+                if final_hook_config is not None:
+                    final_hook_config = HookConfig.merge(
+                        [final_hook_config, plugin_hooks]
+                    )
+                else:
+                    final_hook_config = plugin_hooks
+
+        # Set up hook processor with the combined config
+        if final_hook_config is not None:
+            self._hook_processor, self._on_event = create_hook_callback(
+                hook_config=final_hook_config,
+                working_dir=str(self.workspace.working_dir),
+                session_id=str(self._state.id),
+                original_callback=self._base_callback,
+            )
+            self._hook_processor.set_conversation_state(self._state)
+            self._hook_processor.run_session_start()
+
+        self._plugins_loaded = True
+
+    def _ensure_agent_ready(self) -> None:
+        """Ensure agent is fully initialized with plugins loaded.
+
+        This method combines plugin loading and agent initialization to ensure
+        the agent is initialized exactly once with complete configuration.
+
+        Called lazily on first send_message() or run() to:
+        1. Load plugins (if specified)
+        2. Initialize agent with complete plugin config and hooks
+        3. Register LLMs in the registry
+
+        This preserves the design principle that constructors should not perform
+        I/O or error-prone operations, while eliminating double initialization.
+
+        Thread-safe: Uses state lock to prevent concurrent initialization.
+        """
+        # Fast path: if already initialized, skip lock acquisition entirely.
+        # This is crucial for concurrent send_message() calls during run(),
+        # which holds the state lock during agent.step(). Without this check,
+        # send_message() would block waiting for the lock even though no
+        # initialization is needed.
+        if self._agent_ready:
+            return
+
+        with self._state:
+            # Re-check after acquiring lock in case another thread initialized
+            if self._agent_ready:
+                return
+
+            # Load plugins first (merges skills, MCP config, hooks)
+            self._ensure_plugins_loaded()
+
+            # Initialize agent with complete configuration
+            self.agent.init_state(self._state, on_event=self._on_event)
+
+            # Register LLMs in the registry (still holding lock)
+            self.llm_registry.subscribe(self._state.stats.register_llm)
+            for llm in list(self.agent.get_all_llms()):
+                self.llm_registry.add(llm)
+
+            self._agent_ready = True
+
     @observe(name="conversation.send_message")
     def send_message(self, message: str | Message, sender: str | None = None) -> None:
         """Send a message to the agent.
@@ -267,6 +428,9 @@ class LocalConversation(BaseConversation):
                    one agent delegates to another, the sender can be set to
                    identify which agent is sending the message.
         """
+        # Ensure agent is fully initialized (loads plugins and initializes agent)
+        self._ensure_agent_ready()
+
         # Convert string to Message if needed
         if isinstance(message, str):
             message = Message(role="user", content=[TextContent(text=message)])
@@ -325,6 +489,8 @@ class LocalConversation(BaseConversation):
 
         Can be paused between steps
         """
+        # Ensure agent is fully initialized (loads plugins and initializes agent)
+        self._ensure_agent_ready()
 
         with self._state:
             if self._state.execution_status in [
@@ -572,6 +738,9 @@ class LocalConversation(BaseConversation):
         Returns:
             A string response from the agent
         """
+        # Ensure agent is initialized (needs tools_map)
+        self._ensure_agent_ready()
+
         # Import here to avoid circular imports
         from openhands.sdk.agent.utils import make_llm_completion, prepare_llm_messages
 

openhands/sdk/conversation/impl/remote_conversation.py

@@ -16,7 +16,10 @@ from openhands.sdk.agent.base import AgentBase
 from openhands.sdk.conversation.base import BaseConversation, ConversationStateProtocol
 from openhands.sdk.conversation.conversation_stats import ConversationStats
 from openhands.sdk.conversation.events_list_base import EventsListBase
-from openhands.sdk.conversation.exceptions import ConversationRunError
+from openhands.sdk.conversation.exceptions import (
+    ConversationRunError,
+    WebSocketConnectionError,
+)
 from openhands.sdk.conversation.secret_registry import SecretValue
 from openhands.sdk.conversation.state import ConversationExecutionStatus
 from openhands.sdk.conversation.types import (
@@ -95,6 +98,7 @@ class WebSocketCallbackClient:
     api_key: str | None
     _thread: threading.Thread | None
     _stop: threading.Event
+    _ready: threading.Event
 
     def __init__(
         self,
@@ -109,6 +113,7 @@ class WebSocketCallbackClient:
         self.api_key = api_key
         self._thread = None
         self._stop = threading.Event()
+        self._ready = threading.Event()
 
     def start(self) -> None:
         if self._thread:
@@ -124,6 +129,38 @@ class WebSocketCallbackClient:
         self._thread.join(timeout=5)
         self._thread = None
 
+    def wait_until_ready(self, timeout: float | None = None) -> bool:
+        """Wait for WebSocket subscription to complete.
+
+        The server sends a ConversationStateUpdateEvent immediately after
+        subscription completes. This method blocks until that event is received,
+        the client is stopped, or the timeout expires.
+
+        Args:
+            timeout: Maximum time to wait in seconds. None means wait forever.
+
+        Returns:
+            True if the WebSocket is ready, False if stopped or timeout expired.
+        """
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            # Calculate remaining timeout
+            if deadline is not None:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return False
+                wait_timeout = min(0.05, remaining)
+            else:
+                wait_timeout = 0.05
+
+            # Wait efficiently using Event.wait() instead of sleep
+            if self._ready.wait(timeout=wait_timeout):
+                return True
+
+            # Check if stopped
+            if self._stop.is_set():
+                return False
+
     def _run(self) -> None:
         try:
             asyncio.run(self._client_loop())
@@ -154,6 +191,15 @@ class WebSocketCallbackClient:
                             break
                         try:
                             event = Event.model_validate(json.loads(message))
+
+                            # Set ready on first ConversationStateUpdateEvent
+                            # The server sends this immediately after subscription
+                            if (
+                                isinstance(event, ConversationStateUpdateEvent)
+                                and not self._ready.is_set()
+                            ):
+                                self._ready.set()
+
                             self.callback(event)
                         except Exception:
                             logger.exception(
@@ -219,6 +265,73 @@ class RemoteEventsList(EventsListBase):
         self._cached_event_ids.update(e.id for e in events)
         logger.debug(f"Full sync completed, {len(events)} events cached")
 
+    def reconcile(self) -> int:
+        """Reconcile local cache with server by fetching and merging events.
+
+        This method fetches all events from the server and merges them with
+        the local cache, deduplicating by event ID. This ensures no events
+        are missed due to race conditions between REST sync and WebSocket
+        subscription.
+
+        Returns:
+            Number of new events added during reconciliation.
+        """
+        logger.debug(
+            f"Performing reconciliation sync for conversation {self._conversation_id}"
+        )
+
+        events = []
+        page_id = None
+
+        while True:
+            params = {"limit": 100}
+            if page_id:
+                params["page_id"] = page_id
+
+            try:
+                resp = _send_request(
+                    self._client,
+                    "GET",
+                    f"/api/conversations/{self._conversation_id}/events/search",
+                    params=params,
+                )
+                data = resp.json()
+            except Exception as e:
+                logger.warning(f"Failed to fetch events during reconciliation: {e}")
+                break  # Return partial results rather than failing completely
+
+            events.extend([Event.model_validate(item) for item in data["items"]])
+
+            if not data.get("next_page_id"):
+                break
+            page_id = data["next_page_id"]
+
+        # Merge events into cache, acquiring lock once for all events
+        added_count = 0
+        with self._lock:
+            for event in events:
+                if event.id not in self._cached_event_ids:
+                    self._add_event_unsafe(event)
+                    added_count += 1
+
+        logger.debug(
+            f"Reconciliation completed, {added_count} new events added "
+            f"(total: {len(self._cached_events)})"
+        )
+        return added_count
+
+    def _add_event_unsafe(self, event: Event) -> None:
+        """Add event to cache without acquiring lock (caller must hold lock)."""
+        # Use bisect with key function for O(log N) insertion
+        # This ensures events are always ordered correctly even if
+        # WebSocket delivers them out of order
+        insert_pos = bisect.bisect_right(
+            self._cached_events, event.timestamp, key=lambda e: e.timestamp
+        )
+        self._cached_events.insert(insert_pos, event)
+        self._cached_event_ids.add(event.id)
+        logger.debug(f"Added event {event.id} to local cache at position {insert_pos}")
+
     def add_event(self, event: Event) -> None:
         """Add a new event to the local cache (called by WebSocket callback).
 
@@ -228,17 +341,7 @@ class RemoteEventsList(EventsListBase):
         with self._lock:
             # Check if event already exists to avoid duplicates
             if event.id not in self._cached_event_ids:
-                # Use bisect with key function for O(log N) insertion
-                # This ensures events are always ordered correctly even if
-                # WebSocket delivers them out of order
-                insert_pos = bisect.bisect_right(
-                    self._cached_events, event.timestamp, key=lambda e: e.timestamp
-                )
-                self._cached_events.insert(insert_pos, event)
-                self._cached_event_ids.add(event.id)
-                logger.debug(
-                    f"Added event {event.id} to local cache at position {insert_pos}"
-                )
+                self._add_event_unsafe(event)
 
     def append(self, event: Event) -> None:
         """Add a new event to the list (for compatibility with EventLog interface)."""
@@ -457,6 +560,7 @@ class RemoteConversation(BaseConversation):
         self,
         agent: AgentBase,
         workspace: RemoteWorkspace,
+        plugins: list | None = None,
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
         max_iteration_per_run: int = 500,
@@ -476,6 +580,8 @@ class RemoteConversation(BaseConversation):
         Args:
             agent: Agent configuration (will be sent to the server)
             workspace: The working directory for agent operations and tool execution.
+            plugins: Optional list of plugins to load on the server. Each plugin
+                    is a PluginSource specifying source, ref, and repo_path.
             conversation_id: Optional existing conversation id to attach to
             callbacks: Optional callbacks to receive events (not yet streamed)
             max_iteration_per_run: Max iterations configured on server
@@ -537,6 +643,8 @@ class RemoteConversation(BaseConversation):
                 ).model_dump(),
                 # Include tool module qualnames for dynamic registration on server
                 "tool_module_qualnames": tool_qualnames,
+                # Include plugins to load on server
+                "plugins": [p.model_dump() for p in plugins] if plugins else None,
             }
             if stuck_detection_thresholds is not None:
                 # Convert to StuckDetectionThresholds if dict, then serialize
@@ -610,6 +718,27 @@ class RemoteConversation(BaseConversation):
         )
         self._ws_client.start()
 
+        # Wait for WebSocket subscription to complete before allowing operations.
+        # This ensures events emitted during send_message() are not missed.
+        # The server sends a ConversationStateUpdateEvent after subscription.
+        ws_timeout = 30.0
+        if not self._ws_client.wait_until_ready(timeout=ws_timeout):
+            try:
+                self._ws_client.stop()
+            except Exception:
+                pass
+            finally:
+                self._ws_client = None
+            raise WebSocketConnectionError(
+                conversation_id=self._id,
+                timeout=ws_timeout,
+            )
+
+        # Reconcile events after WebSocket is ready to catch any events that
+        # were emitted between the initial REST sync and WebSocket subscription.
+        # This is the "reconciliation" part of the subscription handshake.
+        self._state.events.reconcile()
+
         # Initialize secrets if provided
         if secrets:
             # Convert dict[str, str] to dict[str, SecretValue]

openhands/sdk/critic/impl/api/critic.py

@@ -49,13 +49,16 @@ class APIBasedCritic(CriticBase, CriticClient):
         messages = LLMConvertibleEvent.events_to_messages(llm_convertible_events)
 
         # Serialize messages to dicts for API
-        for message in messages:
-            message.cache_enabled = False
-            message.vision_enabled = False  # Critic does not support vision currently
-            message.function_calling_enabled = True
-            message.force_string_serializer = False
-            message.send_reasoning_content = False
-        formatted_messages = [message.to_chat_dict() for message in messages]
+        formatted_messages = [
+            message.to_chat_dict(
+                cache_enabled=False,
+                vision_enabled=False,  # Critic does not support vision currently
+                function_calling_enabled=True,
+                force_string_serializer=False,
+                send_reasoning_content=False,
+            )
+            for message in messages
+        ]
 
         # Convert ToolDefinition objects to ChatCompletionToolParam format
         tools_for_api = [tool.to_openai_tool() for tool in tools]