fix: report evicted handles as "evicted", not "not found" (#532)

Track evicted ids in bounded tombstone deques in both handle stores and route
not-found sites through a shared eviction-aware message.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Shashankss1205

src/sktime_mcp/runtime/executor.py

@@ -9,6 +9,7 @@
 import inspect
 import logging
 import uuid
+from collections import deque
 from typing import Any
 
 import pandas as pd
@@ -196,6 +197,8 @@ def __init__(self):
         self._handle_manager = get_handle_manager()
         self._job_manager = get_job_manager()
         self._data_handles: dict[str, Any] = {}
+        # Tombstones for data handles evicted under the cap (see _cleanup_oldest_data).
+        self._evicted_data: deque[str] = deque(maxlen=1024)
         from sktime_mcp.config import settings
 
         self._max_data_handles = settings.max_data_handles
@@ -205,7 +208,23 @@ def _cleanup_oldest_data(self, count: int = 10) -> None:
         to_remove = list(self._data_handles.keys())[:count]
         for handle_id in to_remove:
             del self._data_handles[handle_id]
-            logger.debug("Evicted data handle %s (limit=%d)", handle_id, self._max_data_handles)
+            self._evicted_data.append(handle_id)
+            logger.info("Evicted data handle %s (limit %d reached)", handle_id, self._max_data_handles)
+
+    def data_handle_missing(self, handle_id: str) -> dict[str, Any]:
+        """Error body for a missing data handle — distinguishes evicted from unknown.
+
+        Returns the ``error`` string plus the capped available-handles summary,
+        so callers can splat it into a not-found response.
+        """
+        if handle_id in self._evicted_data:
+            error = (
+                f"Data handle '{handle_id}' was evicted (handle limit "
+                f"{self._max_data_handles} reached); reload the source."
+            )
+        else:
+            error = f"Data handle '{handle_id}' not found"
+        return {"error": error, **self.summarize_available_handles()}
 
     def _register_data_handle(self, handle_id: str, data: dict[str, Any]) -> None:
         if len(self._data_handles) >= self._max_data_handles:
@@ -380,7 +399,7 @@ def fit(
             handle_info = self._handle_manager.get_info(handle_id)
             instance = handle_info.instance
         except KeyError:
-            return {"success": False, "error": f"Handle not found: {handle_id}"}
+            return {"success": False, "error": self._handle_manager.describe_missing(handle_id)}
 
         obj_type = getattr(instance, "get_class_tag", lambda x, y: "")("object_type", "")
         if not hasattr(instance, "fit"):
@@ -448,7 +467,7 @@ def predict(
         try:
             instance = self._handle_manager.get_instance(handle_id)
         except KeyError:
-            return {"success": False, "error": f"Handle not found: {handle_id}"}
+            return {"success": False, "error": self._handle_manager.describe_missing(handle_id)}
 
         obj_type = getattr(instance, "get_class_tag", lambda x, y: "")("object_type", "")
         if (
@@ -667,7 +686,7 @@ def call_method(
         try:
             instance = self._handle_manager.get_instance(handle_id)
         except KeyError:
-            return {"success": False, "error": f"Handle not found: {handle_id}"}
+            return {"success": False, "error": self._handle_manager.describe_missing(handle_id)}
 
         if not hasattr(instance, method_name):
             obj_type = getattr(instance, "get_class_tag", lambda x, y: "")("object_type", "")
@@ -748,7 +767,7 @@ def update(
         try:
             instance = self._handle_manager.get_instance(handle_id)
         except KeyError:
-            return {"success": False, "error": f"Handle not found: {handle_id}"}
+            return {"success": False, "error": self._handle_manager.describe_missing(handle_id)}
 
         if not self._handle_manager.is_fitted(handle_id):
             return {"success": False, "error": "Estimator not fitted"}
@@ -788,7 +807,7 @@ def get_fitted_params(self, handle_id: str) -> dict[str, Any]:
         try:
             instance = self._handle_manager.get_instance(handle_id)
         except KeyError:
-            return {"success": False, "error": f"Handle not found: {handle_id}"}
+            return {"success": False, "error": self._handle_manager.describe_missing(handle_id)}
 
         if not self._handle_manager.is_fitted(handle_id):
             return {"success": False, "error": "Estimator not fitted"}
@@ -932,7 +951,7 @@ async def evaluate_async(
             try:
                 instance = self._handle_manager.get_instance(handle_id)
             except KeyError as err:
-                raise ValueError(f"Handle not found: {handle_id}") from err
+                raise ValueError(self._handle_manager.describe_missing(handle_id)) from err
 
             y_res = self._resolve_source(y)
             if not y_res["success"]:
@@ -1259,7 +1278,7 @@ def format_data_handle(
         was never exposed to the caller.
         """
         if data_handle not in self._data_handles:
-            return {"success": False, "error": f"Data handle '{data_handle}' not found"}
+            return {"success": False, **self.data_handle_missing(data_handle)}
 
         data_info = self._data_handles[data_handle]
         y = data_info["y"].copy()
@@ -1424,7 +1443,7 @@ def release_data_handle(self, data_handle: str) -> dict[str, Any]:
         else:
             return {
                 "success": False,
-                "error": f"Data handle '{data_handle}' not found",
+                "error": self.data_handle_missing(data_handle)["error"],
             }
 
 

src/sktime_mcp/runtime/handles.py

@@ -6,6 +6,7 @@
 
 import logging
 import uuid
+from collections import deque
 from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any
@@ -42,6 +43,21 @@ class HandleManager:
     def __init__(self, max_handles: int = 100):
         self._handles: dict[str, HandleInfo] = {}
         self._max_handles = max_handles
+        # Tombstones: ids evicted to stay under the cap, so a later lookup can
+        # say "evicted" instead of an indistinguishable "not found".
+        self._evicted: deque[str] = deque(maxlen=1024)
+
+    def describe_missing(self, handle_id: str) -> str:
+        """Message for a handle that isn't present — distinguishes evicted from unknown."""
+        if handle_id in self._evicted:
+            return (
+                f"Estimator handle '{handle_id}' was evicted (handle limit "
+                f"{self._max_handles} reached); re-create it with instantiate."
+            )
+        return f"Handle not found: {handle_id}"
+
+    def was_evicted(self, handle_id: str) -> bool:
+        return handle_id in self._evicted
 
     def create_handle(
         self,
@@ -67,12 +83,12 @@ def create_handle(
 
     def get_instance(self, handle_id: str) -> Any:
         if handle_id not in self._handles:
-            raise KeyError(f"Handle not found: {handle_id}")
+            raise KeyError(self.describe_missing(handle_id))
         return self._handles[handle_id].instance
 
     def get_info(self, handle_id: str) -> HandleInfo:
         if handle_id not in self._handles:
-            raise KeyError(f"Handle not found: {handle_id}")
+            raise KeyError(self.describe_missing(handle_id))
         return self._handles[handle_id]
 
     def exists(self, handle_id: str) -> bool:
@@ -113,6 +129,10 @@ def _cleanup_oldest(self, count: int = 10) -> None:
         )
         for handle_id, _ in sorted_handles[:count]:
             del self._handles[handle_id]
+            self._evicted.append(handle_id)
+            logger.info(
+                "Evicted estimator handle %s (limit %d reached)", handle_id, self._max_handles
+            )
 
 
 _handle_manager_instance: HandleManager | None = None

src/sktime_mcp/tools/codegen.py

@@ -86,7 +86,7 @@ def export_code_tool(
     try:
         handle_info = handle_manager.get_info(handle)
     except KeyError:
-        return {"success": False, "error": f"Handle not found: {handle}"}
+        return {"success": False, "error": handle_manager.describe_missing(handle)}
 
     if not _is_valid_var_name(var_name):
         return {

src/sktime_mcp/tools/evaluate.py

@@ -73,7 +73,10 @@ def evaluate_tool(
     try:
         instance = executor._handle_manager.get_instance(estimator_handle)
     except KeyError:
-        return {"success": False, "error": f"Handle not found: {estimator_handle}"}
+        return {
+            "success": False,
+            "error": executor._handle_manager.describe_missing(estimator_handle),
+        }
 
     y_res = executor._resolve_source(y)
     if not y_res["success"]:

src/sktime_mcp/tools/inspect_data.py

@@ -55,8 +55,7 @@ def inspect_data_tool(data_handle: str) -> dict[str, Any]:
     if data_handle not in executor._data_handles:
         return {
             "success": False,
-            "error": f"Data handle '{data_handle}' not found",
-            **executor.summarize_available_handles(),
+            **executor.data_handle_missing(data_handle),
         }
 
     data_info = executor._data_handles[data_handle]

src/sktime_mcp/tools/instantiate.py

@@ -59,7 +59,7 @@ def release_handle_tool(handle: str) -> dict[str, Any]:
     return {
         "success": released,
         "handle": handle,
-        "message": "Handle released" if released else "Handle not found",
+        "message": "Handle released" if released else handle_manager.describe_missing(handle),
     }
 
 

src/sktime_mcp/tools/plotting.py

@@ -179,9 +179,13 @@ def plot_series_tool(
             missing.append(handle)
 
     if missing:
+        evicted = [h for h in missing if h in executor._evicted_data]
+        detail = f"Data handle(s) not found: {missing}"
+        if evicted:
+            detail += f" (evicted under the handle limit: {evicted}; reload the source)"
         return {
             "success": False,
-            "error": f"Data handle(s) not found: {missing}",
+            "error": detail,
             **executor.summarize_available_handles(),
         }
 

src/sktime_mcp/tools/save_data.py

@@ -60,8 +60,7 @@ def save_data_tool(
     if data_handle not in executor._data_handles:
         return {
             "success": False,
-            "error": f"Data handle '{data_handle}' not found",
-            **executor.summarize_available_handles(),
+            **executor.data_handle_missing(data_handle),
         }
 
     fmt = format.lower()

src/sktime_mcp/tools/save_model.py

@@ -60,7 +60,7 @@ def save_model_tool(
     try:
         estimator = handle_manager.get_instance(estimator_handle)
     except KeyError:
-        return {"success": False, "error": f"Handle not found: {estimator_handle}"}
+        return {"success": False, "error": handle_manager.describe_missing(estimator_handle)}
 
     if not handle_manager.is_fitted(estimator_handle):
         handle_info = handle_manager.get_info(estimator_handle)

src/sktime_mcp/tools/split_data.py

@@ -56,8 +56,7 @@ def split_data_tool(
     if data_handle not in executor._data_handles:
         return {
             "success": False,
-            "error": f"Data handle '{data_handle}' not found",
-            **executor.summarize_available_handles(),
+            **executor.data_handle_missing(data_handle),
         }
 
     if test_size is not None and fh is not None: