fix: reject unbound methods instead of silently breaking at runtime

Codex review found that skipping self/cls from schema generation makes
unbound methods appear supported, but execution fails with TypeError
because the receiver is never injected. Bound methods (instance.method)
already work - Python strips self before inspect.signature sees it.

- Raise UserError for unbound self/cls instead of silent schema-only skip
- Remove dead receiver_was_skipped logic and call_sig stripping (P2 fix)
- Clean up self_or_cls_skipped variable (now unreachable)
- Update tests to expect UserError for unbound methods

Author: mvanhorn

src/agents/function_schema.py

@@ -287,13 +287,6 @@ def function_schema(
     takes_context = False
     filtered_params = []
 
-    # Track whether the first real (non-self/cls) parameter has been processed for context check
-    self_or_cls_skipped = False
-    # Permanent flag: True when an unannotated self/cls receiver was found and skipped.
-    # Unlike self_or_cls_skipped, this is never reset and is used to decide whether
-    # to strip self/cls from call_sig.
-    receiver_was_skipped = False
-
     if params:
         first_name, first_param = params[0]
         # Prefer the evaluated type hint if available
@@ -305,24 +298,22 @@ def function_schema(
             else:
                 filtered_params.append((first_name, first_param))
         elif first_name in ("self", "cls"):
-            self_or_cls_skipped = True  # Skip bound method receiver parameter
-            receiver_was_skipped = True
+            # An unannotated self/cls means this is an unbound method or classmethod.
+            # Bound methods (e.g., instance.method) already have self stripped by Python.
+            raise UserError(
+                f"Function {func.__name__} has an unbound '{first_name}' parameter. "
+                f"Pass a bound method (e.g., instance.{func.__name__}) instead of the "
+                f"unbound class method."
+            )
         else:
             filtered_params.append((first_name, first_param))
 
     # For parameters other than the first, raise error if any use RunContextWrapper or ToolContext
-    # (unless self/cls was skipped, in which case ONLY the param immediately after self/cls is
-    # treated as the effective first param).
-    for idx, (name, param) in enumerate(params[1:]):
+    for name, param in params[1:]:
         ann = type_hints.get(name, param.annotation)
         if ann != inspect._empty:
             origin = get_origin(ann) or ann
             if origin is RunContextWrapper or origin is ToolContext:
-                if self_or_cls_skipped and not takes_context and idx == 0:
-                    # self/cls was the first param and this is immediately after it
-                    takes_context = True
-                    self_or_cls_skipped = False
-                    continue
                 raise UserError(
                     f"RunContextWrapper/ToolContext param found at non-first position in function"
                     f" {func.__name__}"
@@ -426,22 +417,14 @@ def function_schema(
     if strict_json_schema:
         json_schema = ensure_strict_json_schema(json_schema)
 
-    # 5. Build a signature that excludes self/cls so to_call_args iterates
-    #    only the parameters the caller actually needs to pass.
-    if receiver_was_skipped:
-        remaining = [p for name, p in params if name not in ("self", "cls")]
-        call_sig = sig.replace(parameters=remaining)
-    else:
-        call_sig = sig
-
-    # 6. Return as a FuncSchema dataclass
+    # 5. Return as a FuncSchema dataclass
     return FuncSchema(
         name=func_name,
         # Ensure description_override takes precedence even if docstring info is disabled.
         description=description_override or (doc_info.description if doc_info else None),
         params_pydantic_model=dynamic_model,
         params_json_schema=json_schema,
-        signature=call_sig,
+        signature=sig,
         takes_context=takes_context,
         strict_json_schema=strict_json_schema,
     )

tests/test_function_schema.py

@@ -887,8 +887,8 @@ def func_with_annotated_multiple_field_constraints(
         fs.params_pydantic_model(**{"score": 50, "factor": 0.0})
 
 
-def test_method_self_param_skipped():
-    """Test that self parameter is skipped for class methods."""
+def test_bound_method_self_not_in_schema():
+    """Test that bound methods work normally (Python already strips self)."""
 
     class MyTools:
         def greet(self, name: str) -> str:
@@ -902,8 +902,8 @@ def greet(self, name: str) -> str:
     assert fs.params_json_schema.get("required") == ["name"]
 
 
-def test_classmethod_cls_param_skipped():
-    """Test that cls parameter is skipped for classmethods passed as unbound."""
+def test_unbound_cls_param_raises():
+    """Test that unbound classmethods with unannotated cls raise UserError."""
 
     # Simulate a function whose first param is named cls with no annotation
     code = compile("def greet(cls, name: str) -> str: ...", "<test>", "exec")
@@ -912,14 +912,12 @@ def test_classmethod_cls_param_skipped():
     fn = ns["greet"]
     fn.__annotations__ = {"name": str, "return": str}
 
-    fs = function_schema(fn, use_docstring_info=False)
-    props = fs.params_json_schema.get("properties", {})
-    assert "cls" not in props
-    assert "name" in props
+    with pytest.raises(UserError, match="unbound 'cls' parameter"):
+        function_schema(fn, use_docstring_info=False)
 
 
-def test_method_self_with_context_second_param():
-    """Test that self is skipped and RunContextWrapper as second param is recognized."""
+def test_bound_method_with_context_second_param():
+    """Test that bound methods with RunContextWrapper as second param work correctly."""
 
     class MyTools:
         def greet(self, ctx: RunContextWrapper[None], name: str) -> str:
@@ -928,6 +926,7 @@ def greet(self, ctx: RunContextWrapper[None], name: str) -> str:
     obj = MyTools()
     fs = function_schema(obj.greet, use_docstring_info=False)
     props = fs.params_json_schema.get("properties", {})
+    # self is already stripped by Python for bound methods
     assert "self" not in props
     assert "ctx" not in props
     assert "name" in props
@@ -946,8 +945,8 @@ def greet(self, name: str, ctx: RunContextWrapper[None]) -> str:
         function_schema(obj.greet, use_docstring_info=False)
 
 
-def test_method_self_excluded_from_call_signature():
-    """Test that self/cls is excluded from the stored signature used by to_call_args."""
+def test_unbound_method_with_self_raises():
+    """Test that unbound methods with unannotated self raise UserError."""
 
     # Simulate an unbound method with self as first param
     code = compile(
@@ -958,16 +957,8 @@ def test_method_self_excluded_from_call_signature():
     fn = ns["greet"]
     fn.__annotations__ = {"ctx": RunContextWrapper[None], "name": str, "return": str}
 
-    fs = function_schema(fn, use_docstring_info=False)
-    # self should not be in the signature used by to_call_args
-    assert "self" not in fs.signature.parameters
-    assert "name" in fs.signature.parameters
-    assert fs.takes_context is True
-
-    # to_call_args should produce only the non-context, non-self params
-    parsed = fs.params_pydantic_model(name="world")
-    args, kwargs = fs.to_call_args(parsed)
-    assert args == ["world"]
+    with pytest.raises(UserError, match="unbound 'self' parameter"):
+        function_schema(fn, use_docstring_info=False)
 
 
 def test_regular_unannotated_first_param_still_included():