Skip to content

"Vibe-Trading: Your Personal Trading Agent"

44.6 KB
Raw Blame
"""Connector-first trading tools.

Tools take an optional ``connection`` profile id. If omitted, they use the
selected profile from ``~/.vibe-trading/trading-connections.json``.
"""

from __future__ import annotations

import json
import math
from typing import Any

from src.agent.tools import BaseTool
from src.tools._arguments import boolean_argument
from src.trading.profiles import (
    list_profiles,
    load_selected_profile_id,
    profile_by_id,
    save_selected_profile_id,
)
from src.trading.onboarding import onboarding_dict
from src.trading.service import (
    cancel_close_order,
    cancel_order,
    check_connection,
    close_position,
    edit_position_stops,
    etoro_copy_close,
    etoro_copy_poll,
    etoro_copy_precheck,
    etoro_copy_start,
    get_account,
    get_acc_cash_flow,
    get_capital_distribution,
    get_capital_flow,
    get_earnings_calendar,
    get_financials,
    get_history,
    get_history_deals,
    get_open_orders,
    get_positions,
    get_quote,
    get_rehab,
    place_order,
    search_instruments,
)


def _json_result(payload: dict[str, Any]) -> str:
    return json.dumps(payload, ensure_ascii=False)


def _connection(value: Any) -> str | None:
    if value is None:
        return None
    text = str(value).strip()
    return text or None


class InvalidTradingArgument(ValueError):
    """A numeric trading argument was supplied but is malformed or non-finite."""


def _brief(value: Any) -> str:
    """Render a rejected argument for an error message without ever raising.

    ``repr()`` is not total: an int with more than 4300 digits raises
    ``ValueError`` under Python's int→str limit. An order tool must not fail to
    describe why it refused, so fall back to the type name.

    Args:
        value: The rejected argument value.

    Returns:
        A short, printable description of the value.
    """
    try:
        text = repr(value)
    except Exception:  # noqa: BLE001 — building an error message must never fail
        return f"<unprintable {type(value).__name__}>"
    return text if len(text) <= 80 else f"{text[:77]}..."


def _finite_float(value: Any, field: str) -> float:
    """Convert a supplied numeric argument to a finite float.

    Args:
        value: Raw argument value (already known to be present).
        field: Argument name, used in the error message.

    Returns:
        The value as a finite float.

    Raises:
        InvalidTradingArgument: If the value is not numeric, or is NaN/Infinity.
            Trading tools are action-bearing, so a malformed size/price/port is
            rejected outright rather than coerced to a default.
    """
    try:
        number = float(value)
    except (TypeError, ValueError, OverflowError):
        raise InvalidTradingArgument(f"{field} must be a finite number, got {_brief(value)}") from None
    if not math.isfinite(number):
        raise InvalidTradingArgument(f"{field} must be a finite number, got {_brief(value)}")
    return number


def _int_or_none(value: Any, field: str = "value") -> int | None:
    """Coerce an optional whole-number argument, rejecting malformed input.

    Args:
        value: Raw argument value; ``None`` and ``""`` mean "not supplied".
        field: Argument name, used in the error message.

    Returns:
        The integer value, or ``None`` when the argument was not supplied.

    Raises:
        InvalidTradingArgument: If the value is present but not a finite whole
            number.
    """
    if value is None or value == "":
        return None
    number = _finite_float(value, field)
    if number != int(number):
        raise InvalidTradingArgument(f"{field} must be a whole number, got {_brief(value)}")
    return int(number)


def _num_or_none(value: Any, field: str = "value") -> float | None:
    """Coerce an optional numeric argument, rejecting malformed input.

    Args:
        value: Raw argument value; ``None`` and ``""`` mean "not supplied".
        field: Argument name, used in the error message.

    Returns:
        The float value, or ``None`` when the argument was not supplied.

    Raises:
        InvalidTradingArgument: If the value is present but not a finite number.
    """
    if value is None or value == "":
        return None
    return _finite_float(value, field)


TRADING_COMMON_PARAMETERS = {
    "connection": {
        "type": "string",
        "description": "Trading connector profile id, e.g. ibkr-paper-local or robinhood-live-mcp. Defaults to the selected profile.",
    },
    "connection_id": {
        "type": "string",
        "description": "Optional local read-only connection instance id. Credentials are loaded from the OS vault and never passed through MCP.",
    },
    "host": {
        "type": "string",
        "description": "Optional local TWS/Gateway host override for local profiles.",
    },
    "port": {
        "type": "integer",
        "description": "Optional local TWS/Gateway port override for local profiles.",
    },
    "client_id": {
        "type": "integer",
        "description": "Optional local TWS/Gateway client id override for local profiles.",
    },
    "market_type": {
        "type": "string",
        "enum": ["spot", "usdm"],
        "description": ("Optional Binance read market. USD-M is accepted only by the live read-only Binance profile."),
    },
    "observation_absolute_tolerance": {
        "type": "number",
        "minimum": 0,
        "description": "Optional USD-M sequential-read coherence tolerance.",
    },
    "account": {
        "type": "string",
        "description": "Optional account code filter when supported by the connector.",
    },
}

ETORO_CREDENTIAL_PARAMETERS = {
    "api_key": {
        "type": "string",
        "description": "Optional eToro Public API key override.",
    },
    "user_key": {
        "type": "string",
        "description": "Optional eToro user key override.",
    },
}


ETORO_TOOL_PARAMETERS = {**TRADING_COMMON_PARAMETERS, **ETORO_CREDENTIAL_PARAMETERS}


def _overrides(kwargs: dict[str, Any]) -> dict[str, Any]:
    """Build the local-connector override dict, rejecting malformed numerics.

    Args:
        kwargs: Raw tool arguments.

    Returns:
        Override mapping with ``None`` for every unsupplied field.

    Raises:
        InvalidTradingArgument: If ``port`` or ``client_id`` is supplied but
            malformed. Silently dropping them would connect to a different
            terminal than the caller asked for.
    """
    return {
        "connection_id": _connection(kwargs.get("connection_id")),
        "host": _connection(kwargs.get("host")),
        "port": _int_or_none(kwargs.get("port"), "port"),
        "client_id": _int_or_none(kwargs.get("client_id"), "client_id"),
        "account": _connection(kwargs.get("account")),
        "market_type": _connection(kwargs.get("market_type")),
        "observation_absolute_tolerance": _num_or_none(
            kwargs.get("observation_absolute_tolerance"),
            "observation_absolute_tolerance",
        ),
    }


def _etoro_overrides(kwargs: dict[str, Any]) -> dict[str, Any]:
    """Build override dict for eToro tools, including optional credential overrides."""
    return {
        **_overrides(kwargs),
        "api_key": _connection(kwargs.get("api_key")),
        "user_key": _connection(kwargs.get("user_key")),
    }


class TradingConnectionsTool(BaseTool):
    """List available trading connector profiles."""

    name = "trading_connections"
    description = (
        "List selectable trading connector profiles. Connectors come first; paper/live is a profile attribute."
    )
    parameters = {"type": "object", "properties": {}, "required": []}
    repeatable = True
    is_readonly = True

    def execute(self, **_: Any) -> str:
        """List connector profiles and mark the selected one."""
        try:
            selected = load_selected_profile_id()
            return _json_result(
                {
                    "status": "ok",
                    "selected_profile": selected,
                    "profiles": [
                        {
                            **profile.to_dict(selected=profile.id == selected),
                            "onboarding": onboarding_dict(profile),
                        }
                        for profile in list_profiles()
                    ],
                }
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingSelectConnectionTool(BaseTool):
    """Select the default trading connector profile."""

    name = "trading_select_connection"
    description = "Select the default trading connector profile for subsequent trading_* tool calls."
    parameters = {
        "type": "object",
        "properties": {
            "connection": {
                "type": "string",
                "description": "Profile id to select, e.g. ibkr-paper-local.",
            }
        },
        "required": ["connection"],
    }
    repeatable = True
    is_readonly = False

    def execute(self, **kwargs: Any) -> str:
        """Persist the selected profile id."""
        try:
            profile = profile_by_id(str(kwargs["connection"]).strip())
            path = save_selected_profile_id(profile.id)
            return _json_result({"status": "ok", "selected_profile": profile.id, "path": str(path)})
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingCheckTool(BaseTool):
    """Check a trading connector profile."""

    name = "trading_check"
    description = "Check whether a trading connector profile is configured and reachable. This never places orders."
    parameters = {
        "type": "object",
        "properties": TRADING_COMMON_PARAMETERS,
        "required": [],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Check connector readiness."""
        try:
            return _json_result(check_connection(_connection(kwargs.get("connection")), **_overrides(kwargs)))
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingAccountTool(BaseTool):
    """Read account summary from a trading connector profile."""

    name = "trading_account"
    description = "Read account summary from the selected trading connector profile. Read-only."
    parameters = TradingCheckTool.parameters
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Read account summary."""
        try:
            return _json_result(get_account(_connection(kwargs.get("connection")), **_overrides(kwargs)))
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingPositionsTool(BaseTool):
    """Read positions from a trading connector profile."""

    name = "trading_positions"
    description = "Read positions from the selected trading connector profile. Read-only."
    parameters = TradingCheckTool.parameters
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Read positions."""
        try:
            return _json_result(get_positions(_connection(kwargs.get("connection")), **_overrides(kwargs)))
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingOrdersTool(BaseTool):
    """Read open orders from a trading connector profile."""

    name = "trading_orders"
    description = "Read open orders from the selected trading connector profile. Read-only."
    parameters = {
        "type": "object",
        "properties": {
            **TRADING_COMMON_PARAMETERS,
            "include_executions": {"type": "boolean", "default": False},
        },
        "required": [],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Read open orders."""
        try:
            return _json_result(
                get_open_orders(
                    _connection(kwargs.get("connection")),
                    include_executions=boolean_argument(kwargs.get("include_executions", False), field="include_executions"),
                    **_overrides(kwargs),
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingQuoteTool(BaseTool):
    """Read a quote from a trading connector profile."""

    name = "trading_quote"
    description = "Read a quote snapshot from the selected trading connector profile. Read-only."
    parameters = {
        "type": "object",
        "properties": {
            **TRADING_COMMON_PARAMETERS,
            "symbol": {"type": "string", "description": "Symbol, e.g. AAPL"},
            "exchange": {"type": "string", "default": "SMART"},
            "currency": {"type": "string", "default": "USD"},
            "sec_type": {"type": "string", "default": "STK"},
        },
        "required": ["symbol"],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Read quote snapshot."""
        try:
            return _json_result(
                get_quote(
                    str(kwargs["symbol"]),
                    _connection(kwargs.get("connection")),
                    exchange=str(kwargs.get("exchange") or "SMART"),
                    currency=str(kwargs.get("currency") or "USD"),
                    sec_type=str(kwargs.get("sec_type") or "STK"),
                    **_overrides(kwargs),
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingHistoryTool(BaseTool):
    """Read historical bars from a trading connector profile."""

    name = "trading_history"
    description = "Read historical bars from the selected trading connector profile. Read-only."
    parameters = {
        "type": "object",
        "properties": {
            **TradingQuoteTool.parameters["properties"],
            "duration": {"type": "string", "default": "30 D", "description": "IBKR (local_tws) duration string."},
            "bar_size": {"type": "string", "default": "1 day", "description": "IBKR (local_tws) bar size."},
            "what_to_show": {"type": "string", "default": "TRADES"},
            "use_rth": {"type": "boolean", "default": True},
            "period": {
                "type": "string",
                "default": "1d",
                "description": "Bar interval for SDK connectors (broker_sdk): 1m/5m/15m/30m/1h/4h/1d/1w/1M.",
            },
            "limit": {"type": "integer", "default": 90, "description": "Number of bars for SDK connectors."},
        },
        "required": ["symbol"],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Read historical bars."""
        try:
            return _json_result(
                get_history(
                    str(kwargs["symbol"]),
                    _connection(kwargs.get("connection")),
                    exchange=str(kwargs.get("exchange") or "SMART"),
                    currency=str(kwargs.get("currency") or "USD"),
                    sec_type=str(kwargs.get("sec_type") or "STK"),
                    duration=str(kwargs.get("duration") or "30 D"),
                    bar_size=str(kwargs.get("bar_size") or "1 day"),
                    what_to_show=str(kwargs.get("what_to_show") or "TRADES"),
                    use_rth=boolean_argument(kwargs.get("use_rth", True), field="use_rth"),
                    period=str(kwargs.get("period") or "1d"),
                    limit=int(kwargs.get("limit") or 90),
                    **_overrides(kwargs),
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingRehabTool(BaseTool):
    """Read dividend / split adjustment factors for a symbol.

    Use the returned adjustment factors to compute forward-adjusted close prices
    so backtests don't show dividend-driven gaps. Read-only.
    """

    name = "trading_rehab"
    description = "Read dividend / split / rights-issue adjustment factors for a symbol from the selected trading connector profile. Read-only."
    parameters = {
        "type": "object",
        "properties": {
            **TradingQuoteTool.parameters["properties"],
        },
        "required": ["symbol"],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Read rehab adjustment factors."""
        try:
            return _json_result(
                get_rehab(
                    str(kwargs["symbol"]),
                    _connection(kwargs.get("connection")),
                    **_overrides(kwargs),
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingCapitalFlowTool(BaseTool):
    """Read historical main-flow (super/big/mid/small) time series for a symbol.

    Tracks institutional vs retail capital inflow / outflow across
    intraday / daily / weekly / monthly buckets. Read-only.
    """

    name = "trading_capital_flow"
    description = "Read historical capital flow time series (institutional / retail inflow-outflow) for a symbol. period_type: INTRADAY/DAY/WEEK/MONTH. Read-only."
    parameters = {
        "type": "object",
        "properties": {
            **TradingQuoteTool.parameters["properties"],
            "period_type": {
                "type": "string",
                "default": "INTRADAY",
                "description": "Aggregation window: INTRADAY / DAY / WEEK / MONTH.",
            },
        },
        "required": ["symbol"],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Read capital flow time series."""
        try:
            return _json_result(
                get_capital_flow(
                    str(kwargs["symbol"]),
                    _connection(kwargs.get("connection")),
                    period_type=str(kwargs.get("period_type") or "INTRADAY"),
                    **_overrides(kwargs),
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingCapitalDistributionTool(BaseTool):
    """Read the LATEST capital in-flow vs out-flow snapshot for a symbol.

    Today's running tally of super/big/mid/small buys vs sells. Use it to spot
    when institutions are accumulating or distributing right now. Read-only.
    """

    name = "trading_capital_distribution"
    description = (
        "Read today's capital in-flow vs out-flow snapshot (super/big/mid/small buckets) for a symbol. Read-only."
    )
    parameters = {
        "type": "object",
        "properties": {
            **TradingQuoteTool.parameters["properties"],
        },
        "required": ["symbol"],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Read today's capital distribution snapshot."""
        try:
            return _json_result(
                get_capital_distribution(
                    str(kwargs["symbol"]),
                    _connection(kwargs.get("connection")),
                    **_overrides(kwargs),
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingHistoryDealsTool(BaseTool):
    """Read historical FILL records (executed deals) for shadow-account analysis.

    Unlike history_order_list_query (returns intent), this returns only orders
    that ACTUALLY filled — with fill price, qty, counter broker, fee, settlement
    date. Required for true cost-basis reconstruction. Read-only.
    """

    name = "trading_history_deals"
    description = "Read historical FILL records (executed deals) for shadow-account cost-basis reconstruction. start/end YYYY-MM-DD; max window 360 days. Read-only."
    parameters = {
        "type": "object",
        "properties": {
            **TradingQuoteTool.parameters["properties"],
            "start": {"type": "string", "description": "Start date YYYY-MM-DD."},
            "end": {"type": "string", "description": "End date YYYY-MM-DD."},
            "code": {
                "type": "string",
                "default": "",
                "description": "Optional Futu instrument code (e.g. HK.00700). Empty = all symbols.",
            },
        },
        "required": ["start", "end"],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Read historical fill records."""
        try:
            return _json_result(
                get_history_deals(
                    str(kwargs["start"]),
                    str(kwargs["end"]),
                    _connection(kwargs.get("connection")),
                    code=str(kwargs.get("code") or ""),
                    **_overrides(kwargs),
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingAccCashFlowTool(BaseTool):
    """Read account cash-flow movements for a clearing date.

    Tracks deposit / withdrawal / FX conversion / buy-sell settlement /
    margin interest / dividends received / fees. Read-only.
    """

    name = "trading_acc_cash_flow"
    description = "Read account cash-flow movements for a clearing date (YYYY-MM-DD): deposit, withdrawal, FX, settlement, fees. Read-only."
    parameters = {
        "type": "object",
        "properties": {
            **TradingQuoteTool.parameters["properties"],
            "clearing_date": {
                "type": "string",
                "description": "Clearing date YYYY-MM-DD.",
            },
        },
        "required": ["clearing_date"],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Read account cash-flow for one clearing date."""
        try:
            return _json_result(
                get_acc_cash_flow(
                    str(kwargs["clearing_date"]),
                    _connection(kwargs.get("connection")),
                    **_overrides(kwargs),
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingFinancialsTool(BaseTool):
    """Read financial statements (income / balance / cash flow) for a symbol.

    Returns structure_list (field definitions) + report_list (period values).
    Read-only.
    """

    name = "trading_financials"
    description = "Read financial statements (INCOME / BALANCE / CASH_FLOW) for a symbol. Returns structure_list + report_list across N periods. Read-only."
    parameters = {
        "type": "object",
        "properties": {
            **TradingQuoteTool.parameters["properties"],
            "statement_type": {
                "type": "string",
                "default": "INCOME",
                "description": "Statement type: INCOME / BALANCE / CASH_FLOW.",
            },
            "num": {"type": "integer", "default": 20, "description": "Maximum periods."},
        },
        "required": ["symbol"],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Read financial statements."""
        try:
            return _json_result(
                get_financials(
                    str(kwargs["symbol"]),
                    _connection(kwargs.get("connection")),
                    statement_type=str(kwargs.get("statement_type") or "INCOME"),
                    num=int(kwargs.get("num") or 20),
                    **_overrides(kwargs),
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingEarningsCalendarTool(BaseTool):
    """Read upcoming earnings-release dates with EPS / revenue consensus.

    Used to plan earnings-season trades (vol crush, surprise, IV rank).
    Read-only.
    """

    name = "trading_earnings_calendar"
    description = "Read upcoming earnings calendar (code, name, EPS/revenue forecast, IV, IV rank) for US / HK. begin/end YYYY-MM-DD. Read-only."
    parameters = {
        "type": "object",
        "properties": {
            **TradingQuoteTool.parameters["properties"],
            "market": {"type": "string", "default": "US", "description": "US or HK."},
            "begin_date": {"type": "string", "default": "", "description": "Begin YYYY-MM-DD."},
            "end_date": {"type": "string", "default": "", "description": "End YYYY-MM-DD."},
        },
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        """Read earnings calendar."""
        try:
            return _json_result(
                get_earnings_calendar(
                    _connection(kwargs.get("connection")),
                    market=str(kwargs.get("market") or "US"),
                    begin_date=str(kwargs.get("begin_date") or ""),
                    end_date=str(kwargs.get("end_date") or ""),
                    **_overrides(kwargs),
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingPlaceOrderTool(BaseTool):
    """Place an order through a trading connector profile.

    Paper profiles place against the broker's sandbox account. Live profiles
    route through the bounded-autonomy mandate gate (mandate + kill switch +
    fail-closed pre-trade checks + audit) before any order reaches the broker.
    Not read-only; not repeatable (an order must never be silently re-issued).
    """

    name = "trading_place_order"
    description = (
        "Place an order through the selected trading connector profile. Paper "
        "profiles trade a sandbox account; live profiles are gated by the user's "
        "mandate and kill switch. side is 'buy' or 'sell'; give exactly one of "
        "quantity (units) or notional (account-currency amount)."
    )
    parameters = {
        "type": "object",
        "properties": {
            **TRADING_COMMON_PARAMETERS,
            "symbol": {"type": "string", "description": "Symbol, e.g. AAPL, BTC-USDT, 700.HK, HK.00700."},
            "side": {"type": "string", "enum": ["buy", "sell"]},
            "quantity": {
                "type": "number",
                "description": "Order size in units/shares/contracts. Exactly one of quantity/notional.",
            },
            "notional": {
                "type": "number",
                "description": "Order size as an account-currency amount. Exactly one of quantity/notional.",
            },
            "order_type": {"type": "string", "enum": ["market", "limit"], "default": "market"},
            "limit_price": {"type": "number", "description": "Required for limit orders."},
            "time_in_force": {"type": "string", "enum": ["day", "gtc"], "default": "day"},
        },
        "required": ["symbol", "side"],
    }
    repeatable = False
    is_readonly = False

    def execute(self, **kwargs: Any) -> str:
        """Place an order via the connector profile.

        Every numeric argument is converted first and a malformed or non-finite
        value aborts with an error envelope BEFORE the service is called: an
        order tool must fail closed rather than drop a bad size field and place
        a different, plausible-looking order.
        """
        try:
            # LLMs frequently populate BOTH sizing fields, leaving the unused
            # one at 0; a zero size is never valid, so treat it as absent to
            # preserve the "exactly one of quantity/notional" contract.
            quantity = _num_or_none(kwargs.get("quantity"), "quantity") or None
            notional = _num_or_none(kwargs.get("notional"), "notional") or None
            limit_price = _num_or_none(kwargs.get("limit_price"), "limit_price")
            overrides = _overrides(kwargs)
        except InvalidTradingArgument as exc:
            return _json_result({"status": "error", "error": str(exc)})

        try:
            return _json_result(
                place_order(
                    str(kwargs["symbol"]),
                    _connection(kwargs.get("connection")),
                    side=str(kwargs.get("side") or ""),
                    quantity=quantity,
                    notional=notional,
                    order_type=str(kwargs.get("order_type") or "market"),
                    limit_price=limit_price,
                    time_in_force=str(kwargs.get("time_in_force") or "day"),
                    **overrides,
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class TradingCancelOrderTool(BaseTool):
    """Cancel an order through a trading connector profile (risk-reducing)."""

    name = "trading_cancel_order"
    description = "Cancel an open order on the selected trading connector profile by order id."
    parameters = {
        "type": "object",
        "properties": {
            **TRADING_COMMON_PARAMETERS,
            "order_id": {"type": "string", "description": "Broker order id to cancel."},
            "symbol": {"type": "string", "description": "Symbol (required by some brokers, e.g. OKX/Binance)."},
        },
        "required": ["order_id"],
    }
    repeatable = False
    is_readonly = False

    def execute(self, **kwargs: Any) -> str:
        """Cancel an order via the connector profile.

        Malformed connector overrides are rejected before the service call, so a
        cancel never silently targets a different terminal than requested.
        """
        try:
            overrides = _overrides(kwargs)
        except InvalidTradingArgument as exc:
            return _json_result({"status": "error", "error": str(exc)})

        try:
            return _json_result(
                cancel_order(
                    str(kwargs["order_id"]),
                    _connection(kwargs.get("connection")),
                    symbol=_connection(kwargs.get("symbol")),
                    **overrides,
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class EtoroSearchInstrumentsTool(BaseTool):
    """Resolve eToro tickers via ``internalSymbolFull`` or fuzzy discovery."""

    name = "etoro_search_instruments"
    description = (
        "Search eToro instruments by ticker (BTC, AAPL), free text, or asset class "
        "(crypto, stocks, forex). Tickers use exact internalSymbolFull lookup; "
        "asset-class labels browse via instrumentTypeIds on /market-data/instruments."
    )
    parameters = {
        "type": "object",
        "properties": {
            **ETORO_TOOL_PARAMETERS,
            "query": {
                "type": "string",
                "description": "Ticker, search text (e.g. Apple), or asset class (e.g. crypto).",
            },
            "limit": {"type": "integer", "description": "Max results (default 10, max 50)."},
            "mode": {
                "type": "string",
                "enum": ["auto", "symbol", "discover", "type"],
                "description": "auto: ticker exact lookup then fuzzy; symbol: exact only; discover: fuzzy only; type: browse by instrument_type_id.",
            },
            "instrument_type_id": {
                "type": "integer",
                "description": "eToro instrumentTypeID (1=Forex … 10=Crypto). Browse mode when set.",
            },
            "include_rates": {
                "type": "boolean",
                "description": "When browsing by type, attach bid/ask/last from /market-data/instruments/rates.",
            },
        },
        "required": ["query"],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        try:
            overrides = _etoro_overrides(kwargs)
            limit = _int_or_none(kwargs.get("limit"), "limit") or 10
            mode = str(kwargs.get("mode") or "auto")
            instrument_type_id = _int_or_none(kwargs.get("instrument_type_id"), "instrument_type_id")
            include_rates = bool(kwargs.get("include_rates", False))
        except InvalidTradingArgument as exc:
            return _json_result({"status": "error", "error": str(exc)})
        try:
            return _json_result(
                search_instruments(
                    str(kwargs["query"]),
                    _connection(kwargs.get("connection")),
                    limit=limit,
                    mode=mode,
                    instrument_type_id=instrument_type_id,
                    include_rates=include_rates,
                    **overrides,
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class EtoroClosePositionTool(BaseTool):
    """Close or partially close an eToro position."""

    name = "etoro_close_position"
    description = "Close or partially close an open eToro position by position id."
    parameters = {
        "type": "object",
        "properties": {
            **ETORO_TOOL_PARAMETERS,
            "position_id": {"type": "string", "description": "eToro position id."},
            "instrument_id": {
                "type": "integer",
                "description": "Optional instrument id; always resolved and verified against the open position.",
            },
            "units_to_close": {"type": "number", "description": "Units to close; omit to close entire position."},
            "request_id": {"type": "string", "description": "Optional idempotency request id (UUID)."},
        },
        "required": ["position_id"],
    }
    repeatable = False
    is_readonly = False

    def execute(self, **kwargs: Any) -> str:
        try:
            overrides = _etoro_overrides(kwargs)
            units = _num_or_none(kwargs.get("units_to_close"), "units_to_close")
        except InvalidTradingArgument as exc:
            return _json_result({"status": "error", "error": str(exc)})
        try:
            return _json_result(
                close_position(
                    kwargs["position_id"],
                    _connection(kwargs.get("connection")),
                    instrument_id=_int_or_none(kwargs.get("instrument_id"), "instrument_id"),
                    units_to_close=units,
                    request_id=_connection(kwargs.get("request_id")),
                    **overrides,
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class EtoroCancelCloseOrderTool(BaseTool):
    name = "etoro_cancel_close_order"
    description = (
        "Cancel a pending eToro market close order by order id (paper only; "
        "live is fail-closed because this reinstates exposure)."
    )
    parameters = {
        "type": "object",
        "properties": {
            **ETORO_TOOL_PARAMETERS,
            "order_id": {"type": "string", "description": "Pending close order id."},
            "request_id": {"type": "string", "description": "Optional idempotency request id (UUID)."},
        },
        "required": ["order_id"],
    }
    repeatable = False
    is_readonly = False

    def execute(self, **kwargs: Any) -> str:
        try:
            overrides = _etoro_overrides(kwargs)
        except InvalidTradingArgument as exc:
            return _json_result({"status": "error", "error": str(exc)})
        try:
            return _json_result(
                cancel_close_order(
                    str(kwargs["order_id"]),
                    _connection(kwargs.get("connection")),
                    request_id=_connection(kwargs.get("request_id")),
                    **overrides,
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class EtoroEditPositionStopsTool(BaseTool):
    name = "etoro_edit_position_stops"
    description = (
        "Modify or clear stop-loss/take-profit on an open eToro position "
        "(paper only; live edits are fail-closed until incremental funding can be quantified)."
    )
    parameters = {
        "type": "object",
        "properties": {
            **ETORO_TOOL_PARAMETERS,
            "position_id": {"type": "string", "description": "eToro position id."},
            "stop_loss": {"type": "number", "description": "New stop-loss rate."},
            "take_profit": {"type": "number", "description": "New take-profit rate."},
            "trailing_stop_loss": {
                "type": "boolean",
                "description": "true selects trailing; false selects fixed stop-loss type.",
            },
            "clear_stop_loss": {"type": "boolean", "description": "Remove the stop-loss."},
            "clear_take_profit": {"type": "boolean", "description": "Remove the take-profit."},
            "request_id": {"type": "string", "description": "Optional idempotency request id (UUID)."},
        },
        "required": ["position_id"],
    }
    repeatable = False
    is_readonly = False

    def execute(self, **kwargs: Any) -> str:
        try:
            overrides = _etoro_overrides(kwargs)
            stop_loss = _num_or_none(kwargs.get("stop_loss"), "stop_loss")
            take_profit = _num_or_none(kwargs.get("take_profit"), "take_profit")
        except InvalidTradingArgument as exc:
            return _json_result({"status": "error", "error": str(exc)})
        trailing = kwargs.get("trailing_stop_loss")
        try:
            return _json_result(
                edit_position_stops(
                    kwargs["position_id"],
                    _connection(kwargs.get("connection")),
                    stop_loss=stop_loss,
                    take_profit=take_profit,
                    trailing_stop_loss=boolean_argument(trailing, field="trailing_stop_loss") if trailing is not None else None,
                    clear_stop_loss=boolean_argument(kwargs.get("clear_stop_loss"), field="clear_stop_loss"),
                    clear_take_profit=boolean_argument(kwargs.get("clear_take_profit"), field="clear_take_profit"),
                    request_id=_connection(kwargs.get("request_id")),
                    **overrides,
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class EtoroCopyPrecheckTool(BaseTool):
    name = "etoro_copy_precheck"
    description = (
        "Dry-run whether the account can copy an investor with an account-currency amount. "
        "Live accounts only — not supported on demo (paper) profiles."
    )
    parameters = {
        "type": "object",
        "properties": {
            **ETORO_TOOL_PARAMETERS,
            "parent_cid": {"type": "integer", "description": "Investor parent CID."},
            "amount": {"type": "number", "description": "Positive amount in the account currency."},
            "request_id": {"type": "string", "description": "Optional request id (UUID)."},
        },
        "required": ["parent_cid", "amount"],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        try:
            overrides = _etoro_overrides(kwargs)
            amount = _finite_float(kwargs["amount"], "amount")
            parent_cid = _int_or_none(kwargs["parent_cid"], "parent_cid")
        except InvalidTradingArgument as exc:
            return _json_result({"status": "error", "error": str(exc)})
        try:
            return _json_result(
                etoro_copy_precheck(
                    parent_cid,
                    amount,
                    _connection(kwargs.get("connection")),
                    request_id=_connection(kwargs.get("request_id")),
                    **overrides,
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class EtoroCopyStartTool(BaseTool):
    name = "etoro_copy_start"
    description = (
        "Start copying an investor or adjust an existing copy allocation. "
        "Live accounts only — not supported on demo (paper) profiles."
    )
    parameters = {
        "type": "object",
        "properties": {
            **ETORO_TOOL_PARAMETERS,
            "parent_cid": {"type": "integer", "description": "Investor parent CID."},
            "amount": {
                "type": "number",
                "description": "Account-currency amount to add (negative to reduce). Live increases require a verified USD account.",
            },
            "reference_id": {
                "type": "string",
                "description": "Required caller reference: 1-35 URL-safe characters, used for polling.",
            },
            "request_id": {"type": "string", "description": "Optional request id (UUID)."},
        },
        "required": ["parent_cid", "amount", "reference_id"],
    }
    repeatable = False
    is_readonly = False

    def execute(self, **kwargs: Any) -> str:
        try:
            overrides = _etoro_overrides(kwargs)
            amount = _finite_float(kwargs["amount"], "amount")
            parent_cid = _int_or_none(kwargs["parent_cid"], "parent_cid")
        except InvalidTradingArgument as exc:
            return _json_result({"status": "error", "error": str(exc)})
        try:
            return _json_result(
                etoro_copy_start(
                    parent_cid,
                    amount,
                    _connection(kwargs.get("connection")),
                    reference_id=str(kwargs["reference_id"]),
                    request_id=_connection(kwargs.get("request_id")),
                    **overrides,
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class EtoroCopyPollTool(BaseTool):
    name = "etoro_copy_poll"
    description = (
        "Poll the outcome of an asynchronous eToro copy operation. "
        "Live accounts only — not supported on demo (paper) profiles."
    )
    parameters = {
        "type": "object",
        "properties": {
            **ETORO_TOOL_PARAMETERS,
            "reference_id": {"type": "string", "description": "Copy operation reference id."},
            "request_id": {"type": "string", "description": "Optional request id (UUID)."},
        },
        "required": ["reference_id"],
    }
    repeatable = True
    is_readonly = True

    def execute(self, **kwargs: Any) -> str:
        try:
            overrides = _etoro_overrides(kwargs)
        except InvalidTradingArgument as exc:
            return _json_result({"status": "error", "error": str(exc)})
        try:
            return _json_result(
                etoro_copy_poll(
                    str(kwargs["reference_id"]),
                    _connection(kwargs.get("connection")),
                    request_id=_connection(kwargs.get("request_id")),
                    **overrides,
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})


class EtoroCopyCloseTool(BaseTool):
    name = "etoro_copy_close"
    description = (
        "Close or detach an eToro copy relationship by mirror id. "
        "Live accounts only — not supported on demo (paper) profiles."
    )
    parameters = {
        "type": "object",
        "properties": {
            **ETORO_TOOL_PARAMETERS,
            "mirror_id": {"type": "integer", "description": "Copy mirror id."},
            "unregister_type": {
                "type": "string",
                "enum": ["Close", "Detach"],
                "description": "Close liquidates copy; Detach moves positions to main portfolio.",
            },
            "request_id": {"type": "string", "description": "Optional request id (UUID)."},
        },
        "required": ["mirror_id"],
    }
    repeatable = False
    is_readonly = False

    def execute(self, **kwargs: Any) -> str:
        try:
            overrides = _etoro_overrides(kwargs)
            mirror_id = _int_or_none(kwargs["mirror_id"], "mirror_id")
        except InvalidTradingArgument as exc:
            return _json_result({"status": "error", "error": str(exc)})
        try:
            return _json_result(
                etoro_copy_close(
                    mirror_id,
                    _connection(kwargs.get("connection")),
                    unregister_type=str(kwargs.get("unregister_type") or "Close"),
                    request_id=_connection(kwargs.get("request_id")),
                    **overrides,
                )
            )
        except Exception as exc:  # noqa: BLE001
            return _json_result({"status": "error", "error": str(exc)})