Skip to content

Self-improving AI Employees for everyone

131 KB
Raw Blame
"""AI service backed by the native provider SDK layer.

Every in-process and durable agent execution goes through
:mod:`services.agent_runtime` and :mod:`services.llm`.
"""

from __future__ import annotations

import time
from dataclasses import dataclass
from datetime import datetime
from typing import Dict, Any, List, Optional, Type, TYPE_CHECKING

import json

# ``NodeUserError`` is the framework's "user-correctable, no-traceback"
# sentinel used to surface typed SDK errors cleanly through
# ``BaseNode.execute()``.
from services.plugin import NodeUserError
from services.agent_bindings import delegation_roster, is_runtime_tool, node_tools, unique_node_bindings, rebind_allowed, extend_runtime_graph
from services.tool_identity import DuplicateToolNameError, ensure_unique_tool_names

if TYPE_CHECKING:
    from pydantic import BaseModel, Field, create_model  # noqa: F401


# Backwards-compat shim (PEP 562 module-level ``__getattr__``) for code that
# historically read ``PROVIDER_CONFIGS`` as a module-level constant here. It
# resolves to the native config map.
def __getattr__(name: str):
    if name == "PROVIDER_CONFIGS":
        return NATIVE_PROVIDER_CONFIGS
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")


from core.config import Settings
from core.logging import get_logger, log_execution_time, log_api_call
from services.auth import AuthService

logger = get_logger(__name__)

# ---------------------------------------------------------------------------
# Native LLM provider/runtime imports for every new chat and agent execution
# ---------------------------------------------------------------------------
# ``ChatUnifier`` (injected via DI) owns provider dispatch. The legacy
# ``services.llm.factory`` module (``create_provider`` /
# ``is_native_provider``) was removed after the unifier cutover.
from services.llm.protocol import (
    Message as NativeMessage,
    ThinkingConfig as NativeThinkingConfig,
    LLMResponse,
    ToolDef,
    Usage,
)
from services.llm.config import (
    PROVIDER_CONFIGS as NATIVE_PROVIDER_CONFIGS,
    detect_provider_from_model as native_detect_provider_from_model,
    get_default_model as native_get_default_model,
    get_default_model_async as native_get_default_model_async,
    is_model_valid_for_provider as native_is_model_valid_for_provider,
    resolve_max_tokens as native_resolve_max_tokens,
    resolve_temperature as native_resolve_temperature,
)
from services.agent_runtime import AgentToolSpec, run_native_agent_loop
from services.runtime_tool_context import native_observer_options, bind_runtime_context
from services.tool_output import resolve_tool_output_limit


# =============================================================================
# MARKDOWN MEMORY HELPERS - Parse/append/trim conversation markdown
# =============================================================================


_USAGE_FIELDS = (
    "input_tokens",
    "output_tokens",
    "total_tokens",
    "cache_creation_tokens",
    "cache_read_tokens",
    "reasoning_tokens",
)


def _coerce_native_usage(value: Any) -> Usage:
    if isinstance(value, Usage):
        return value
    if isinstance(value, dict):
        return Usage(
            **{
                key: value.get(key, 0)
                for key in _USAGE_FIELDS
            }
        )
    return Usage()


def _accumulate_compaction_usage(
    final_state: Dict[str, Any],
    compaction_result: Optional[Dict[str, Any]],
) -> None:
    """Add summarizer billing to execution usage, not context thresholds."""

    if not compaction_result or not compaction_result.get("usage"):
        return
    final_state["usage"] = _coerce_native_usage(
        final_state.get("usage")
    ) + _coerce_native_usage(compaction_result["usage"])


def _parse_memory_markdown(content: str) -> List[NativeMessage]:
    """Compatibility wrapper for the native Markdown memory parser."""

    from services.memory.markdown import parse_memory_markdown

    return parse_memory_markdown(content)


# Compatibility alias for callers that clear the historical cache directly.
# The implementation and ownership now live in ``services.memory.vector_store``.
from services.memory.vector_store import (
    _memory_vector_stores as _memory_vector_stores,
    get_memory_vector_store as _get_memory_vector_store,
)


async def _get_configured_memory_vector_store(
    session_id: str,
    memory_data: Dict[str, Any],
    auth_service: Any,
):
    """Resolve one memory node's async native embedding store."""

    return await _get_memory_vector_store(
        session_id,
        provider=memory_data.get("embedding_provider", "huggingface"),
        model=memory_data.get("embedding_model"),
        endpoint=memory_data.get("embedding_endpoint"),
        auth_service=auth_service,
    )


# =============================================================================
# AI PROVIDER REGISTRY - Single source of truth for provider configurations
# =============================================================================


# Compatibility export. Native configuration is the single source of truth.
ThinkingConfig = NativeThinkingConfig


# =============================================================================
# LLM DEFAULTS CONFIGURATION - Load from config/llm_defaults.json
# =============================================================================


def _load_llm_defaults() -> Dict[str, Any]:
    """Load LLM provider defaults from config/llm_defaults.json."""
    from pathlib import Path

    config_path = Path(__file__).parent.parent / "config" / "llm_defaults.json"
    try:
        with open(config_path, encoding="utf-8") as f:
            return json.load(f)
    except Exception as e:
        logger.warning(f"Could not load llm_defaults.json: {e}")
        return {"providers": {}}


_LLM_DEFAULTS = _load_llm_defaults()


def _get_default_model(provider: str, fallback: str) -> str:
    """Get default model for a provider from config, with fallback."""
    providers = _LLM_DEFAULTS.get("providers", {})
    return providers.get(provider, {}).get("default_model", fallback)


def _require_saved_endpoint(provider: str) -> None:
    """Called when no key was injected: a named endpoint is unsaved, not keyless.

    Saving an endpoint always stores a key (the user's or the declared
    placeholder), so a missing key means the endpoint was removed or never
    chosen. Say that, as a user-correctable error, instead of "API key is
    required". Any other provider falls through to the caller's own error.
    """
    from services.llm.endpoints import unconfigured_endpoint_message

    message = unconfigured_endpoint_message(provider)
    if message:
        raise NodeUserError(message)


def _resolve_max_tokens(flattened: dict, model: str, provider: str) -> int:
    """Resolve max_tokens: user param (clamped to model max) -> model max.

    Delegates to ``services/llm/config.py::resolve_max_tokens`` so the
    agent paths (execute_agent / execute_chat_agent / F4.B
    prepare_agent_payload) and the native chat path agree: when the user
    doesn't set max_tokens, the model's full supported output budget is
    used (registry -> llm_defaults fallback), never an artificial
    provider-wide floor.
    """
    return native_resolve_max_tokens(flattened, model, provider)


def _resolve_temperature(flattened: dict, model: str, provider: str, thinking_enabled: bool) -> float:
    """Resolve temperature through the native provider configuration."""
    return native_resolve_temperature(
        flattened,
        model,
        provider,
        thinking_enabled,
    )


def detect_provider_from_model(model: str) -> str:
    """Detect AI provider from model name using registry patterns."""
    return native_detect_provider_from_model(model)


def is_model_valid_for_provider(model: str, provider: str) -> bool:
    """Check if model name matches the provider's patterns.

    Pattern-matching is meaningful for cloud providers — `gpt-*` is OpenAI,
    `claude-*` is Anthropic, etc. — and the check guards against picking
    a model from one provider's dropdown after switching to another.

    For "open-world" providers (OpenRouter proxy, local Ollama / LM Studio
    servers) the model namespace is whatever the user has installed:
    `llama-3.2`, `qwen2.5-coder`, `phi-3-mini`, custom GGUF files, etc.
    None of those contain the literal substrings `ollama` or `lmstudio`,
    so applying the cloud-style filter produces a false negative on every
    valid local model — the call site then "uses default" which for a
    local provider is the SAME model name, emitting a confusing
    "invalid ... using default: <same name>" log line. Treat all three
    as always-valid; the local-server SDK will reject genuinely missing
    models at request time with a clear 404.
    """
    return native_is_model_valid_for_provider(model, provider)


def get_default_model(provider: str) -> str:
    """Get default model for a provider from JSON config."""
    return native_get_default_model(provider)


async def get_default_model_async(provider: str, database) -> str:
    """Get default model for a provider, checking database first then JSON config.

    Priority: database user setting > JSON config file > fallback
    """
    return await native_get_default_model_async(provider, database)


# =============================================================================
# MESSAGE FILTERING UTILITIES - Standardized for all providers
# =============================================================================


def is_valid_message_content(content: Any) -> bool:
    """Check if message content is valid (non-empty) for API calls.

    This is a standardized utility for validating message content before:
    - Saving to conversation memory
    - Including in API requests
    - Building message history

    Args:
        content: The message content to validate (str, list, or other)

    Returns:
        True if content is valid and non-empty, False otherwise
    """
    if content is None:
        return False

    # Handle list content format (Gemini returns [{"type": "text", "text": "..."}])
    if isinstance(content, list):
        return any(
            (isinstance(block, dict) and block.get("text", "").strip()) or (isinstance(block, str) and block.strip()) for block in content
        )

    # Handle string content (most common)
    if isinstance(content, str):
        return bool(content.strip())

    # Other truthy content types
    return bool(content)


def _build_skill_system_prompt(skill_data: List[Dict[str, Any]], log_prefix: str = "[Agent]") -> tuple:
    """Build skill injection text for the system message.

    Personality skills (names ending in '-personality') get their FULL SKILL.md
    instructions injected. All other skills get brief registry descriptions only.

    Args:
        skill_data: List of skill entries from _collect_agent_connections.
        log_prefix: Log prefix for debug messages.

    Returns:
        Tuple of (prompt_text, has_personality). prompt_text is the string to
        append to system_message. has_personality indicates whether any
        personality skills were found (used to drop the default system message).
    """
    # Kept as a compatibility entry point for callers and tests; the shared
    # builder is the sole progressive-disclosure implementation.
    from services.skill_prompt import build_skill_system_prompt

    return build_skill_system_prompt(skill_data, log_prefix)


@dataclass
class _AgentContextRuntime:
    """Plain conversation binding for one Context-connected agent.

    The key ``(workflow_id, generation, agent_node_id)`` addresses one row in
    the ``agent_conversations`` store; ``history`` is that row's transcript
    replayed as native messages, and ``save`` writes the loop's live message
    list back per turn (called via the agent loop's ``conversation_saver``,
    which already treats failures as best-effort).
    """

    workflow_id: str
    generation: int
    agent_node_id: str
    database: Any
    history: List[NativeMessage]

    async def save(self, messages: List[NativeMessage]) -> None:
        from services.agent_context import save_conversation
        from services.llm.protocol import message_to_wire

        await save_conversation(
            self.database,
            workflow_id=self.workflow_id,
            generation=self.generation,
            agent_node_id=self.agent_node_id,
            messages=[dict(message_to_wire(message)) for message in messages],
        )


class AIService:
    """AI model service backed by the native provider SDK layer."""

    def __init__(
        self,
        auth_service: AuthService,
        database,
        cache,
        settings: Settings,
        chat_unifier=None,
        gateway_router=None,
    ):
        self.auth = auth_service
        self.database = database
        self.cache = cache
        self.settings = settings
        # ``ChatUnifier`` is the single facade for chat-model dispatch +
        # typed-exception translation + JSON-driven incompatible_models
        # filter. Injected by the DI container; the legacy ``None``
        # default exists only so tests and ad-hoc constructions without
        # the DI container can still instantiate ``AIService`` (the chat
        # paths will fall back to direct factory calls).
        self.chat_unifier = chat_unifier
        # services/gateway/routing.py: a provider with no key of the
        # install's own may still run on the OpenCompany Gateway.
        self.gateway_router = gateway_router
        # RLM service (lazy import to avoid circular deps)
        # RLM service (lazy import to avoid circular deps)
        from services.rlm import RLMService

        self.rlm_service = RLMService(auth=self.auth)

    def detect_provider(self, model: str) -> str:
        """Detect AI provider from model name."""
        return detect_provider_from_model(model)

    async def _gateway_covers(self, provider: str) -> bool:
        """No key of the install's own, but the OpenCompany Gateway serves
        ``provider``: ChatUnifier sends the call there (services/gateway)."""
        return self.gateway_router is not None and await self.gateway_router.covers(provider)

    async def _prepare_context(
        self,
        *,
        node_id: str,
        context_data: Optional[Dict[str, Any]],
        execution_context: Optional[Dict[str, Any]],
        workflow_id: Optional[str],
        database: Any,
    ) -> Optional["_AgentContextRuntime"]:
        """Load the agent's stored conversation for this generation.

        Returns ``None`` when no Context node is connected or the run carries
        no admitted generation (manual canvas runs persist nothing by
        design). A failing load raises instead of silently starting an
        amnesiac run that burns tokens on an empty prompt.
        """

        if not context_data or context_data.get("kind") != "context":
            return None

        from services.agent_context import load_conversation
        from services.llm.protocol import message_from_wire

        raw_context = execution_context or {}
        admitted_workflow_id = str(
            workflow_id or raw_context.get("workflow_id") or ""
        )
        descriptor_workflow_id = str(context_data.get("workflow_id") or "")
        if (
            admitted_workflow_id
            and descriptor_workflow_id
            and admitted_workflow_id != descriptor_workflow_id
        ):
            raise ValueError("Context workflow scope mismatch")
        resolved_workflow_id = admitted_workflow_id or descriptor_workflow_id
        if not resolved_workflow_id:
            return None
        admitted_generation = int(
            raw_context.get("generation")
            or raw_context.get("workflow_generation")
            or 0
        )
        descriptor_generation = int(context_data.get("generation") or 0)
        if (
            admitted_generation
            and descriptor_generation
            and admitted_generation != descriptor_generation
        ):
            raise ValueError("Context generation scope mismatch")
        generation = admitted_generation or descriptor_generation
        if generation <= 0:
            return None

        try:
            wires = await load_conversation(
                database,
                workflow_id=resolved_workflow_id,
                generation=generation,
                agent_node_id=node_id,
            )
        except Exception as exc:
            raise ValueError(
                "Conversation load failed for workflow "
                f"{resolved_workflow_id} generation {generation} agent "
                f"{node_id}: {exc}"
            ) from exc
        history = [
            message_from_wire(wire)
            for wire in wires
            if isinstance(wire, dict)
        ]
        return _AgentContextRuntime(
            workflow_id=resolved_workflow_id,
            generation=generation,
            agent_node_id=node_id,
            database=database,
            history=history,
        )

    def _extract_text_content(self, content, ai_response=None) -> str:
        """Extract text content from various response formats.

        Handles:
        - String content (OpenAI, Anthropic)
        - List of content blocks (Gemini 3+ models)
        - Empty/None content with error details from metadata

        Args:
            content: The raw content from response (str, list, or None)
            ai_response: The full AIMessage for metadata inspection

        Returns:
            Extracted text string

        Raises:
            ValueError: If content is empty with details about why
        """
        # Handle list content (Gemini format: [{"type": "text", "text": "..."}])
        if isinstance(content, list):
            text_parts = []
            for block in content:
                if isinstance(block, dict):
                    if block.get("type") == "text" and block.get("text"):
                        text_parts.append(block["text"])
                    elif "text" in block:
                        text_parts.append(str(block["text"]))
                elif isinstance(block, str):
                    text_parts.append(block)
            extracted = "\n".join(text_parts)
            if extracted.strip():
                return extracted
            # List was present but no text extracted
            logger.warning(f"[Agent] Content was list but no text extracted: {content}")

        # Handle string content
        if isinstance(content, str) and content.strip():
            return content

        # Use the content_blocks property for typed content extraction
        if ai_response and hasattr(ai_response, "content_blocks") and ai_response.content_blocks:
            text_parts = []
            for block in ai_response.content_blocks:
                if isinstance(block, dict) and block.get("type") == "text":
                    text_parts.append(block.get("text", ""))
            extracted = "\n".join(filter(None, text_parts))
            if extracted.strip():
                return extracted

        # Content is empty - try to get error details from metadata
        error_details = []
        if ai_response and hasattr(ai_response, "response_metadata"):
            meta = ai_response.response_metadata
            finish_reason = meta.get("finish_reason", "")

            if finish_reason == "SAFETY":
                error_details.append("Content blocked by safety filters")
                # Try to get specific blocked categories
                safety_ratings = meta.get("safety_ratings", [])
                blocked = [r.get("category") for r in safety_ratings if r.get("blocked")]
                if blocked:
                    error_details.append(f"Blocked categories: {', '.join(blocked)}")

            elif finish_reason in ("MAX_TOKENS", "length"):
                # Check if reasoning consumed all tokens (OpenAI o-series models)
                # OpenAI path: token_usage.completion_tokens_details.reasoning_tokens
                token_usage = meta.get("token_usage", {})
                completion_details = token_usage.get("completion_tokens_details", {})
                reasoning_tokens = completion_details.get("reasoning_tokens", 0)
                completion_tokens = token_usage.get("completion_tokens", 0)

                # Also check Gemini path: output_token_details
                if not reasoning_tokens:
                    token_details = meta.get("output_token_details", {})
                    reasoning_tokens = token_details.get("reasoning", 0)

                if reasoning_tokens > 0 and reasoning_tokens >= completion_tokens:
                    error_details.append(
                        f"Model used all {reasoning_tokens} tokens for reasoning, none left for response. Increase max_tokens (current response used {completion_tokens} total)."
                    )
                else:
                    error_details.append("Response truncated due to max_tokens limit")

            elif finish_reason == "MALFORMED_FUNCTION_CALL":
                error_details.append("Model returned malformed function call. Tool schema may be incompatible.")

            if meta.get("block_reason"):
                error_details.append(f"Block reason: {meta.get('block_reason')}")

        if error_details:
            raise ValueError(f"AI returned empty response. {'; '.join(error_details)}")

        # Generic empty response - log full response details for debugging
        if ai_response:
            logger.warning(f"[Agent] Empty response debug - content_blocks: {getattr(ai_response, 'content_blocks', None)}")
            logger.warning(f"[Agent] Empty response debug - additional_kwargs: {getattr(ai_response, 'additional_kwargs', {})}")
            if hasattr(ai_response, "response_metadata"):
                meta = ai_response.response_metadata
                logger.warning(f"[Agent] Empty response debug - finish_reason: {meta.get('finish_reason')}")
                logger.warning(f"[Agent] Empty response debug - token_usage: {meta.get('token_usage')}")
        logger.warning(f"[Agent] Empty response with no error details. Content type: {type(content)}, value: {repr(content)}")
        raise ValueError("AI generated empty response. Try rephrasing your prompt or using a different model.")

    async def _track_token_usage(
        self,
        session_id: str,
        node_id: str,
        provider: str,
        model: str,
        ai_response,
        all_messages: list,
        broadcaster=None,
        workflow_id: Optional[str] = None,
        memory_content: Optional[str] = None,
        api_key: Optional[str] = None,
        memory_node_id: Optional[str] = None,
    ) -> Optional[Dict[str, Any]]:
        """Track token usage and trigger compaction if threshold exceeded.

        Extracts usage_metadata from the assistant message and tracks it
        in the compaction service for session token monitoring.

        Args:
            session_id: Memory session ID
            node_id: Agent node ID
            provider: AI provider name
            model: Model name
            ai_response: The AIMessage response
            all_messages: All messages in conversation (for aggregation)
            broadcaster: Optional status broadcaster
            workflow_id: Optional workflow ID for scoped broadcasts
            memory_content: Current memory content (for compaction)
            api_key: API key (for compaction summarization)
            memory_node_id: Memory node ID (for parameter updates)

        Returns:
            Compaction result if triggered, None otherwise
        """
        from services.compaction import get_compaction_service

        svc = get_compaction_service()
        if not svc:
            return

        # Native responses expose a normalized ``Usage`` object. The
        # attribute probes below stay because callers also hand this method
        # raw provider payloads, which carry usage under either name.
        usage = None
        if isinstance(ai_response, Usage):
            usage = ai_response
        elif isinstance(ai_response, LLMResponse):
            usage = ai_response.usage
        elif hasattr(ai_response, "usage_metadata") and ai_response.usage_metadata:
            usage = ai_response.usage_metadata
        elif hasattr(ai_response, "response_metadata"):
            # Fallback: check response_metadata for usage info
            meta = ai_response.response_metadata
            if "usage" in meta:
                usage = meta["usage"]
            elif "token_usage" in meta:
                usage = meta["token_usage"]

        if not usage and all_messages:
            # Aggregate usage from all AI messages if single message has no usage
            total_input = 0
            total_output = 0
            for msg in all_messages:
                if hasattr(msg, "usage_metadata") and msg.usage_metadata:
                    total_input += msg.usage_metadata.get("input_tokens", 0)
                    total_output += msg.usage_metadata.get("output_tokens", 0)
            if total_input > 0 or total_output > 0:
                usage = {"input_tokens": total_input, "output_tokens": total_output, "total_tokens": total_input + total_output}

        if not usage:
            logger.debug(f"[TokenTracking] No usage_metadata available for {provider}/{model}")
            return

        # Normalize usage dict (handle both dict and TypedDict formats)
        usage_dict = {
            "input_tokens": usage.get("input_tokens", 0) if isinstance(usage, dict) else getattr(usage, "input_tokens", 0),
            "output_tokens": usage.get("output_tokens", 0) if isinstance(usage, dict) else getattr(usage, "output_tokens", 0),
            "total_tokens": usage.get("total_tokens", 0) if isinstance(usage, dict) else getattr(usage, "total_tokens", 0),
            "cache_creation_tokens": usage.get("cache_creation_tokens", 0) if isinstance(usage, dict) else getattr(usage, "cache_creation_tokens", 0),
            "cache_read_tokens": usage.get("cache_read_tokens", 0) if isinstance(usage, dict) else getattr(usage, "cache_read_tokens", 0),
            "reasoning_tokens": usage.get("reasoning_tokens", 0) if isinstance(usage, dict) else getattr(usage, "reasoning_tokens", 0),
        }

        try:
            tracking = await svc.track(session_id=session_id, node_id=node_id, provider=provider, model=model, usage=usage_dict)
            logger.debug(f"[TokenTracking] Tracked {usage_dict['total_tokens']} tokens for session {session_id}, total={tracking['total']}")

            # Broadcast token update
            if broadcaster:
                await broadcaster.broadcast(
                    {"type": "token_usage_update", "session_id": session_id, "workflow_id": workflow_id, "data": tracking}
                )

            # Trigger compaction if threshold exceeded
            # No own key is fine when the OpenCompany Gateway serves the provider.
            if tracking.get("needs_compaction") and memory_content and (api_key or await self._gateway_covers(provider)):
                logger.info(f"[Compaction] Threshold exceeded for session {session_id}, triggering compaction")

                if broadcaster:
                    await broadcaster.broadcast({"type": "compaction_starting", "session_id": session_id, "node_id": node_id})

                result = await svc.compact_context(
                    session_id=session_id, node_id=node_id, memory_content=memory_content, provider=provider, api_key=api_key, model=model
                )

                if broadcaster:
                    await broadcaster.broadcast(
                        {
                            "type": "compaction_completed",
                            "session_id": session_id,
                            "success": result.get("success", False),
                            "tokens_before": result.get("tokens_before", 0),
                            "tokens_after": result.get("tokens_after", 0),
                            "error": result.get("error"),
                        }
                    )

                return result

        except Exception as e:
            logger.warning(f"[TokenTracking] Failed to track tokens: {e}")

        return None


    def _get_curated_models(self, provider: str) -> List[str]:
        """Get curated model list from llm_defaults.json for a provider.

        Delegates to ``services.llm.config.curated_models`` — the same
        list backs ``OpenAIProvider.fetch_models`` for providers that
        declare no model-list route, and the two must not drift.
        """
        from services.llm.config import curated_models

        return curated_models(provider)

    async def fetch_models(self, provider: str, api_key: str) -> List[str]:
        """Fetch available models from a provider via ``ChatUnifier``.

        The unifier handles ``{provider}_proxy`` resolution, typed-SDK
        exception translation, and the JSON-driven ``incompatible_models``
        filter. All 12 providers (4 dedicated + 8 OpenAI-compat
        including groq + cerebras) route through here — Phase D removed
        the legacy per-provider fallback path.

        On API failure, falls back to the curated list from
        ``llm_defaults.json``. When the provider has no ``default_model``
        declared (intentional for local servers like ollama / lmstudio),
        returns an empty list so the frontend dropdown shows a real
        "no models" empty state instead of a placeholder name.
        """
        if self.chat_unifier is None:
            raise NodeUserError(
                "ChatUnifier is not injected. AIService must be constructed via "
                "the DI container (core.container.Container)."
            )
        if not api_key and await self._gateway_covers(provider):
            # No key of the install's own: the gateway serves this provider.
            # Its curated models, with no network call: a gateway key must
            # never reach a vendor's model-list URL.
            return self._get_curated_models(provider)
        try:
            return await self.chat_unifier.fetch_models(provider=provider, api_key=api_key)
        except NodeUserError:
            raise
        except Exception as e:
            logger.warning(f"[AI] Failed to fetch models from {provider} API: {e}")

        # JSON-curated fallback
        curated = self._get_curated_models(provider)
        if curated:
            return curated
        provider_cfg = _LLM_DEFAULTS.get("providers", {}).get(provider, {})
        default_model = provider_cfg.get("default_model", "")
        return [default_model] if default_model else []

    async def execute_chat(self, node_id: str, node_type: str, parameters: Dict[str, Any]) -> Dict[str, Any]:
        """Execute AI chat model."""
        start_time = time.time()

        try:
            # Flatten options collection from frontend
            options = parameters.get("options", {})
            flattened = {**parameters, **options}

            # Extract the schema-canonical chat-model parameters.
            api_key = flattened.get("api_key")
            model = flattened.get("model", "gpt-3.5-turbo")
            # Strip [FREE] prefix if present (added by OpenRouter model list for display)
            if model.startswith("[FREE] "):
                model = model[7:]
            prompt = flattened.get("prompt", "Hello")

            # Schema-canonical name on chat-model `_base.py` is
            # `system_prompt`; agent paths use `system_message` and are
            # handled separately in execute_agent / execute_chat_agent.
            system_prompt = flattened.get("system_prompt", "")

            # Determine provider from node_type (more reliable than model name detection)
            from constants import detect_ai_provider

            provider = detect_ai_provider(node_type, flattened)

            if not api_key and not await self._gateway_covers(provider):
                _require_saved_endpoint(provider)
                raise ValueError("API key is required")

            # Validate prompt is not empty (prevents wasted API calls for all providers)
            if not is_valid_message_content(prompt):
                raise ValueError("Prompt cannot be empty")

            # Build thinking config from parameters
            thinking_config = None
            if flattened.get("thinking_enabled"):
                thinking_config = NativeThinkingConfig(
                    enabled=True,
                    budget=int(flattened.get("thinking_budget", 2048)),
                    effort=flattened.get("reasoning_effort", "medium"),
                    # No fabricated default — only forward thinking_level
                    # when the node actually configured it (Vertex rejects
                    # an unsolicited thinking_level on 2.5-era models).
                    level=flattened.get("thinking_level"),
                    format=flattened.get("reasoning_format", "parsed"),
                )

            # --- Unifier path (every provider) ---
            #
            # ``ChatUnifier`` owns proxy_url resolution + provider
            # instantiation + typed-SDK exception translation (raises
            # ``NodeUserError`` for both unknown providers and typed SDK
            # errors so ``BaseNode.execute()`` logs one WARN line with
            # no traceback). No per-provider Python lives here.
            #
            # groq + cerebras register through the OpenAI-compat path in
            # ``services.llm.providers._compat``.
            if self.chat_unifier is None:
                raise NodeUserError(
                    "ChatUnifier is not injected. AIService must be constructed via "
                    "the DI container (core.container.Container)."
                )

            max_tokens = native_resolve_max_tokens(flattened, model, provider)
            temperature = native_resolve_temperature(
                flattened,
                model,
                provider,
                bool(thinking_config and thinking_config.enabled),
            )

            native_msgs: List[NativeMessage] = []
            if system_prompt and is_valid_message_content(system_prompt):
                native_msgs.append(NativeMessage(role="system", content=system_prompt))
            native_msgs.append(NativeMessage(role="user", content=prompt))

            llm_resp: LLMResponse = await self.chat_unifier.chat(
                provider=provider,
                api_key=api_key,
                messages=native_msgs,
                model=model,
                temperature=temperature,
                max_tokens=max_tokens,
                thinking=thinking_config,
            )

            response_text = llm_resp.content
            thinking_content = llm_resp.thinking
            finish_reason = llm_resp.finish_reason

            result = {
                "response": response_text,
                "thinking": thinking_content,
                "thinking_enabled": thinking_config.enabled if thinking_config else False,
                "model": model,
                "provider": provider,
                "finish_reason": finish_reason,
                "timestamp": datetime.now().isoformat(),
                "input": {
                    "prompt": prompt,
                    "system_prompt": system_prompt,
                },
            }

            log_execution_time(logger, "ai_chat", start_time, time.time())
            log_api_call(logger, provider, model, "chat", True)

            return {
                "success": True,
                "node_id": node_id,
                "node_type": node_type,
                "result": result,
                "execution_time": time.time() - start_time,
            }

        except NodeUserError:
            # Re-raise without wrapping. ``ChatUnifier`` already
            # translated the typed SDK exception (openai / anthropic /
            # google APIError, …) into ``NodeUserError`` at the single
            # delegation site. ``BaseNode.execute()`` catches this and
            # logs one WARN line with no traceback. Every chat-path
            # call goes through the unifier post-Phase-A3, so the
            # previous per-provider catch blocks are gone.
            raise

        except Exception as e:
            logger.error("AI execution failed", node_id=node_id, error=str(e))
            log_api_call(
                logger,
                provider if "provider" in locals() else "unknown",
                model if "model" in locals() else "unknown",
                "chat",
                False,
                error=str(e),
            )

            return {
                "success": False,
                "node_id": node_id,
                "node_type": node_type,
                "error": str(e),
                "execution_time": time.time() - start_time,
                "timestamp": datetime.now().isoformat(),
            }

    async def execute_agent(
        self,
        node_id: str,
        parameters: Dict[str, Any],
        memory_data: Optional[Dict[str, Any]] = None,
        skill_data: Optional[List[Dict[str, Any]]] = None,
        tool_data: Optional[List[Dict[str, Any]]] = None,
        broadcaster=None,
        workflow_id: Optional[str] = None,
        context: Optional[Dict[str, Any]] = None,
        database=None,
    ) -> Dict[str, Any]:
        """Execute AI Agent via the shared native SDK loop.

        Each iteration invokes ``ChatUnifier``, appends the exact replayable
        assistant message, dispatches tool calls, appends native tool-result
        messages, and continues until a final response or the configured
        recursion limit.

        Features:
        - Provider-neutral tool calling through ``AgentToolSpec``
        - Real-time status broadcasts for UI animations

        Args:
            node_id: The node identifier
            parameters: Node parameters including prompt, model, etc.
            memory_data: Optional memory data from connected simpleMemory node
                        containing session_id, window_size for conversation history
            skill_data: Optional skill configurations from connected skill nodes
            tool_data: Optional list of tool configurations from connected tool nodes
            broadcaster: Optional StatusBroadcaster for real-time UI updates
            workflow_id: Optional workflow ID for scoped status broadcasts
            context: Optional execution context with nodes, edges for nested agent delegation
        """
        start_time = time.time()
        provider = "unknown"
        model = "unknown"

        # EARLY LOG: Entry point for debugging
        from services.runtime_tool_context import prepare_native_runtime
        parameters, context, skill_data, tool_data = await prepare_native_runtime(
            database or self.database, node_id, parameters, context, skill_data, tool_data, workflow_id=workflow_id)
        logger.debug(
            f"[AIAgent] execute_agent called: node_id={node_id}, workflow_id={workflow_id}, skill_count={len(skill_data) if skill_data else 0}, tool_count={len(tool_data) if tool_data else 0}"
        )
        if skill_data:
            for i, sd in enumerate(skill_data):
                logger.debug(f"[AIAgent] Skill {i}: type={sd.get('node_type')}, label={sd.get('label')}")
        if tool_data:
            for i, td in enumerate(tool_data):
                logger.debug(f"[AIAgent] Tool {i}: type={td.get('node_type')}, node_id={td.get('node_id')}")

        # Helper to broadcast status updates with workflow_id for proper scoping
        async def broadcast_status(phase: str, details: Dict[str, Any] = None):
            if broadcaster:
                await broadcaster.update_node_status(
                    node_id, "executing", {"phase": phase, "agent_type": "loop", **(details or {})}, workflow_id=workflow_id
                )

        try:
            # Extract top-level parameters (always visible in UI)
            prompt = parameters.get("prompt", "Hello")
            system_message = parameters.get("system_message", "You are a helpful assistant")

            # Inject skills: personality skills get full instructions, others get brief descriptions
            skill_prompt, has_personality = _build_skill_system_prompt(skill_data, log_prefix="[AIAgent]")
            if skill_prompt:
                if has_personality:
                    system_message = skill_prompt
                else:
                    system_message = f"{system_message}\n\n{skill_prompt}"

            # Flatten options collection from frontend
            options = parameters.get("options", {})
            flattened = {**parameters, **options}

            api_key = flattened.get("api_key")
            provider = parameters.get("provider", "openai")
            model = parameters.get("model", "")
            # Strip [FREE] prefix if present (added by OpenRouter model list for display)
            if model.startswith("[FREE] "):
                model = model[7:]

            logger.debug(f"[Agent] Agent: {provider}/{model}, tools={len(tool_data) if tool_data else 0}")

            # If no model specified or model doesn't match provider, use default (DB > config)
            if not model or not is_model_valid_for_provider(model, provider):
                old_model = model
                model = await get_default_model_async(provider, database)
                if old_model:
                    logger.warning(f"Model '{old_model}' invalid for provider '{provider}', using default: {model}")
                else:
                    logger.info(f"No model specified, using default: {model}")

            if not api_key and not await self._gateway_covers(provider):
                _require_saved_endpoint(provider)
                raise ValueError("API key is required for AI Agent")

            # Resolve max_tokens and temperature via model registry
            max_tokens = _resolve_max_tokens(flattened, model, provider)

            # Build thinking config from parameters
            thinking_config = None
            if flattened.get("thinking_enabled"):
                thinking_config = ThinkingConfig(
                    enabled=True,
                    budget=int(flattened.get("thinking_budget", 2048)),
                    effort=flattened.get("reasoning_effort", "medium"),
                    level=flattened.get("thinking_level"),
                    format=flattened.get("reasoning_format", "parsed"),
                )
                logger.debug(f"[Agent] Thinking enabled: budget={thinking_config.budget}, effort={thinking_config.effort}")

            temperature = _resolve_temperature(flattened, model, provider, bool(thinking_config and thinking_config.enabled))

            # Broadcast: Initializing model
            await broadcast_status("initializing", {"message": f"Initializing {provider} model...", "provider": provider, "model": model, "active_skills": [], "last_skills": [], "last_tool_name": None, "last_capability": None})

            context_runtime = await self._prepare_context(
                node_id=node_id,
                context_data=memory_data,
                execution_context=context,
                workflow_id=workflow_id,
                database=database or self.database,
            )
            if context_runtime is not None:
                # Simple Memory is an explicit tool when a Context node is
                # connected; legacy automatic recall/persistence remains only
                # for graphs recorded with an input-memory edge.
                memory_data = None

            # Build initial messages for state. The SystemMessage is
            # PREPENDED after tool building (below), because the
            # delegation-guidance block at the end of the tool-building
            # section grows ``system_message`` to include the
            # ``Available agents: delegate_to_*`` list and the
            # ``task``/``context`` schema description. Appending the
            # SystemMessage here would lock in the pre-update string
            # and the LLM would never see the delegation contract,
            # which is exactly what previously broke ``aiAgent``-driven
            # delegation through the ``input-tools`` handle.
            initial_messages: List[NativeMessage] = (
                [
                    message
                    for message in context_runtime.history
                    if message.role != "system"
                ]
                if context_runtime is not None
                else []
            )

            # Add memory history from connected simpleMemory node (markdown-based)
            session_id = None
            history_count = 0
            if memory_data and memory_data.get("session_id"):
                session_id = memory_data["session_id"]
                memory_content = memory_data.get("memory_content", "")

                # Broadcast: Loading memory
                await broadcast_status(
                    "loading_memory", {"message": "Loading conversation history...", "session_id": session_id, "has_memory": True}
                )

                # Parse short-term memory from markdown
                history_messages = _parse_memory_markdown(memory_content)
                history_count = len(history_messages)

                # If long-term memory enabled, retrieve relevant context
                if memory_data.get("long_term_enabled"):
                    try:
                        store = await _get_configured_memory_vector_store(
                            session_id,
                            memory_data,
                            self.auth,
                        )
                        if store:
                            k = memory_data.get("retrieval_count", 3)
                            docs = await store.similarity_search(prompt, k=k)
                            if docs:
                                retrieved_context = "\n---\n".join(
                                    d.page_content for d in docs
                                )
                                initial_messages.append(
                                    NativeMessage(
                                        role="system",
                                        content=(
                                            "Relevant past context:\n"
                                            f"{retrieved_context}"
                                        ),
                                    )
                                )
                                logger.info(f"[Agent Memory] Retrieved {len(docs)} relevant memories from long-term store")
                    except Exception as e:
                        logger.debug(f"[Agent Memory] Long-term retrieval skipped: {e}")

                # Add parsed history messages
                initial_messages.extend(history_messages)

                logger.info(f"[Agent Memory] Loaded {history_count} messages from markdown")

                # Broadcast: Memory loaded
                await broadcast_status(
                    "memory_loaded",
                    {"message": f"Loaded {history_count} messages from memory", "session_id": session_id, "history_count": history_count},
                )

            # Add current user prompt
            initial_messages.append(NativeMessage(role="user", content=prompt))

            # Build tools if provided
            tools = []
            tool_configs = {}
            tool_identities: List[Dict[str, str]] = []
            tool_bindings: List[tuple[Any, Dict[str, Any]]] = []

            # Standard skills are progressively disclosed through one scoped
            # provider-neutral tool. Personality skills were injected above.
            from services.skill_runtime import skill_tool_info

            skill_info = skill_tool_info(skill_data or [], node_id)
            effective_tool_data = unique_node_bindings(tool_data or [])
            if skill_info:
                effective_tool_data.append(skill_info)

            if effective_tool_data:
                await broadcast_status("building_tools", {"message": f"Building {len(effective_tool_data)} tool(s)...", "tool_count": len(effective_tool_data)})

                for tool_info in effective_tool_data:
                    for tool, config in await node_tools(self, tool_info):
                        tools.append(tool)
                        tool_bindings.append((tool, config))
                        tool_identities.append(
                            {
                                "name": tool.name,
                                "node_id": str(config.get("node_id") or tool_info.get("node_id") or ""),
                                "label": str(config.get("label") or tool_info.get("label") or tool_info.get("node_type") or "tool"),
                            }
                        )
                        logger.debug(f"[Agent] Registered tool: name={tool.name}, node_id={config.get('node_id')}")

                logger.debug(f"[Agent] Built {len(tools)} tools")

                # Auto-inject check_delegated_tasks tool when delegation tools present
                if any(tool.name.startswith("delegate_to_") for tool in tools):
                    check_info = {
                        "node_type": "_builtin_check_delegated_tasks",
                        "node_id": f"{node_id}_check_tasks",
                        "parameters": {},
                        "label": "Check Delegated Tasks",
                    }
                    check_tool, check_config = await self._build_tool_from_node(check_info)
                    if check_tool:
                        tools.append(check_tool)
                        tool_bindings.append((check_tool, check_config))
                        tool_identities.append(
                            {
                                "name": check_tool.name,
                                "node_id": str(check_config.get("node_id") or check_info["node_id"]),
                                "label": str(check_config.get("label") or check_info["label"]),
                            }
                        )
                        logger.debug("[Agent] Auto-injected check_delegated_tasks tool")

                    # Add delegation guidance to system message
                    delegate_names = [tool.name for tool in tools if tool.name.startswith("delegate_to_")]
                    system_message += (
                        "\n\n## Agent Delegation\n"
                        "When delegating to sub-agents, use 'task' for the mission directive "
                        "(role and goal) and 'context' for input data the agent needs to work with.\n"
                        f"Available agents: {', '.join(delegate_names)}"
                    )

                # Name-based dispatch is only safe after validating the full
                # surface.  Build the lookup map after this check so a later
                # duplicate can never silently replace an earlier node.
                ensure_unique_tool_names(tool_identities)
                tool_configs.update({tool.name: config for tool, config in tool_bindings})

            # Now that ``system_message`` is final (skill prompt + delegation
            # guidance both folded in), prepend it as the first message.
            # See the comment at the original ``initial_messages`` declaration
            # for why this can't happen earlier.
            if system_message:
                initial_messages.insert(
                    0,
                    NativeMessage(role="system", content=system_message),
                )

            # Create tool executor callback. Tool-node status lifecycle
            # (executing/success/error) is owned by ``handlers.tools.execute_tool``
            # — this closure only emits the *parent agent's* phase
            # broadcasts (``executing_tool`` / ``tool_completed``).
            async def tool_executor(tool_name: str, tool_args: Dict) -> Any:
                """Execute a tool by name."""
                from services.handlers.tools import execute_tool

                config = tool_configs.get(tool_name, {})
                tool_node_id = config.get("node_id")

                logger.debug(f"[Agent] Executing tool: {tool_name} (args={tool_args})")
                logger.debug(f"[Agent] Tool node_id={tool_node_id}, workflow_id={workflow_id}")

                # Parent-agent phase broadcast (does not touch tool node).
                await broadcast_status(
                    "executing_tool", {"message": f"Executing tool: {tool_name}", "tool_name": tool_name}
                )

                if broadcaster and tool_name and tool_name != "Skill":
                    await broadcaster.broadcast_agent_capability(
                        node_id,
                        capability_kind="tool",
                        capability_name=tool_name,
                        state="started",
                        workflow_id=workflow_id,
                        execution_id=str((context or {}).get("execution_id") or "") or None,
                        root_execution_id=str((context or {}).get("root_execution_id") or "") or None,
                        target_node_id=str(tool_node_id or "") or None,
                        provider=provider,
                        invocation_source="native",
                    )

                # Inject services + graph context so execute_tool can scope its
                # broadcasts and nested agents can execute with their own tools.
                config["workflow_id"] = workflow_id
                config["ai_service"] = self
                config["database"] = self.database
                config["parent_node_id"] = node_id
                config["provider"] = provider
                # Surface the auto-rebind toggle so agentBuilder's summary
                # text reflects the user's current preference.
                config["auto_rebind_tools"] = auto_rebind_enabled
                if context:
                    if context.get("pi_harness_version") == 1:
                        from services.temporal.pi_inline_delegation import forward_inline_scope
                        config.update(forward_inline_scope(context))
                    config["run_scope"] = context.get("run_scope")
                    config["generation"] = context.get("generation")
                    config["parameter_snapshot"] = context.get("parameter_snapshot", {})
                    config["employee_job_id"] = context.get("employee_job_id")
                    config["team_task_id"] = context.get("team_task_id")
                    config["team_execution_id"] = context.get("team_execution_id")
                    for scope_key in ("data_scope_id", "context_execution_id", "context_session_id", "session_id", "graphVersion", "outputs", "pi_harness_version", "runtime_behavior_version"):
                        if scope_key in context:
                            config[scope_key] = context[scope_key]
                    config["nodes"] = context.get("nodes", [])
                    config["edges"] = context.get("edges", [])
                    config["workspace_dir"] = context.get("workspace_dir", "")
                    config["user_id"] = context.get("user_id", "owner")
                    # Stable per-run id so session-keyed tools (browser)
                    # reuse one instance across the agent loop.
                    config["execution_id"] = context.get("execution_id")
                    config["_browser_task_id"] = context.get("_browser_task_id")
                    config["_browser_owner"] = (context.get("browser_bindings") or {}).get(str(tool_node_id))
                    config["root_execution_id"] = context.get("root_execution_id")
                    config["delegation_depth"] = context.get("delegation_depth", 0)
                    config["team_id"] = context.get("team_id")
                    config["max_concurrent_subagents"] = context.get("max_concurrent_subagents", 3)
                    config["max_delegation_depth"] = context.get("max_delegation_depth", 2)

                try:
                    from services.employees.permissions import assert_runtime_access
                    await assert_runtime_access(self.database, workflow_id, str(tool_node_id or ""), str(config.get("node_type") or ""), config)
                    result = await execute_tool(tool_name, tool_args, config)

                    await broadcast_status(
                        "tool_completed",
                        {"message": f"Tool completed: {tool_name}", "tool_name": tool_name},
                    )

                    if broadcaster and tool_name and tool_name != "Skill":
                        await broadcaster.broadcast_agent_capability(
                            node_id,
                            capability_kind="tool",
                            capability_name=tool_name,
                            state="completed",
                            workflow_id=workflow_id,
                            execution_id=str((context or {}).get("execution_id") or "") or None,
                            root_execution_id=str((context or {}).get("root_execution_id") or "") or None,
                            target_node_id=str(tool_node_id or "") or None,
                            provider=provider,
                            invocation_source="native",
                        )

                    return result

                except Exception as e:
                    error_msg = str(e)
                    logger.error(f"[Agent] Tool execution failed: {tool_name}", error=error_msg)

                    # Keep normal AI agents on the same observable contract as
                    # specialized/team-lead agents.  Without this terminal
                    # phase a failed fast tool call leaves only the preceding
                    # generic executing phase, so the canvas cannot retain
                    # ``tool <name>`` or mark the capability as failed.
                    await broadcast_status(
                        "tool_completed",
                        {
                            "message": f"Tool failed: {tool_name}",
                            "tool_name": tool_name,
                            "tool_failed": True,
                        },
                    )
                    if broadcaster and tool_name and tool_name != "Skill":
                        await broadcaster.broadcast_agent_capability(
                            node_id,
                            capability_kind="tool",
                            capability_name=tool_name,
                            state="failed",
                            workflow_id=workflow_id,
                            execution_id=str((context or {}).get("execution_id") or "") or None,
                            root_execution_id=str((context or {}).get("root_execution_id") or "") or None,
                            target_node_id=str(tool_node_id or "") or None,
                            provider=provider,
                            invocation_source="native",
                            error_code=type(e).__name__,
                        )

                    # Re-raise so the native loop can surface the error to the LLM.
                    raise

            # Auto-rebind toggle: when the user enables "Auto-Rebind Tools
            # After Canvas Changes" in Settings, canvas-mutating tools
            # (agentBuilder) extend the LLM's bound surface mid-loop. The
            # default is True; lookup failures fall back to True so the
            # feature doesn't silently disable itself on a transient DB hiccup.
            auto_rebind_enabled = True
            user_recursion_limit: Optional[int] = None
            tool_output_limit = resolve_tool_output_limit(None, self.settings)
            try:
                user_settings = await self.database.get_user_settings()
                if user_settings is not None:
                    auto_rebind_enabled = bool(
                        user_settings.get("auto_rebind_tools_after_canvas_change", True)
                    )
                    _raw_limit = user_settings.get("agent_recursion_limit")
                    if isinstance(_raw_limit, int) and _raw_limit > 0:
                        user_recursion_limit = _raw_limit
                    tool_output_limit = resolve_tool_output_limit(
                        user_settings, self.settings
                    )
            except Exception as exc:  # noqa: BLE001 — defensive read
                logger.debug("[Agent] user_settings read failed: %s", exc)

            async def _rebind_from_operations(operations: List[Dict[str, Any]]) -> List[Any]:
                """Translate workflow_ops add_node ops (component_kind='tool')
                into fresh :class:`AgentToolSpec` values via the canonical
                :meth:`_build_tool_from_node` helper. The returned list is
                appended to the native loop's current tool surface so the LLM
                can invoke the new tool in
                its NEXT iteration without a Run-stop-Run cycle.

                Tool configs are folded into the existing ``tool_configs``
                closure so ``tool_executor`` can route the LLM's eventual
                tool_call to the right node. A node already bound (Agent
                Builder hands back a saved tool this run may hold) is
                skipped rather than bound twice under one name.
                """
                from services.node_registry import get_node_class

                saved_workflow = await self.database.get_workflow(workflow_id) if workflow_id else None
                saved_graph = getattr(saved_workflow, "data", None) or {}
                if context is not None and saved_graph:
                    admitted_graph = extend_runtime_graph(context, saved_graph, operations)
                    context["nodes"] = admitted_graph["nodes"]
                    context["edges"] = admitted_graph["edges"]
                bound = {identity["node_id"] for identity in tool_identities}
                new_bindings: List[tuple[Any, Dict[str, Any]]] = []
                for op in operations:
                    if op.get("type") != "add_node":
                        continue
                    if not rebind_allowed(op, node_id, nodes=(context or {}).get("nodes", []), edges=(context or {}).get("edges", []), operations=() if saved_graph else operations):
                        continue
                    node_type = op.get("node_type")
                    if not node_type:
                        continue
                    cls = get_node_class(node_type)
                    if cls is None:
                        continue
                    # Match the catalogue filter — pure ToolNode OR
                    # dual-purpose ActionNode (usable_as_tool=True),
                    # excluding chat models. Without this the rebind
                    # silently drops twitterSearch / googleGmail /
                    # pythonExecutor etc. and the LLM tries to call
                    # tools it never got bound to. A Skills node
                    # (masterSkill) is tool-kind but feeds input-skill;
                    # it is never an LLM tool.
                    _kind = getattr(cls, "component_kind", "")
                    if not is_runtime_tool(cls):
                        continue
                    if (getattr(cls, "ui_hints", None) or {}).get("isMasterSkillEditor"):
                        continue
                    tool_info = {
                        "node_id": op.get("minted_id") or op.get("client_ref") or f"new_{node_type}",
                        "node_type": node_type,
                        "parameters": op.get("parameters") or {},
                        "label": op.get("label") or node_type,
                    }
                    if tool_info["node_id"] in bound:
                        continue
                    tool_info = bind_runtime_context(tool_info, context or {}, node_id)
                    try:
                        built = await node_tools(self, tool_info)
                    except Exception as exc:  # noqa: BLE001 — log + skip one tool
                        logger.warning(
                            "[Agent] rebind: building tools raised for %s: %s",
                            node_type,
                            exc,
                        )
                        continue
                    if not built:
                        continue
                    new_bindings.extend((tool, tool_config or tool_info) for tool, tool_config in built)
                    bound.add(tool_info["node_id"])

                new_identities = [
                    {
                        "name": tool.name,
                        "node_id": str(config.get("node_id") or ""),
                        "label": str(config.get("label") or config.get("node_type") or "tool"),
                    }
                    for tool, config in new_bindings
                ]
                ensure_unique_tool_names([*tool_identities, *new_identities])
                for tool, tool_config in new_bindings:
                    tool_configs[tool.name] = tool_config
                tool_identities.extend(new_identities)
                return [tool for tool, _ in new_bindings]

            # Broadcast: Building agent
            await broadcast_status(
                "building_graph",
                {
                    "message": "Building agent...",
                    "message_count": len(initial_messages),
                    "has_memory": bool(session_id),
                    "history_count": history_count,
                    "tool_count": len(tools),
                },
            )

            # Broadcast: Invoking LLM
            await broadcast_status(
                "invoking_llm",
                {
                    "message": f"Invoking {provider} LLM...",
                    "provider": provider,
                    "model": model,
                    "iteration": 1,
                    "has_memory": bool(session_id),
                    "history_count": history_count,
                },
            )

            # Run the agent loop. ``recursion_limit`` precedence:
            #   1. ``UserSettings.agent_recursion_limit`` (per-user)
            #   2. ``Settings.agent_recursion_limit`` env var (global default)
            #   3. ``llm_defaults.json:agent.recursion_limit`` (legacy fallback)
            # The real termination signal is the LLM returning a final
            # response without tool_calls; this cap is the safety backstop.
            # On hit, the loop appends a synthetic terminal AIMessage so
            # downstream extraction returns a usable partial response.
            from services.model_registry import get_model_registry

            if user_recursion_limit is not None:
                recursion_limit = user_recursion_limit
            else:
                recursion_limit = int(get_model_registry().get_agent_defaults()["recursion_limit"])

            async def _emit_progress(iter_count: int) -> None:
                if broadcaster:
                    await broadcaster.broadcast_agent_progress(
                        node_id,
                        workflow_id=workflow_id,
                        iteration=iter_count,
                        max_iterations=recursion_limit,
                    )

            final_state = await run_native_agent_loop(
                self.chat_unifier,
                **native_observer_options(context, node_id, workflow_id, provider, model),
                provider=provider,
                api_key=api_key,
                model=model,
                temperature=temperature,
                max_tokens=max_tokens,
                thinking=thinking_config,
                initial_messages=initial_messages,
                tools=tools if tools else None,
                tool_executor=tool_executor if tools else None,
                max_iterations=recursion_limit,
                progress_callback=_emit_progress if broadcaster else None,
                rebind_from_operations=_rebind_from_operations if auto_rebind_enabled else None,
                roster_after_rebind=lambda: delegation_roster(tool_identities),
                conversation_saver=(
                    context_runtime.save
                    if context_runtime is not None
                    else None
                ),
                tool_output_limit=tool_output_limit,
            )

            # Extract the AI response (last message in the accumulated messages)
            all_messages = final_state["messages"]
            ai_response = all_messages[-1] if all_messages else None

            if not ai_response or not hasattr(ai_response, "content"):
                raise ValueError("No response generated from agent")

            # Handle different content formats (Gemini can return list of content blocks)
            response_content = self._extract_text_content(ai_response.content, ai_response)
            iterations = final_state.get("iteration", 1)

            # Get accumulated thinking content from state
            thinking_content = final_state.get("thinking_content")

            logger.info(f"[Agent] Agent completed in {iterations} iteration(s), thinking={'yes' if thinking_content else 'no'}")

            # Track token usage if memory connected (for compaction service)
            # Also triggers compaction if threshold exceeded
            compaction_result = None
            if session_id and ai_response:
                compaction_result = await self._track_token_usage(
                    session_id=session_id,
                    node_id=node_id,
                    provider=provider,
                    model=model,
                    ai_response=final_state.get("usage") or ai_response,
                    all_messages=all_messages,
                    broadcaster=broadcaster,
                    workflow_id=workflow_id,
                    memory_content=memory_data.get("memory_content", "") if memory_data else None,
                    api_key=api_key,
                    memory_node_id=memory_data.get("node_id") if memory_data else None,
                )
                _accumulate_compaction_usage(
                    final_state, compaction_result
                )

            # Save to memory if connected (markdown-based with optional vector DB)
            # Only save non-empty messages using standardized validation
            if (
                memory_data
                and memory_data.get("node_id")
                and is_valid_message_content(prompt)
                and is_valid_message_content(response_content)
            ):
                # Broadcast: Saving to memory
                await broadcast_status(
                    "saving_memory",
                    {
                        "message": "Saving to conversation memory...",
                        "session_id": session_id,
                        "has_memory": True,
                        "history_count": history_count,
                    },
                )

                from services.memory.runtime import append_memory_turns_atomic

                # Compaction may take long enough for another worker to append.
                # The atomic helper installs the summary only if the content it
                # compacted is still current; otherwise it preserves the newer
                # transcript and appends this exchange to it.
                compacted_summary = None
                if compaction_result and compaction_result.get("success") and compaction_result.get("summary"):
                    compacted_summary = compaction_result["summary"]
                    logger.info("[Agent Memory] Using compacted summary as new base")

                memory_node_id = memory_data["node_id"]
                execution_id = (context or {}).get("execution_id")
                mutation_id = (
                    f"ai-memory:{execution_id}:{node_id}:{memory_node_id}"
                    if execution_id
                    else None
                )
                _current_params, removed_texts, _applied = await append_memory_turns_atomic(
                    self.database,
                    memory_node_id,
                    [("human", prompt), ("ai", response_content)],
                    window_size=int(memory_data.get("window_size", 10)),
                    mutation_id=mutation_id,
                    replacement_content=compacted_summary,
                    expected_content=memory_data.get("memory_content", ""),
                )

                # Store removed messages in long-term vector DB
                if removed_texts and memory_data.get("long_term_enabled"):
                    try:
                        store = await _get_configured_memory_vector_store(
                            session_id,
                            memory_data,
                            self.auth,
                        )
                        if store:
                            await store.add_texts(removed_texts)
                            logger.info(f"[Agent Memory] Archived {len(removed_texts)} messages to long-term store")
                    except Exception as e:
                        logger.warning(f"[Agent Memory] Failed to archive to vector store: {e}")

                logger.info(f"[Agent Memory] Saved markdown to memory node '{memory_node_id}'")

            result = {
                "response": response_content,
                "thinking": thinking_content,
                "thinking_enabled": thinking_config.enabled if thinking_config else False,
                "model": model,
                "provider": provider,
                "agent_type": "loop",
                "iterations": iterations,
                "finish_reason": "stop",
                "timestamp": datetime.now().isoformat(),
                "input": {
                    "prompt": prompt,
                    "system_message": system_message,
                },
            }

            # Add memory info if used
            if session_id:
                result["memory"] = {"session_id": session_id, "history_loaded": history_count}
            if context_runtime is not None:
                result["context"] = {
                    "workflow_id": context_runtime.workflow_id,
                    "generation": context_runtime.generation,
                    "agent_node_id": context_runtime.agent_node_id,
                }

            log_execution_time(logger, "ai_agent_loop", start_time, time.time())
            log_api_call(logger, provider, model, "agent", True)

            return {
                "success": True,
                "node_id": node_id,
                "node_type": "aiAgent",
                "result": result,
                "execution_time": time.time() - start_time,
            }

        except DuplicateToolNameError as e:
            logger.warning("[Agent] Duplicate tool surface rejected: %s", e)
            return {
                "success": False,
                "node_id": node_id,
                "node_type": "aiAgent",
                **e.as_dict(),
                "execution_time": time.time() - start_time,
                "timestamp": datetime.now().isoformat(),
            }

        except NodeUserError as e:
            log_api_call(logger, provider, model, "agent", False, error=str(e))
            raise

        except Exception as e:
            logger.error("[Agent] AI agent execution failed", node_id=node_id, error=str(e))
            log_api_call(logger, provider, model, "agent", False, error=str(e))

            return {
                "success": False,
                "node_id": node_id,
                "node_type": "aiAgent",
                "error": str(e),
                "execution_time": time.time() - start_time,
                "timestamp": datetime.now().isoformat(),
            }

        finally:
            from services.skill_runtime import clear_skill_turn

            await clear_skill_turn(workflow_id or "", str((context or {}).get("execution_id") or ""), node_id)

    async def execute_chat_agent(
        self,
        node_id: str,
        parameters: Dict[str, Any],
        memory_data: Optional[Dict[str, Any]] = None,
        skill_data: Optional[List[Dict[str, Any]]] = None,
        tool_data: Optional[List[Dict[str, Any]]] = None,
        broadcaster=None,
        workflow_id: Optional[str] = None,
        context: Optional[Dict[str, Any]] = None,
        database=None,
    ) -> Dict[str, Any]:
        """Execute Chat Agent - conversational AI with memory, skills, and tool calling.

        Chat Agent supports:
        - Memory (input-memory): Markdown-based conversation history (same as AI Agent)
        - Skills (input-skill): Provide context/instructions via SKILL.md
        - Tools (input-tools): Tool nodes (httpRequest, etc.) for agent tool calling

        Args:
            node_id: The node identifier
            parameters: Node parameters including prompt, model, etc.
            memory_data: Optional memory data from connected SimpleMemory node (markdown-based)
            skill_data: Optional skill configurations from connected skill nodes
            tool_data: Optional tool configurations from connected tool nodes (httpRequest, etc.)
            broadcaster: Optional StatusBroadcaster for real-time UI updates
            workflow_id: Optional workflow ID for scoped status broadcasts
            context: Optional execution context with nodes, edges for nested agent delegation
        """
        start_time = time.time()
        provider = "unknown"
        model = "unknown"

        logger.debug(
            f"[ChatAgent] execute_chat_agent called: node_id={node_id}, workflow_id={workflow_id}, skill_count={len(skill_data) if skill_data else 0}, tool_count={len(tool_data) if tool_data else 0}"
        )
        from services.runtime_tool_context import prepare_native_runtime
        parameters, context, skill_data, tool_data = await prepare_native_runtime(
            database or self.database, node_id, parameters, context, skill_data, tool_data, workflow_id=workflow_id)

        async def broadcast_status(phase: str, details: Dict[str, Any] = None):
            if broadcaster:
                await broadcaster.update_node_status(
                    node_id,
                    "executing",
                    {"phase": phase, "agent_type": "chat_with_skills" if skill_data else "chat", **(details or {})},
                    workflow_id=workflow_id,
                )

        try:
            # Extract parameters
            prompt = parameters.get("prompt", "Hello")
            system_message = parameters.get("system_message", "You are a helpful assistant")

            # Inject skills: personality skills get full instructions, others get brief descriptions
            skill_prompt, has_personality = _build_skill_system_prompt(skill_data, log_prefix="[ChatAgent]")
            if skill_prompt:
                if has_personality:
                    system_message = skill_prompt
                else:
                    system_message = f"{system_message}\n\n{skill_prompt}"

            # Build tools from tool_data using same method as AI Agent
            # This supports all directly connected tool types.
            all_tools = []
            tool_node_configs = {}  # Map tool name to node config (same as AI Agent's tool_configs)
            tool_identities: List[Dict[str, str]] = []
            tool_bindings: List[tuple[Any, Dict[str, Any]]] = []
            from services.skill_runtime import skill_tool_info

            effective_tool_data = unique_node_bindings(tool_data or [])
            progressive_skill_tool = skill_tool_info(skill_data or [], node_id)
            if progressive_skill_tool:
                effective_tool_data.append(progressive_skill_tool)
            if effective_tool_data:
                await broadcast_status("building_tools", {"message": f"Building {len(effective_tool_data)} tool(s)...", "tool_count": len(effective_tool_data)})

                task_manager_bound = any(info.get("node_type") == "taskManager" for info in effective_tool_data)
                durable_delegates = [info for info in effective_tool_data if info.get("delegate_tool_name")]
                if task_manager_bound and durable_delegates:
                    from services.plugin.edge_walker import format_teammate_roster_line

                    teammate_lines = "\n".join(format_teammate_roster_line(info) for info in durable_delegates)
                    system_message += (
                        "\n\n## Durable Team Delegation\n"
                        "All teammate assignments MUST use task_manager with operation='assign_task'. "
                        "Supply title, bounded mission, relevant context, acceptance criteria, and one "
                        "assignee_node_id from the connected list below. Multiple assign_task calls may "
                        "be issued together for parallel queued execution. Never call delegate_to_* "
                        "directly. Review submitted tasks using list_tasks/get_task and accept, retry, "
                        "modify, reassign, or cancel them before the final report. For mutations, copy "
                        "task.id to task_id and task.revision to expected_revision.\n"
                        f"Connected teammates:\n{teammate_lines}"
                    )

                for tool_info in effective_tool_data:
                    if task_manager_bound and tool_info.get("delegate_tool_name"):
                        continue
                    # The same tool building as the AI Agent, for all tool types
                    for tool, config in await node_tools(self, tool_info):
                        all_tools.append(tool)
                        tool_bindings.append((tool, config))
                        tool_identities.append(
                            {
                                "name": tool.name,
                                "node_id": str(config.get("node_id") or tool_info.get("node_id") or ""),
                                "label": str(config.get("label") or tool_info.get("label") or tool_info.get("node_type") or "tool"),
                            }
                        )
                        logger.debug(
                            f"[ChatAgent] Built tool: {tool.name} (type={config.get('node_type')}, node_id={config.get('node_id')})"
                        )

                logger.debug(f"[ChatAgent] Built {len(all_tools)} tools from tool_data")

                # Auto-inject check_delegated_tasks tool when delegation tools present
                if any(tool.name.startswith("delegate_to_") for tool in all_tools):
                    check_info = {
                        "node_type": "_builtin_check_delegated_tasks",
                        "node_id": f"{node_id}_check_tasks",
                        "parameters": {},
                        "label": "Check Delegated Tasks",
                    }
                    check_tool, check_config = await self._build_tool_from_node(check_info)
                    if check_tool:
                        all_tools.append(check_tool)
                        tool_bindings.append((check_tool, check_config))
                        tool_identities.append(
                            {
                                "name": check_tool.name,
                                "node_id": str(check_config.get("node_id") or check_info["node_id"]),
                                "label": str(check_config.get("label") or check_info["label"]),
                            }
                        )
                        logger.debug("[ChatAgent] Auto-injected check_delegated_tasks tool")

                    # Add delegation guidance to system message
                    delegate_names = [tool.name for tool in all_tools if tool.name.startswith("delegate_to_")]
                    system_message += (
                        "\n\n## Agent Delegation\n"
                        "When delegating to sub-agents, use 'task' for the mission directive "
                        "(role and goal) and 'context' for input data the agent needs to work with.\n"
                        f"Available agents: {', '.join(delegate_names)}"
                    )

                ensure_unique_tool_names(tool_identities)
                tool_node_configs.update({tool.name: config for tool, config in tool_bindings})

            logger.debug(f"[ChatAgent] Total tools available: {len(all_tools)}")
            # Debug: log all tool schemas to verify they're correct
            for t in all_tools:
                schema = t.parameters
                logger.debug(f"[ChatAgent] Tool '{t.name}' schema: {schema}")

            # Flatten options collection from frontend
            options = parameters.get("options", {})
            flattened = {**parameters, **options}

            api_key = flattened.get("api_key")
            provider = parameters.get("provider", "openai")
            model = parameters.get("model", "")
            # Strip [FREE] prefix if present (added by OpenRouter model list for display)
            if model.startswith("[FREE] "):
                model = model[7:]

            logger.debug(f"[ChatAgent] Provider: {provider}, Model: {model}")

            # Validate model for provider - use default (DB > config)
            if not model or not is_model_valid_for_provider(model, provider):
                old_model = model
                model = await get_default_model_async(provider, database)
                if old_model:
                    logger.warning(f"Model '{old_model}' invalid for provider '{provider}', using default: {model}")
                else:
                    logger.info(f"No model specified, using default: {model}")

            if not api_key and not await self._gateway_covers(provider):
                _require_saved_endpoint(provider)
                raise ValueError("API key is required for Zeenie")

            # Resolve max_tokens and temperature via model registry
            max_tokens = _resolve_max_tokens(flattened, model, provider)

            # Build thinking config from parameters
            thinking_config = None
            if flattened.get("thinking_enabled"):
                thinking_config = ThinkingConfig(
                    enabled=True,
                    budget=int(flattened.get("thinking_budget", 2048)),
                    effort=flattened.get("reasoning_effort", "medium"),
                    level=flattened.get("thinking_level"),
                    format=flattened.get("reasoning_format", "parsed"),
                )

            temperature = _resolve_temperature(flattened, model, provider, bool(thinking_config and thinking_config.enabled))

            # Broadcast: Initializing
            await broadcast_status("initializing", {"message": f"Initializing {provider} model...", "provider": provider, "model": model, "active_skills": [], "last_skills": [], "last_tool_name": None, "last_capability": None})

            context_runtime = await self._prepare_context(
                node_id=node_id,
                context_data=memory_data,
                execution_context=context,
                workflow_id=workflow_id,
                database=database or self.database,
            )
            if context_runtime is not None:
                memory_data = None

            # Build messages
            messages: List[NativeMessage] = (
                [
                    message
                    for message in context_runtime.history
                    if message.role != "system"
                ]
                if context_runtime is not None
                else []
            )
            if system_message:
                messages.insert(
                    0,
                    NativeMessage(role="system", content=system_message),
                )

            # Load memory history if connected (markdown-based like AI Agent)
            session_id = None
            history_count = 0
            memory_content = None
            if memory_data and memory_data.get("node_id"):
                session_id = memory_data.get("session_id", "default")
                memory_content = memory_data.get("memory_content", "# Conversation History\n\n*No messages yet.*\n")

                await broadcast_status(
                    "loading_memory", {"message": "Loading conversation history...", "session_id": session_id, "has_memory": True}
                )

                # Parse short-term memory from markdown
                history_messages = _parse_memory_markdown(memory_content)
                history_count = len(history_messages)

                # If long-term memory enabled, retrieve relevant context
                if memory_data.get("long_term_enabled"):
                    try:
                        store = await _get_configured_memory_vector_store(
                            session_id,
                            memory_data,
                            self.auth,
                        )
                        if store:
                            k = memory_data.get("retrieval_count", 3)
                            docs = await store.similarity_search(prompt, k=k)
                            if docs:
                                retrieved_context = "\n---\n".join(
                                    d.page_content for d in docs
                                )
                                messages.append(
                                    NativeMessage(
                                        role="system",
                                        content=(
                                            "Relevant past context:\n"
                                            f"{retrieved_context}"
                                        ),
                                    )
                                )
                                logger.info(f"[ChatAgent Memory] Retrieved {len(docs)} relevant memories from long-term store")
                    except Exception as e:
                        logger.debug(f"[ChatAgent Memory] Long-term retrieval skipped: {e}")

                # Add parsed history messages
                messages.extend(history_messages)

                logger.info(f"[ChatAgent Memory] Loaded {history_count} messages from markdown")

                await broadcast_status(
                    "memory_loaded",
                    {"message": f"Loaded {history_count} messages from memory", "session_id": session_id, "history_count": history_count},
                )

            # Add current prompt
            messages.append(NativeMessage(role="user", content=prompt))

            # Broadcast: Invoking LLM
            await broadcast_status(
                "invoking_llm",
                {
                    "message": "Generating response...",
                    "has_memory": session_id is not None,
                    "history_count": history_count,
                    "skill_count": len(skill_data) if skill_data else 0,
                },
            )

            # Execute with or without tools
            thinking_content = None
            iterations = 1

            if all_tools:
                # Use the agent loop for tool execution (like AI Agent)
                logger.debug(f"[ChatAgent] Using agent loop with {len(all_tools)} tools")

                # Create tool executor callback. Tool-node status lifecycle
                # is owned by ``handlers.tools.execute_tool`` (single source
                # of truth, shared with execute_agent's tool_executor).
                async def chat_tool_executor(tool_name: str, tool_args: Dict) -> Any:
                    """Execute a tool by name using handlers/tools.py (same as AI Agent)."""
                    from services.handlers.tools import execute_tool

                    logger.debug(f"[ChatAgent] Executing tool: {tool_name}, args={tool_args}")

                    config = tool_node_configs.get(tool_name, {})
                    tool_node_id = config.get("node_id")
                    logger.debug(
                        f"[ChatAgent] Tool config: node_id={tool_node_id}, node_type={config.get('node_type')}, workflow_id={workflow_id}"
                    )

                    await broadcast_status(
                        "executing_tool",
                        {"message": f"Executing tool: {tool_name}", "tool_name": tool_name},
                    )
                    if broadcaster and tool_name and tool_name != "Skill":
                        await broadcaster.broadcast_agent_capability(
                            node_id,
                            capability_kind="tool",
                            capability_name=tool_name,
                            state="started",
                            workflow_id=workflow_id,
                            execution_id=str((context or {}).get("execution_id") or "") or None,
                            root_execution_id=str((context or {}).get("root_execution_id") or "") or None,
                            target_node_id=str(tool_node_id or "") or None,
                            provider=provider,
                            invocation_source="native",
                        )

                    # Inject services + graph context so execute_tool can scope its
                    # broadcasts and nested agents can execute with their own tools.
                    config["workflow_id"] = workflow_id
                    config["ai_service"] = self
                    config["database"] = self.database
                    config["parent_node_id"] = node_id
                    config["provider"] = provider
                    config["auto_rebind_tools"] = auto_rebind_enabled
                    if context:
                        if context.get("pi_harness_version") == 1:
                            from services.temporal.pi_inline_delegation import forward_inline_scope
                            config.update(forward_inline_scope(context))
                        config["run_scope"] = context.get("run_scope")
                        config["generation"] = context.get("generation")
                        config["parameter_snapshot"] = context.get("parameter_snapshot", {})
                        config["employee_job_id"] = context.get("employee_job_id")
                        config["team_task_id"] = context.get("team_task_id")
                        config["team_execution_id"] = context.get("team_execution_id")
                        for scope_key in ("data_scope_id", "context_execution_id", "context_session_id", "session_id", "graphVersion", "outputs", "pi_harness_version", "runtime_behavior_version"):
                            if scope_key in context:
                                config[scope_key] = context[scope_key]
                        config["nodes"] = context.get("nodes", [])
                        config["edges"] = context.get("edges", [])
                        config["workspace_dir"] = context.get("workspace_dir", "")
                        config["user_id"] = context.get("user_id", "owner")
                        # Stable per-run id so session-keyed tools (browser)
                        # reuse one instance across the agent loop.
                        config["execution_id"] = context.get("execution_id")
                        config["_browser_task_id"] = context.get("_browser_task_id")
                        config["_browser_owner"] = (context.get("browser_bindings") or {}).get(str(tool_node_id))
                        config["root_execution_id"] = context.get("root_execution_id")
                        config["delegation_depth"] = context.get("delegation_depth", 0)
                        config["team_id"] = context.get("team_id")
                        config["max_concurrent_subagents"] = context.get("max_concurrent_subagents", 3)
                        config["max_delegation_depth"] = context.get("max_delegation_depth", 2)

                    try:
                        from services.employees.permissions import assert_runtime_access
                        await assert_runtime_access(self.database, workflow_id, str(tool_node_id or ""), str(config.get("node_type") or ""), config)
                        result = await execute_tool(tool_name, tool_args, config)
                        await broadcast_status(
                            "tool_completed",
                            {"message": f"Tool completed: {tool_name}", "tool_name": tool_name},
                        )
                        if broadcaster and tool_name and tool_name != "Skill":
                            await broadcaster.broadcast_agent_capability(
                                node_id,
                                capability_kind="tool",
                                capability_name=tool_name,
                                state="completed",
                                workflow_id=workflow_id,
                                execution_id=str((context or {}).get("execution_id") or "") or None,
                                root_execution_id=str((context or {}).get("root_execution_id") or "") or None,
                                target_node_id=str(tool_node_id or "") or None,
                                provider=provider,
                                invocation_source="native",
                            )
                        logger.debug(f"[ChatAgent] Tool executed successfully: {tool_name}")
                        return result
                    except Exception as e:
                        logger.error(f"[ChatAgent] Tool execution failed: {tool_name}", error=str(e))
                        await broadcast_status(
                            "tool_completed",
                            {"message": f"Tool failed: {tool_name}", "tool_name": tool_name, "tool_failed": True},
                        )
                        if broadcaster and tool_name and tool_name != "Skill":
                            await broadcaster.broadcast_agent_capability(
                                node_id,
                                capability_kind="tool",
                                capability_name=tool_name,
                                state="failed",
                                workflow_id=workflow_id,
                                execution_id=str((context or {}).get("execution_id") or "") or None,
                                root_execution_id=str((context or {}).get("root_execution_id") or "") or None,
                                target_node_id=str(tool_node_id or "") or None,
                                provider=provider,
                                invocation_source="native",
                                error_code=type(e).__name__,
                            )
                        return e.as_dict() if isinstance(e, NodeUserError) else {"error": str(e)}

                # Auto-rebind toggle + recursion_limit override: same
                # machinery as ``execute_agent``.
                auto_rebind_enabled = True
                user_recursion_limit: Optional[int] = None
                tool_output_limit = resolve_tool_output_limit(None, self.settings)
                try:
                    user_settings = await self.database.get_user_settings()
                    if user_settings is not None:
                        auto_rebind_enabled = bool(
                            user_settings.get("auto_rebind_tools_after_canvas_change", True)
                        )
                        _raw_limit = user_settings.get("agent_recursion_limit")
                        if isinstance(_raw_limit, int) and _raw_limit > 0:
                            user_recursion_limit = _raw_limit
                        tool_output_limit = resolve_tool_output_limit(
                            user_settings, self.settings
                        )
                except Exception as exc:  # noqa: BLE001 — defensive read
                    logger.debug("[ChatAgent] user_settings read failed: %s", exc)

                async def _rebind_from_operations(operations: List[Dict[str, Any]]) -> List[Any]:
                    """Mirror of execute_agent._rebind_from_operations — see that
                    function for the contract. We can't dedupe cleanly because
                    the two agent paths capture different closure variables
                    (``tool_configs`` vs ``tool_node_configs``)."""
                    from services.node_registry import get_node_class

                    saved_workflow = await self.database.get_workflow(workflow_id) if workflow_id else None
                    saved_graph = getattr(saved_workflow, "data", None) or {}
                    if context is not None and saved_graph:
                        admitted_graph = extend_runtime_graph(context, saved_graph, operations)
                        context["nodes"] = admitted_graph["nodes"]
                        context["edges"] = admitted_graph["edges"]
                    bound = {identity["node_id"] for identity in tool_identities}
                    new_bindings: List[tuple[Any, Dict[str, Any]]] = []
                    for op in operations:
                        if op.get("type") != "add_node":
                            continue
                        if not rebind_allowed(op, node_id, nodes=(context or {}).get("nodes", []), edges=(context or {}).get("edges", []), operations=() if saved_graph else operations):
                            continue
                        node_type = op.get("node_type")
                        if not node_type:
                            continue
                        cls = get_node_class(node_type)
                        if cls is None:
                            continue
                        # Match the catalogue filter — pure ToolNode OR
                        # dual-purpose ActionNode (usable_as_tool=True),
                        # excluding chat models and the Skills node
                        # (masterSkill feeds input-skill, never an LLM
                        # tool). Without this the rebind silently drops
                        # twitterSearch / googleGmail / pythonExecutor etc.
                        _kind = getattr(cls, "component_kind", "")
                        if not is_runtime_tool(cls):
                            continue
                        if (getattr(cls, "ui_hints", None) or {}).get("isMasterSkillEditor"):
                            continue
                        tool_info = {
                            "node_id": op.get("minted_id") or op.get("client_ref") or f"new_{node_type}",
                            "node_type": node_type,
                            "parameters": op.get("parameters") or {},
                            "label": op.get("label") or node_type,
                        }
                        if tool_info["node_id"] in bound:
                            continue
                        tool_info = bind_runtime_context(tool_info, context or {}, node_id)
                        try:
                            built = await node_tools(self, tool_info)
                        except Exception as exc:  # noqa: BLE001
                            logger.warning(
                                "[ChatAgent] rebind: building tools raised for %s: %s",
                                node_type,
                                exc,
                            )
                            continue
                        if not built:
                            continue
                        new_bindings.extend((tool, tool_config or tool_info) for tool, tool_config in built)
                        bound.add(tool_info["node_id"])

                    new_identities = [
                        {
                            "name": tool.name,
                            "node_id": str(config.get("node_id") or ""),
                            "label": str(config.get("label") or config.get("node_type") or "tool"),
                        }
                        for tool, config in new_bindings
                    ]
                    ensure_unique_tool_names([*tool_identities, *new_identities])
                    for tool, tool_config in new_bindings:
                        tool_node_configs[tool.name] = tool_config
                    tool_identities.extend(new_identities)
                    return [tool for tool, _ in new_bindings]

                # Run the agent loop. See ``execute_agent`` for the
                # rationale on ``recursion_limit`` + the truncation
                # behaviour on hit. Precedence: UserSettings > env.
                from services.model_registry import get_model_registry

                if user_recursion_limit is not None:
                    recursion_limit = user_recursion_limit
                else:
                    recursion_limit = int(get_model_registry().get_agent_defaults()["recursion_limit"])

                async def _emit_progress(iter_count: int) -> None:
                    if broadcaster:
                        await broadcaster.broadcast_agent_progress(
                            node_id,
                            workflow_id=workflow_id,
                            iteration=iter_count,
                            max_iterations=recursion_limit,
                        )

                final_state = await run_native_agent_loop(
                    self.chat_unifier,
                    **native_observer_options(context, node_id, workflow_id, provider, model),
                    provider=provider,
                    api_key=api_key,
                    model=model,
                    temperature=temperature,
                    max_tokens=max_tokens,
                    thinking=thinking_config,
                    initial_messages=messages,
                    tools=all_tools,
                    tool_executor=chat_tool_executor,
                    max_iterations=recursion_limit,
                    progress_callback=_emit_progress if broadcaster else None,
                    rebind_from_operations=_rebind_from_operations if auto_rebind_enabled else None,
                    roster_after_rebind=lambda: delegation_roster(tool_identities),
                    conversation_saver=(
                        context_runtime.save
                        if context_runtime is not None
                        else None
                    ),
                    tool_output_limit=tool_output_limit,
                )

                # Extract response
                all_messages = final_state["messages"]
                ai_response = all_messages[-1] if all_messages else None

                if not ai_response or not hasattr(ai_response, "content"):
                    raise ValueError("No response generated from agent")

                response_content = self._extract_text_content(ai_response.content, ai_response)
                iterations = final_state.get("iteration", 1)
                thinking_content = final_state.get("thinking_content")
            else:
                final_state = await run_native_agent_loop(
                    self.chat_unifier,
                    **native_observer_options(context, node_id, workflow_id, provider, model),
                    provider=provider,
                    api_key=api_key,
                    model=model,
                    temperature=temperature,
                    max_tokens=max_tokens,
                    thinking=thinking_config,
                    initial_messages=messages,
                    max_iterations=1,
                    conversation_saver=(
                        context_runtime.save
                        if context_runtime is not None
                        else None
                    ),
                )
                all_messages = final_state["messages"]
                ai_response = all_messages[-1] if all_messages else None
                if ai_response is None:
                    raise ValueError("No response generated from agent")
                response_content = self._extract_text_content(
                    ai_response.content,
                    ai_response,
                )
                thinking_content = final_state.get("thinking_content")

            logger.info(f"[ChatAgent] Response generated, thinking={'yes' if thinking_content else 'no'}, iterations={iterations}")

            # Track token usage if memory connected (for compaction service)
            # Also triggers compaction if threshold exceeded.
            response_msg = final_state.get("usage") or ai_response
            compaction_result = None
            if session_id and response_msg:
                compaction_result = await self._track_token_usage(
                    session_id=session_id,
                    node_id=node_id,
                    provider=provider,
                    model=model,
                    ai_response=response_msg,
                    all_messages=all_messages,
                    broadcaster=broadcaster,
                    workflow_id=workflow_id,
                    memory_content=memory_content,
                    api_key=api_key,
                    memory_node_id=memory_data.get("node_id") if memory_data else None,
                )
                _accumulate_compaction_usage(
                    final_state, compaction_result
                )

            # Save to memory if connected (markdown-based like AI Agent)
            if (
                memory_data
                and memory_data.get("node_id")
                and is_valid_message_content(prompt)
                and is_valid_message_content(response_content)
            ):
                await broadcast_status(
                    "saving_memory", {"message": "Saving to conversation memory...", "session_id": session_id, "has_memory": True}
                )

                from services.memory.runtime import append_memory_turns_atomic

                compacted_summary = None
                if compaction_result and compaction_result.get("success") and compaction_result.get("summary"):
                    compacted_summary = compaction_result["summary"]
                    logger.info("[ChatAgent Memory] Using compacted summary as new base")

                memory_node_id = memory_data["node_id"]
                execution_id = (context or {}).get("execution_id")
                mutation_id = (
                    f"chat-memory:{execution_id}:{node_id}:{memory_node_id}"
                    if execution_id
                    else None
                )
                _current_params, removed_texts, _applied = await append_memory_turns_atomic(
                    self.database,
                    memory_node_id,
                    [("human", prompt), ("ai", response_content)],
                    window_size=int(memory_data.get("window_size", 10)),
                    mutation_id=mutation_id,
                    replacement_content=compacted_summary,
                    expected_content=memory_content,
                )

                # Store removed messages in long-term vector DB
                if removed_texts and memory_data.get("long_term_enabled"):
                    try:
                        store = await _get_configured_memory_vector_store(
                            session_id,
                            memory_data,
                            self.auth,
                        )
                        if store:
                            await store.add_texts(removed_texts)
                            logger.info(f"[ChatAgent Memory] Archived {len(removed_texts)} messages to long-term store")
                    except Exception as e:
                        logger.warning(f"[ChatAgent Memory] Failed to archive to vector store: {e}")

                logger.info(f"[ChatAgent Memory] Saved markdown to memory node '{memory_node_id}'")

            # Determine agent type based on configuration
            agent_type = "chat"
            if skill_data and all_tools:
                agent_type = "chat_with_skills_and_tools"
            elif skill_data:
                agent_type = "chat_with_skills"
            elif all_tools:
                agent_type = "chat_with_tools"

            result = {
                "response": response_content,
                "thinking": thinking_content,
                "thinking_enabled": thinking_config.enabled if thinking_config else False,
                "model": model,
                "provider": provider,
                "agent_type": agent_type,
                "iterations": iterations,
                "finish_reason": "stop",
                "timestamp": datetime.now().isoformat(),
                "input": {
                    "prompt": prompt,
                    "system_message": system_message,
                },
            }

            if session_id:
                result["memory"] = {"session_id": session_id, "history_loaded": history_count}
            if context_runtime is not None:
                result["context"] = {
                    "workflow_id": context_runtime.workflow_id,
                    "generation": context_runtime.generation,
                    "agent_node_id": context_runtime.agent_node_id,
                }

            if skill_data:
                result["skills"] = {
                    "connected": [s.get("skill_name", s.get("node_type", "")) for s in skill_data],
                    "count": len(skill_data),
                }

            if all_tools:
                result["tools"] = {"connected": [t.name for t in all_tools], "count": len(all_tools)}

            log_execution_time(logger, "chat_agent", start_time, time.time())
            log_api_call(logger, provider, model, "chat_agent", True)

            return {
                "success": True,
                "node_id": node_id,
                "node_type": "chatAgent",
                "result": result,
                "execution_time": time.time() - start_time,
            }

        except DuplicateToolNameError as e:
            logger.warning("[ChatAgent] Duplicate tool surface rejected: %s", e)
            return {
                "success": False,
                "node_id": node_id,
                "node_type": "chatAgent",
                **e.as_dict(),
                "execution_time": time.time() - start_time,
                "timestamp": datetime.now().isoformat(),
            }

        except NodeUserError as e:
            log_api_call(logger, provider, model, "chat_agent", False, error=str(e))
            raise

        except Exception as e:
            logger.error("[ChatAgent] Execution failed", node_id=node_id, error=str(e))
            log_api_call(logger, provider, model, "chat_agent", False, error=str(e))

            return {
                "success": False,
                "node_id": node_id,
                "node_type": "chatAgent",
                "error": str(e),
                "execution_time": time.time() - start_time,
                "timestamp": datetime.now().isoformat(),
            }

        finally:
            from services.skill_runtime import clear_skill_turn

            await clear_skill_turn(workflow_id or "", str((context or {}).get("execution_id") or ""), node_id)

    async def _build_tool_from_node(self, tool_info: Dict[str, Any]) -> tuple:
        """Convert a node configuration into a provider-neutral tool spec.

        Uses database-stored schema as source of truth if available, otherwise
        falls back to dynamic schema generation.

        Tool name + description resolution chain (Wave 12 D5):
          1. DB-stored schema (per-node override via UI)
          2. ``cls.tool_name`` / ``cls.tool_description`` ClassVars on the
             plugin class. ``tool_description`` falls back to
             ``cls.description`` when empty.
          3. ``_PSEUDO_TOOL_FALLBACK`` for built-in pseudo-types that have
             no plugin class (``_builtin_check_delegated_tasks``)
          4. ``node_params.get('tool_name')`` / ``...tool_description``
             (per-node override declared as a Pydantic field on the plugin's
             Params model — e.g. brave_search / serper_search / perplexity).
          5. Last-resort default: ``f"tool_{label}"`` / ``f"Execute {label}"``

        Args:
            tool_info: Dict containing node_id, node_type, parameters, and label

        Returns:
            Tuple of (AgentToolSpec, config_dict) or (None, None) on failure
        """
        # Built-in / aggregator pseudo-types — no plugin class, no ClassVar.
        # These must stay as an explicit fallback dict (Wave 12 D5).
        _PSEUDO_TOOL_FALLBACK = {
            "_builtin_check_delegated_tasks": (
                "check_delegated_tasks",
                "Check status and retrieve results of previously delegated tasks.",
            ),
            "_builtin_skill": (
                "Skill",
                "Load a connected skill or read/search one of its declared text resources on demand.",
            ),
        }

        def _resolve_default_tool_name_description(node_type: str) -> tuple:
            """Resolve ``(tool_name, tool_description)`` via the post-D5 chain.

            ``tool_description`` falls back to ``cls.description`` when the
            plugin doesn't override it — only ~15-20 of the 68 plugins need
            an LLM-tuned description distinct from the human-facing one
            (writeTodos, pythonExecutor, the 16 specialized agents,
            stripeAction, ...). The rest share their existing
            ``description``.

            Returns ``(None, None)`` when the node_type matches no entry —
            callers fall through to ``node_params`` then ``f"tool_{label}"``.
            """
            from services.node_registry import get_node_class

            node_cls = get_node_class(node_type)
            if node_cls is not None:
                cv_name = (getattr(node_cls, "tool_name", "") or "").strip()
                cv_desc = (getattr(node_cls, "tool_description", "") or "").strip()
                if cv_name:
                    # tool_description falls back to the plugin's regular
                    # ``description`` ClassVar (avoids duplicating the same
                    # text in two ClassVars on most plugins).
                    return cv_name, cv_desc or (getattr(node_cls, "description", "") or "").strip() or None
            pseudo = _PSEUDO_TOOL_FALLBACK.get(node_type)
            if pseudo is not None:
                return pseudo
            return None, None

        try:
            node_type = tool_info.get("node_type", "")
            node_params = tool_info.get("parameters", {})
            node_label = tool_info.get("label", node_type)
            node_id = tool_info.get("node_id", "")
            connected_services = tool_info.get("connected_services", [])

            default_tool_name, default_tool_description = _resolve_default_tool_name_description(node_type)
            from services.node_registry import get_node_class

            plugin_cls = get_node_class(node_type)
            schema_locked = bool(
                plugin_cls is not None
                and getattr(plugin_cls, "tool_schema_locked", False)
            )
            # Team-handle expansion assigns a per-node identity to custom
            # aiAgent delegates. It intentionally outranks schemas and class
            # defaults because those are type-wide and would collide.
            delegated_name = tool_info.get("delegate_tool_name")

            # Check database for stored schema (source of truth)
            db_schema = await self.database.get_tool_schema(node_id) if node_id else None

            if schema_locked:
                # Security-sensitive first-party tools own both their
                # canonical name and invocation schema. A stale/custom row
                # from the generic Tool editor must not replace that
                # contract.
                tool_name = default_tool_name or node_type
                tool_description = (
                    default_tool_description or f"Execute {node_label} node"
                )
            elif db_schema:
                # Use database schema as source of truth
                logger.debug(f"[Agent] Using DB schema for tool node {node_id}")
                tool_name = delegated_name or db_schema.get("tool_name", default_tool_name or f"tool_{node_label}")
                tool_description = db_schema.get("tool_description", default_tool_description or f"Execute {node_label}")
                # Use stored connected_services if available (for toolkit nodes)
                if db_schema.get("connected_services"):
                    connected_services = db_schema["connected_services"]
            else:
                # Fall back to dynamic generation from node params
                tool_name = delegated_name or (
                    node_params.get("tool_name") or default_tool_name or f"tool_{node_label}".replace(" ", "_").replace("-", "_").lower()
                )
                tool_description = node_params.get("tool_description") or default_tool_description or f"Execute {node_label} node"

            # For AI Agent nodes, enhance description with child agent's tool capabilities
            # This allows parent agent to know what the child agent can do
            from services.workspace_capabilities import is_registered_agent

            if is_registered_agent(node_type):
                child_tools = tool_info.get("child_tools", [])
                if child_tools:
                    # Build capability description from child's connected tools
                    capability_descriptions = []
                    for child_tool in child_tools:
                        child_type = child_tool.get("node_type", "")
                        child_label = child_tool.get("label", child_type)
                        # Resolve via the post-D5 chain (ClassVar → pseudo → legacy)
                        _, child_desc = _resolve_default_tool_name_description(child_type)
                        if not child_desc:
                            child_desc = f"Use {child_label}"
                        capability_descriptions.append(f"- {child_label}: {child_desc}")

                    capabilities_text = "\n".join(capability_descriptions)
                    tool_description = (
                        f"Delegate tasks to '{node_label}' agent. "
                        f"This agent has the following capabilities:\n{capabilities_text}\n"
                        f"Call ONCE per task, returns task_id. Agent works in background."
                    )
                    logger.info(f"[Agent] Enhanced tool description for {node_type} with {len(child_tools)} child tools")

            # Clean tool name (providers require alphanumeric + underscores)
            import re

            tool_name = re.sub(r"[^a-zA-Z0-9_]", "_", tool_name)

            # Build schema based on node type.
            # If DB has schema_config, use it to build custom schema, otherwise use dynamic
            schema_params = dict(node_params)
            if connected_services:
                schema_params["connected_services"] = connected_services
            if (
                not schema_locked
                and db_schema
                and db_schema.get("schema_config")
            ):
                schema_params["db_schema_config"] = db_schema["schema_config"]
            schema = self._get_tool_schema(node_type, schema_params)

            # Build config dict - include connected_services for toolkit nodes
            config = {
                "node_type": node_type,
                "node_id": node_id,
                "parameters": node_params,
                "label": node_label,
                "connected_services": connected_services,  # Pass through for execution
            }

            from services.plugin.tool import inline_schema_refs

            parameters = inline_schema_refs(schema.model_json_schema())
            tool = AgentToolSpec(
                definition=ToolDef(
                    name=tool_name,
                    description=tool_description,
                    parameters=parameters,
                ),
                args_schema=schema,
                execution=config,
            )

            logger.debug(f"[Agent] Built tool '{tool_name}' with node_id={node_id}")
            return tool, config

        except Exception as e:
            logger.error(f"[Agent] Failed to build tool from node: {e}")
            return None, None

    def _get_tool_schema(self, node_type: str, params: Dict[str, Any]) -> Type[BaseModel]:
        """Get Pydantic schema for tool based on node type.

        Uses db_schema_config from database if available (source of truth),
        otherwise falls back to built-in schema definitions.

        Args:
            node_type: The node type (e.g., 'calculatorTool', 'httpRequest')
            params: Node parameters, may include db_schema_config from database

        Returns:
            Pydantic BaseModel class for the tool's arguments
        """
        from pydantic import BaseModel, Field

        # Plugin-locked ToolInput is authoritative even when an older client
        # left a custom ToolSchema row in the database.
        from services.node_registry import get_node_class

        plugin_cls = get_node_class(node_type)
        if plugin_cls is not None and getattr(plugin_cls, "tool_schema_locked", False):
            tool_input_model = getattr(plugin_cls, "tool_input_model", None)
            return tool_input_model() if callable(tool_input_model) else plugin_cls.Params

        # Check if we have a database-stored schema config (source of truth)
        db_schema_config = params.get("db_schema_config")
        if db_schema_config:
            return self._build_schema_from_config(db_schema_config)

        # Agent delegation schema — MUST fire before the plugin fast-path.
        # When an agent is connected to another agent's input-tools handle, we
        # expose a (task, context) schema for delegation rather than the agent's
        # own Params (which would leak provider/model/prompt into the parent LLM).
        _AGENT_DELEGATION_TYPES = (
            "aiAgent",
            "chatAgent",
            "android_agent",
            "coding_agent",
            "web_agent",
            "browser_agent",
            "task_agent",
            "social_agent",
            "travel_agent",
            "tool_agent",
            "productivity_agent",
            "payments_agent",
            "consumer_agent",
            "autonomous_agent",
            "orchestrator_agent",
            "ai_employee",
            "rlm_agent",
            "claude_code_agent",
        )
        if node_type in _AGENT_DELEGATION_TYPES:
            agent_label = params.get("label", node_type)

            class DelegateToAgentSchema(BaseModel):
                """Delegate a task to another AI Agent (non-blocking).

                The child agent works independently in the background.
                The 'task' becomes the agent's mission directive (system message).
                The 'context' becomes the agent's input data (user prompt).
                Returns a task_id immediately. Use 'check_delegated_tasks'
                tool to check status and retrieve results when ready.
                """

                task: str = Field(
                    description=f"The mission directive for '{agent_label}'. Describe the role and goal clearly, e.g. 'You are a coding assistant. Write a Python script that processes the given CSV data.'"
                )
                context: Optional[str] = Field(
                    default=None,
                    description="Input data or specific details the agent needs to work with, e.g. file contents, user requirements, or parameters",
                )

            return DelegateToAgentSchema

        if node_type == "_builtin_skill":
            from typing import Literal

            class SkillInvocationSchema(BaseModel):
                action: Literal["load", "read_resource", "search_resource"] = Field(
                    default="load", description="Load instructions, read a bounded resource page, or search a resource."
                )
                skill_name: str = Field(description="Exact connected skill name from Available Skills.")
                path: Optional[str] = Field(default=None, description="Declared references/<file> or scripts/<file> path.")
                query: Optional[str] = Field(default=None, description="Case-insensitive search query for search_resource.")
                cursor: int = Field(default=0, ge=0, description="Pagination cursor.")
                limit: int = Field(default=4000, ge=1, le=16000, description="Bounded character or match limit.")

            return SkillInvocationSchema

        # Built-in check tool for delegation result retrieval (no plugin).
        if node_type == "_builtin_check_delegated_tasks":

            class CheckDelegatedTasksSchema(BaseModel):
                """Check on previously delegated tasks and retrieve their results.

                Call this to see if delegated agents have completed their work.
                Returns status and results for each task.
                """

                task_ids: Optional[List[str]] = Field(
                    default=None, description="Specific task IDs to check. Omit to get ALL delegated tasks."
                )

            return CheckDelegatedTasksSchema

        # Wave 11.B.1 plugin fast-path: if this node_type is a registered
        # BaseNode subclass, use its Pydantic Params model directly. Every
        # AI-tool-usable plugin is covered by this lookup (contract invariant
        # test_fast_path_covers_every_plugin_tool). Wave 11.D.13 stripped the
        # per-type ad-hoc schemas that used to live below this gate.
        if plugin_cls is not None and hasattr(plugin_cls, "Params"):
            tool_input_model = getattr(plugin_cls, "tool_input_model", None)
            if callable(tool_input_model):
                return tool_input_model()
            return plugin_cls.Params

        # Generic schema for other nodes
        class GenericToolSchema(BaseModel):
            """Generic schema for tool arguments."""

            input: str = Field(description="Input data for the tool")

        return GenericToolSchema

    def _build_schema_from_config(self, schema_config: Dict[str, Any]) -> Type[BaseModel]:
        """Build a Pydantic schema from database-stored configuration.

        Schema config format:
        {
            "description": "Schema description",
            "fields": {
                "field_name": {
                    "type": "string" | "number" | "boolean" | "object" | "array",
                    "description": "Field description",
                    "required": True | False,
                    "default": <optional default value>,
                    "enum": [<optional enum values>]
                }
            }
        }
        """
        from pydantic import Field, create_model

        fields_config = schema_config.get("fields", {})
        schema_description = schema_config.get("description", "Tool arguments schema")

        # Build field annotations and defaults
        annotations = {}
        field_defaults = {}

        TYPE_MAP = {
            "string": str,
            "number": float,
            "integer": int,
            "boolean": bool,
            "object": Dict[str, Any],
            "array": list,
        }

        for field_name, field_config in fields_config.items():
            field_type_str = field_config.get("type", "string")
            field_type = TYPE_MAP.get(field_type_str, str)
            field_description = field_config.get("description", "")
            is_required = field_config.get("required", True)
            default_value = field_config.get("default")
            enum_values = field_config.get("enum")

            # Handle optional fields
            if not is_required:
                field_type = Optional[field_type]

            annotations[field_name] = field_type

            # Build Field with description and enum if provided
            field_kwargs = {"description": field_description}
            if enum_values:
                # For enums, include in description since Pydantic Field doesn't support enum directly
                field_kwargs["description"] = f"{field_description} Options: {', '.join(str(v) for v in enum_values)}"

            if default_value is not None:
                field_defaults[field_name] = Field(default=default_value, **field_kwargs)
            elif not is_required:
                field_defaults[field_name] = Field(default=None, **field_kwargs)
            else:
                field_defaults[field_name] = Field(**field_kwargs)

        # Create dynamic Pydantic model
        DynamicSchema = create_model(
            "DynamicToolSchema", __doc__=schema_description, **{name: (annotations[name], field_defaults[name]) for name in annotations}
        )

        return DynamicSchema