sofias-sdk-lite 0.3.0__tar.gz → 0.4.1__tar.gz

{sofias_sdk_lite-0.3.0 → sofias_sdk_lite-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sofias-sdk-lite
-Version: 0.3.0
+Version: 0.4.1
 Summary: Build agents on the Sofias agent graph and run them over RabbitMQ.
 Keywords: agents,ai,llm,rabbitmq,sofias
 Author: Sofias Tech, S.L.

{sofias_sdk_lite-0.3.0 → sofias_sdk_lite-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sofias-sdk-lite"
-version = "0.3.0"
+version = "0.4.1"
 description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -68,6 +68,9 @@ markers = ["integration: requires a running RabbitMQ broker"]
 line-length = 100
 target-version = "py311"
 
+[tool.ruff.lint]
+extend-select = ["TC004"]
+
 [tool.pyright]
 include = ["src"]
 typeCheckingMode = "strict"

{sofias_sdk_lite-0.3.0 → sofias_sdk_lite-0.4.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sofias-sdk-lite"
-version = "0.3.0"
+version = "0.4.1"
 description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -75,6 +75,13 @@ markers = ["integration: requires a running RabbitMQ broker"]
 line-length = 100
 target-version = "py311"
 
+[tool.ruff.lint]
+# TC004 catches a name imported only under ``if TYPE_CHECKING:`` but used at
+# runtime. That shipped in 0.4.0 as a NameError the moment a node executed a
+# caller-owned tool (TKT-067). Neither pyright strict nor mypy flag it: to them
+# the symbol exists. Ruff is the one checker that does.
+extend-select = ["TC004"]
+
 [tool.pyright]
 include = ["src"]
 typeCheckingMode = "strict"

{sofias_sdk_lite-0.3.0 → sofias_sdk_lite-0.4.1}/src/sofias_sdk_lite/__init__.py

@@ -103,6 +103,12 @@ from sofias_sdk_lite.llm import (
     ToolCall,
     ToolSpec,
 )
+from sofias_sdk_lite.files import (
+    Attachment,
+    FileAccess,
+    FileAccessError,
+    ReturnedFile,
+)
 from sofias_sdk_lite.messaging import (
     AgentTaskMessage,
     ApiTaskMessage,
@@ -171,6 +177,11 @@ except PackageNotFoundError:  # pragma: no cover - source checkout without insta
 
 __all__ = [
     "__version__",
+    # Files (0.4.0)
+    "Attachment",
+    "FileAccess",
+    "FileAccessError",
+    "ReturnedFile",
     # Agent
     "Agent",
     "AgentBuilder",

sofias_sdk_lite-0.4.1/src/sofias_sdk_lite/files.py

@@ -0,0 +1,195 @@
+"""Files for third-party agents: the turn's attachments and the files you return.
+
+Everything goes through the platform's intermediary with the turn's short-lived
+grant (the same one your connectors use). Your agent never sees storage keys or
+permanent links, and the grant expires when the turn does.
+
+The task message carries what you need::
+
+    def prepare_input(self, task, history, role):
+        for attachment in task.attachment_details:      # what the user attached
+            data = task.files.download(attachment)        # bytes
+        saved = task.files.upload("report.csv", csv_bytes, "text/csv")
+        answer = f"Here is the report.\\n\\n{saved.artifact()}"
+
+``task.files`` is ``None`` when the platform has no intermediary for your agent
+(for instance, a local run): check it before using it.
+
+Images for a vision model::
+
+    part = task.files.image_part(attachment)   # OpenAI-compatible content part
+    messages = [{"role": "user", "content": [{"type": "text", "text": "What is it?"}, part]}]
+
+Limits: 25 MB per file and 10 returned files per turn.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any, ClassVar
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = [
+    "MAX_FILE_BYTES",
+    "Attachment",
+    "FileAccess",
+    "FileAccessError",
+    "ReturnedFile",
+]
+
+#: The intermediary rejects bigger files; checked here too, before sending.
+MAX_FILE_BYTES = 25 * 1024 * 1024
+
+
+class FileAccessError(RuntimeError):
+    """A download or upload the intermediary refused (status in ``status_code``)."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class Attachment(BaseModel):
+    """A file the user attached, as listed in ``task.attachment_details``."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: str | None = None
+    filename: str
+    content_type: str | None = None
+    byte_size: int | None = None
+    url: str
+
+
+class ReturnedFile(BaseModel):
+    """A file you uploaded with ``FileAccess.upload``: return it with ``artifact()``."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: str
+    filename: str
+    content_type: str | None = None
+    byte_size: int | None = None
+    url: str | None = None
+
+    def artifact(self) -> str:
+        """The tag that hands this file to the user. Put it in your answer."""
+        return "[ARTIFACT]\n" + json.dumps({"file_id": self.id}) + "\n[/ARTIFACT]"
+
+
+class FileAccess(BaseModel):
+    """Download the turn's attachments and upload the files you return.
+
+    Built by the SDK from the ``files`` entry of the task message; the token is
+    the turn's grant and never appears in ``repr`` or logs.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    url: str
+    token: str = Field(repr=False)
+    timeout: float = 60.0
+
+    #: Tests swap the HTTP transport here (``httpx.MockTransport``).
+    _transport: ClassVar[httpx.BaseTransport | None] = None
+    _async_transport: ClassVar[httpx.AsyncBaseTransport | None] = None
+
+    # -- download -----------------------------------------------------------
+
+    def download(self, attachment: Attachment | str) -> bytes:
+        """The bytes of an attachment (or of an intermediary file URL)."""
+        with httpx.Client(timeout=self.timeout, transport=self._transport) as client:
+            response = client.get(_url_of(attachment), headers=self._headers())
+        return _content(response, "download")
+
+    async def adownload(self, attachment: Attachment | str) -> bytes:
+        """Async ``download``."""
+        async with httpx.AsyncClient(
+            timeout=self.timeout, transport=self._async_transport
+        ) as client:
+            response = await client.get(_url_of(attachment), headers=self._headers())
+        return _content(response, "download")
+
+    def image_part(self, attachment: Attachment) -> dict[str, Any]:
+        """An OpenAI-compatible ``image_url`` content part for a vision model."""
+        return _image_part(attachment, self.download(attachment))
+
+    async def aimage_part(self, attachment: Attachment) -> dict[str, Any]:
+        """Async ``image_part``."""
+        return _image_part(attachment, await self.adownload(attachment))
+
+    # -- upload -------------------------------------------------------------
+
+    def upload(
+        self, filename: str, data: bytes, content_type: str = "application/octet-stream"
+    ) -> ReturnedFile:
+        """Store a file for this turn; return it to the user with ``.artifact()``."""
+        _check_size(data)
+        with httpx.Client(timeout=self.timeout, transport=self._transport) as client:
+            response = client.post(
+                self._upload_url(filename), content=data, headers=self._headers(content_type)
+            )
+        return _returned(response)
+
+    async def aupload(
+        self, filename: str, data: bytes, content_type: str = "application/octet-stream"
+    ) -> ReturnedFile:
+        """Async ``upload``."""
+        _check_size(data)
+        async with httpx.AsyncClient(
+            timeout=self.timeout, transport=self._async_transport
+        ) as client:
+            response = await client.post(
+                self._upload_url(filename), content=data, headers=self._headers(content_type)
+            )
+        return _returned(response)
+
+    # -- internals ----------------------------------------------------------
+
+    def _headers(self, content_type: str | None = None) -> dict[str, str]:
+        headers = {"Authorization": f"Bearer {self.token}"}
+        if content_type:
+            headers["Content-Type"] = content_type
+        return headers
+
+    def _upload_url(self, filename: str) -> str:
+        return f"{self.url.rstrip('/')}?filename={quote(filename)}"
+
+
+def _url_of(attachment: Attachment | str) -> str:
+    return attachment if isinstance(attachment, str) else attachment.url
+
+
+def _check_size(data: bytes) -> None:
+    if not data:
+        raise ValueError("cannot upload an empty file")
+    if len(data) > MAX_FILE_BYTES:
+        raise ValueError(f"file too large: {len(data)} bytes (limit {MAX_FILE_BYTES})")
+
+
+def _content(response: httpx.Response, action: str) -> bytes:
+    if response.status_code != 200:
+        raise FileAccessError(
+            f"file {action} failed (HTTP {response.status_code})", response.status_code
+        )
+    return response.content
+
+
+def _returned(response: httpx.Response) -> ReturnedFile:
+    if response.status_code != 201:
+        raise FileAccessError(
+            f"file upload failed (HTTP {response.status_code})", response.status_code
+        )
+    return ReturnedFile.model_validate(response.json())
+
+
+def _image_part(attachment: Attachment, data: bytes) -> dict[str, Any]:
+    content_type = attachment.content_type or "image/png"
+    if not content_type.startswith("image/"):
+        raise ValueError(f"{attachment.filename} is not an image ({content_type})")
+    encoded = base64.b64encode(data).decode("ascii")
+    return {"type": "image_url", "image_url": {"url": f"data:{content_type};base64,{encoded}"}}

{sofias_sdk_lite-0.3.0 → sofias_sdk_lite-0.4.1}/src/sofias_sdk_lite/messaging/models.py

@@ -37,6 +37,7 @@ from pydantic import BaseModel, Field, field_validator, model_validator
 import nh3
 
 from sofias_sdk_lite.contracts.strict_contract import StrictContract
+from sofias_sdk_lite.files import Attachment, FileAccess
 from sofias_sdk_lite.observability._log import get_logger
 
 logger = get_logger("messaging.models")
@@ -105,6 +106,15 @@ class _BaseTaskMessage(BaseModel):
     available_agents: dict[str, Any] | list[str] = {}
     agent_internal_capabilities: str | None = None
 
+    # --- Files (0.4.0) ---
+    # What the user attached: download URLs, and their details. For third-party
+    # agents both point at the platform's intermediary, with the turn's grant.
+    attachments: list[str] = []
+    attachment_details: list[Attachment] = []
+    # Where to download from and upload to with the turn's grant (``None`` when
+    # the platform sends no intermediary, e.g. a local run). See ``sofias_sdk_lite.files``.
+    files: FileAccess | None = None
+
     # --- Delegation (optional) ---
     reply_to: str | None = None
     correlation_id: str | None = None

{sofias_sdk_lite-0.3.0 → sofias_sdk_lite-0.4.1}/src/sofias_sdk_lite/nodes/llm_node.py

@@ -48,6 +48,7 @@ from sofias_sdk_lite.llm import (
 )
 from sofias_sdk_lite.nodes.base_node import BaseNode, NodeType
 from sofias_sdk_lite.nodes.prompt_assembler import PromptAssembler
+from sofias_sdk_lite.observability.tool_events import emit_tool_call
 from sofias_sdk_lite.observability._log import get_logger
 
 if TYPE_CHECKING:
@@ -599,6 +600,7 @@ class LLMNode(BaseNode):
         base_prompt: str,
         prompt: str,
         runtime_vars: dict[str, Any],
+        input_data: dict[str, Any],
     ) -> tuple[int, list[ToolSpec] | None, str]:
         """Re-read the tools when the catalog changed mid-turn.
 
@@ -615,6 +617,7 @@ class LLMNode(BaseNode):
                 would duplicate the schemas inside the text.
             prompt: Current prompt.
             runtime_vars: Template variables for this turn.
+            input_data: The node's validated input for this turn.
 
         Returns:
             Updated ``(revision, specs, prompt)``, or the ones received when
@@ -634,14 +637,33 @@ class LLMNode(BaseNode):
         return (
             revision,
             new_specs,
-            self._prompt_with_registry_tools(base_prompt, new_specs, runtime_vars),
+            self._prompt_with_registry_tools(base_prompt, new_specs, runtime_vars, input_data),
         )
 
+    def _assemble_prompt(self, runtime_vars: dict[str, Any], input_data: dict[str, Any]) -> str:
+        """Assemble this turn's prompt with the node's assembler.
+
+        ``input_data`` only reaches an assembler we built ourselves. A
+        caller-supplied one was written against ``assemble(runtime_vars=...)``
+        and would reject the extra keyword, so it keeps the signature it knows.
+
+        Args:
+            runtime_vars: Template variables for this turn (settings + input).
+            input_data: The node's validated input on its own.
+
+        Returns:
+            The assembled prompt.
+        """
+        if not self._owns_prompt_assembler:
+            return self._prompt_assembler.assemble(runtime_vars=runtime_vars)
+        return self._prompt_assembler.assemble(runtime_vars=runtime_vars, input_data=input_data)
+
     def _prompt_with_registry_tools(
         self,
         prompt: str,
         tool_specs: list[ToolSpec] | None,
         runtime_vars: dict[str, Any],
+        input_data: dict[str, Any],
     ) -> str:
         """Re-assemble the prompt including the registry's tools.
 
@@ -655,6 +677,7 @@ class LLMNode(BaseNode):
             prompt: Prompt already assembled with the node's assembler.
             tool_specs: Static plus registry tools, or None.
             runtime_vars: Template variables for this turn.
+            input_data: The node's validated input for this turn.
 
         Returns:
             The re-assembled prompt, or the one received when no rebuild applies.
@@ -670,7 +693,7 @@ class LLMNode(BaseNode):
             output_contract=self._config.output_contract,
             raw_text=self._raw_text_field is not None,
         )
-        return assembler.assemble(runtime_vars=runtime_vars)
+        return assembler.assemble(runtime_vars=runtime_vars, input_data=input_data)
 
     async def _execute_registry_tool(self, tool_call: ToolCall, tool_start: float) -> ToolResult:
         """Execute a tool call via the ToolRegistry.
@@ -727,7 +750,11 @@ class LLMNode(BaseNode):
         )
 
     async def _execute_tool(self, tool_call: ToolCall) -> ToolResult:
-        """Execute a single tool call.
+        """Execute a single tool call and leave its event line (``emit_tool_call``).
+
+        Both paths -- streaming and not -- and both kinds of tool -- your own
+        and the connectors' -- come through here, so this is the one place the
+        sandbox logs learn which tools ran.
 
         Args:
             tool_call: The tool call to execute.
@@ -735,6 +762,20 @@ class LLMNode(BaseNode):
         Returns:
             ToolResult with success/failure and output/error.
         """
+        started = time.perf_counter()
+        result = await self._run_tool(tool_call)
+        known = tool_call.name in self._tools_by_name or self._tool_registry is not None
+        emit_tool_call(
+            tool_call.name,
+            ok=result.success,
+            duration_ms=(time.perf_counter() - started) * 1000,
+            node_name=self.name,
+            error_type=None if result.success else ("failed" if known else "not_found"),
+        )
+        return result
+
+    async def _run_tool(self, tool_call: ToolCall) -> ToolResult:
+        """Execute a single tool call (see ``_execute_tool``)."""
         tool_start = time.perf_counter()
         tool = self._tools_by_name.get(tool_call.name)
         if tool is None:
@@ -760,6 +801,12 @@ class LLMNode(BaseNode):
             if modified_input is not None:
                 tool_input = modified_input
 
+        # ToolContext is a TYPE_CHECKING-only name in this module, and this is
+        # the one place that BUILDS one instead of just annotating with it, so
+        # it needs the real import at runtime. Same local-import idiom already
+        # used for DelegationNode, FanOutStrategy and StreamingResponseWorkflow.
+        from sofias_sdk_lite.tools import ToolContext
+
         # Execute the tool using BaseTool.execute() in a worker thread (async, non-blocking)
         try:
             context = ToolContext(
@@ -980,7 +1027,7 @@ class LLMNode(BaseNode):
 
         runtime_vars = self._get_runtime_vars()
         runtime_vars.update(input_data)
-        prompt = self._prompt_assembler.assemble(runtime_vars=runtime_vars)
+        prompt = self._assemble_prompt(runtime_vars, input_data)
 
         max_iterations = self._get_max_iterations()
         parallel_tool_calls = self._get_parallel_tool_calls()
@@ -988,7 +1035,7 @@ class LLMNode(BaseNode):
         tool_catalog_revision = self._tool_catalog_revision()
 
         base_prompt = prompt
-        prompt = self._prompt_with_registry_tools(prompt, tool_specs, runtime_vars)
+        prompt = self._prompt_with_registry_tools(prompt, tool_specs, runtime_vars, input_data)
 
         history: list[tuple[LLMResponse, list[ToolResult]]] = []
         iteration = 0
@@ -1000,7 +1047,7 @@ class LLMNode(BaseNode):
 
         while iteration < max_iterations:
             tool_catalog_revision, tool_specs, prompt = await self._refresh_tool_catalog(
-                tool_catalog_revision, tool_specs, base_prompt, prompt, runtime_vars
+                tool_catalog_revision, tool_specs, base_prompt, prompt, runtime_vars, input_data
             )
 
             if token_budget and history:
@@ -1474,7 +1521,7 @@ class LLMNode(BaseNode):
             runtime_vars = self._get_runtime_vars()
             # Include validated input in runtime vars for prompt templates
             runtime_vars.update(input_data)
-            prompt = self._prompt_assembler.assemble(runtime_vars=runtime_vars)
+            prompt = self._assemble_prompt(runtime_vars, input_data)
 
             # Tool loop
             max_iterations = self._get_max_iterations()
@@ -1483,7 +1530,9 @@ class LLMNode(BaseNode):
             tool_catalog_revision = self._tool_catalog_revision()
 
             base_prompt = prompt
-            prompt = self._prompt_with_registry_tools(prompt, tool_specs, runtime_vars)
+            prompt = self._prompt_with_registry_tools(
+                prompt, tool_specs, runtime_vars, input_data
+            )
 
             history: list[tuple[LLMResponse, list[ToolResult]]] = []
             iteration = 0
@@ -1506,7 +1555,12 @@ class LLMNode(BaseNode):
 
             while iteration < max_iterations:
                 tool_catalog_revision, tool_specs, prompt = await self._refresh_tool_catalog(
-                    tool_catalog_revision, tool_specs, base_prompt, prompt, runtime_vars
+                    tool_catalog_revision,
+                    tool_specs,
+                    base_prompt,
+                    prompt,
+                    runtime_vars,
+                    input_data,
                 )
 
                 if token_budget and history:

{sofias_sdk_lite-0.3.0 → sofias_sdk_lite-0.4.1}/src/sofias_sdk_lite/nodes/prompt_assembler.py

@@ -13,6 +13,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from sofias_sdk_lite.llm import ToolSpec
+from sofias_sdk_lite.observability._log import get_logger
 
 if TYPE_CHECKING:
     from sofias_sdk_lite.contracts import StrictContract
@@ -21,6 +22,8 @@ if TYPE_CHECKING:
 # Re-export so existing importers keep working
 __all__ = ["PromptAssembler", "ToolSpec"]
 
+logger = get_logger("nodes.prompt_assembler")
+
 
 class PromptAssembler:
     """Assembles the final prompt for LLM calls.
@@ -230,7 +233,44 @@ class PromptAssembler:
         """
         return ""
 
-    def assemble(self, runtime_vars: dict[str, Any] | None = None) -> str:
+    @staticmethod
+    def _keys_used_by_template(template: str, input_data: dict[str, Any]) -> list[str]:
+        """Which input keys the template actually references as {placeholders}.
+
+        Args:
+            template: The fixed prompt, before variable resolution.
+            input_data: The node's validated input.
+
+        Returns:
+            The referenced keys, empty when the template ignores the input.
+        """
+        return [key for key in input_data if "{" + key + "}" in template]
+
+    def _format_input_section(self, input_data: dict[str, Any]) -> str:
+        """Format the node's input as its own section.
+
+        The input reaches the model ONLY through {placeholders} in the fixed
+        prompt: there is no separate "user message" channel. A node configured
+        without ``NodePromptConfig`` therefore sent the model the tool catalogue
+        and nothing else, dropping the user's message in silence (TKT-066).
+
+        Args:
+            input_data: The node's validated input.
+
+        Returns:
+            Formatted input section, or empty string when there is no input.
+        """
+        if not input_data:
+            return ""
+
+        body = json.dumps(input_data, indent=2, ensure_ascii=False, default=str)
+        return f"## Input\n\n```json\n{body}\n```"
+
+    def assemble(
+        self,
+        runtime_vars: dict[str, Any] | None = None,
+        input_data: dict[str, Any] | None = None,
+    ) -> str:
         """Assemble the final prompt.
 
         Combines the fixed prompt with variable sections (tools, output format)
@@ -238,6 +278,11 @@ class PromptAssembler:
 
         Args:
             runtime_vars: Optional runtime variables for template resolution.
+            input_data: The node's validated input, when the caller can tell it
+                apart from ``runtime_vars`` (which also carries agent settings).
+                Used to render the input for a node that has no prompt template,
+                and to warn when a template ignores it. Optional, so a
+                caller-supplied assembler keeps working without it.
 
         Returns:
             The complete assembled prompt ready for LLM invocation.
@@ -264,5 +309,24 @@ class PromptAssembler:
         if output_section:
             sections.append(output_section)
 
+        if input_data:
+            if not fixed_prompt:
+                # No template at all: without this the input never reaches the
+                # model. Appended last, after the tool schemas, so the task sits
+                # closest to where the model answers.
+                input_section = self._format_input_section(input_data)
+                if input_section:
+                    sections.append(input_section)
+            elif not self._keys_used_by_template(fixed_prompt, input_data):
+                # A template that names none of the input keys drops the input
+                # just as silently, but it may be deliberate (a node whose input
+                # only passes through to the output), so this only warns.
+                logger.warning(
+                    "Prompt template references none of the node's input: the "
+                    "model will not see it. Reference it as {placeholder}.",
+                    node_name=self._config.name,
+                    input_keys=sorted(input_data),
+                )
+
         # Join sections with clear separation
         return "\n\n".join(sections).strip()

sofias_sdk_lite-0.4.1/src/sofias_sdk_lite/observability/tool_events.py

@@ -0,0 +1,80 @@
+"""One line per tool call, for the developer portal's sandbox logs.
+
+Every tool the model calls -- your own or a connector's -- leaves one line on
+standard output, whatever your logging configuration::
+
+    SOFIAS_EVENT {"type":"tool_call","tool":"search","server":"notion","ok":true,"duration_ms":412,...}
+
+The portal reads these lines to show which tools your agent called. They carry
+names, timings and outcome only: never the arguments or the results, which may
+hold your users' data. Set ``SOFIAS_EVENTS=off`` to silence them.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import time
+from typing import Any
+
+__all__ = ["EVENT_PREFIX", "emit_tool_call"]
+
+#: Marks the lines the portal parses; everything else in the log is shown raw.
+EVENT_PREFIX = "SOFIAS_EVENT"
+
+_logger = logging.getLogger("sofias_sdk_lite.events")
+
+
+class _StdoutHandler(logging.StreamHandler):  # type: ignore[type-arg]
+    """Writes to whatever ``sys.stdout`` is at emit time (it may be swapped later)."""
+
+    @property  # type: ignore[override]
+    def stream(self) -> Any:
+        return sys.stdout
+
+    @stream.setter
+    def stream(self, _value: Any) -> None:
+        pass
+
+
+def _ensure_handler() -> None:
+    """Own stdout handler, so the line appears even without logging configured."""
+    if _logger.handlers:
+        return
+    handler = _StdoutHandler()
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    _logger.addHandler(handler)
+    _logger.setLevel(logging.INFO)
+    _logger.propagate = False
+
+
+def emit_tool_call(
+    tool_name: str,
+    *,
+    ok: bool,
+    duration_ms: float,
+    node_name: str | None = None,
+    error_type: str | None = None,
+) -> None:
+    """Write the event line for one tool call (no arguments, no results)."""
+    if os.environ.get("SOFIAS_EVENTS", "").lower() in {"off", "0", "false"}:
+        return
+    server, separator, tool = tool_name.partition("__")
+    if not separator:
+        server, tool = "", tool_name
+    event: dict[str, Any] = {
+        "type": "tool_call",
+        "tool": tool,
+        "server": server or None,
+        "ok": ok,
+        "duration_ms": round(duration_ms),
+        "node": node_name,
+        "error_type": error_type,
+        "ts": round(time.time(), 3),
+    }
+    _ensure_handler()
+    _logger.info(
+        "%s %s", EVENT_PREFIX, json.dumps(event, separators=(",", ":"), ensure_ascii=False)
+    )