chore: run pyright across src and tests in typecheck (#2623)

seratch · web-flow · commit 2ac2bbb9cbd9 · 2026-03-07T13:47:05.000+09:00
diff --git a/.agents/skills/code-change-verification/SKILL.md b/.agents/skills/code-change-verification/SKILL.md
@@ -20,7 +20,7 @@ Ensure work is only marked complete after formatting, linting, type checking, an
 ## Manual workflow
 
 - If dependencies are not installed or have changed, run `make sync` first to install dev requirements via `uv`.
-- Run from the repository root in this order: `make format`, `make lint`, `make mypy`, `make tests`.
+- Run from the repository root in this order: `make format`, `make lint`, `make typecheck`, `make tests`.
 - Do not skip steps; stop and fix issues immediately when a command fails.
 - Re-run the full stack after applying fixes so the commands execute in the required order.
 
diff --git a/.agents/skills/code-change-verification/scripts/run.ps1 b/.agents/skills/code-change-verification/scripts/run.ps1
@@ -32,7 +32,7 @@ function Invoke-MakeStep {
 
 Invoke-MakeStep -Step "format"
 Invoke-MakeStep -Step "lint"
-Invoke-MakeStep -Step "mypy"
+Invoke-MakeStep -Step "typecheck"
 Invoke-MakeStep -Step "tests"
 
 Write-Host "code-change-verification: all commands passed."
diff --git a/.agents/skills/code-change-verification/scripts/run.sh b/.agents/skills/code-change-verification/scripts/run.sh
@@ -16,8 +16,8 @@ make format
 echo "Running make lint..."
 make lint
 
-echo "Running make mypy..."
-make mypy
+echo "Running make typecheck..."
+make typecheck
 
 echo "Running make tests..."
 make tests
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -58,7 +58,7 @@ jobs:
         run: make sync
       - name: Run typecheck
         if: steps.changes.outputs.run == 'true'
-        run: make mypy
+        run: make typecheck
       - name: Skip typecheck
         if: steps.changes.outputs.run != 'true'
         run: echo "Skipping typecheck for non-code changes."
diff --git a/AGENTS.md b/AGENTS.md
@@ -129,7 +129,7 @@ When `$code-change-verification` applies, run it to execute the required verific
   ```
 - Type checking:
   ```bash
-  make mypy
+  make typecheck
   ```
 
 #### Snapshot tests
@@ -155,7 +155,7 @@ Some tests rely on inline snapshots; see `tests/README.md` for details. Re-run `
 #### Formatting, linting, and type checking
 
 - Formatting and linting use `ruff`; run `make format` (applies fixes) and `make lint` (checks only).
-- Type hints must pass `make mypy`.
+- Type hints must pass `make typecheck`.
 - Write comments as full sentences ending with a period.
 - Imports are managed by Ruff and should stay sorted.
 
@@ -166,7 +166,7 @@ When `$code-change-verification` applies, run the full sequence in order (or use
 ```bash
 make format
 make lint
-make mypy
+make typecheck
 make tests
 ```
 
@@ -202,12 +202,12 @@ make tests
 
 - Use the template at `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`; include a summary, test plan, and issue number if applicable.
 - Add tests for new behavior when feasible and update documentation for user-facing changes.
-- Run `make format`, `make lint`, `make mypy`, and `make tests` before marking work ready.
+- Run `make format`, `make lint`, `make typecheck`, and `make tests` before marking work ready.
 - Commit messages should be concise and written in the imperative mood. Small, focused commits are preferred.
 
 ### Review Process & What Reviewers Look For
 
-- ✅ Checks pass (`make format`, `make lint`, `make mypy`, `make tests`).
+- ✅ Checks pass (`make format`, `make lint`, `make typecheck`, `make tests`).
 - ✅ Tests cover new behavior and edge cases.
 - ✅ Code is readable, maintainable, and consistent with existing style.
 - ✅ Public APIs and user-facing behavior changes are documented.
diff --git a/Makefile b/Makefile
@@ -19,6 +19,23 @@ lint:
 mypy: 
 	uv run mypy . --exclude site
 
+.PHONY: pyright
+pyright:
+	uv run pyright --project pyrightconfig.json
+
+.PHONY: typecheck
+typecheck:
+	@set -eu; \
+	mypy_pid=''; \
+	pyright_pid=''; \
+	trap 'test -n "$$mypy_pid" && kill $$mypy_pid 2>/dev/null || true; test -n "$$pyright_pid" && kill $$pyright_pid 2>/dev/null || true' EXIT INT TERM; \
+	echo "Running make mypy and make pyright in parallel..."; \
+	$(MAKE) mypy & mypy_pid=$$!; \
+	$(MAKE) pyright & pyright_pid=$$!; \
+	wait $$mypy_pid; \
+	wait $$pyright_pid; \
+	trap - EXIT
+
 .PHONY: tests
 tests: tests-parallel tests-serial
 
@@ -68,4 +85,4 @@ deploy-docs:
 	uv run mkdocs gh-deploy --force --verbose
 
 .PHONY: check
-check: format-check lint mypy tests
+check: format-check lint typecheck tests
diff --git a/pyproject.toml b/pyproject.toml
@@ -74,6 +74,7 @@ dev = [
     "dapr>=1.14.0",
     "grpcio>=1.60.0",
     "testcontainers==4.12.0", # pinned to 4.12.0 because 4.13.0 has a warning bug in wait_for_logs, see https://github.com/testcontainers/testcontainers-python/issues/874
+    "pyright==1.1.408",
 ]
 
 [tool.uv.workspace]
diff --git a/pyrightconfig.json b/pyrightconfig.json
@@ -0,0 +1,15 @@
+{
+  "include": ["src", "tests"],
+  "extraPaths": ["."],
+  "pythonVersion": "3.10",
+  "typeCheckingMode": "basic",
+  "reportAttributeAccessIssue": "none",
+  "reportArgumentType": "none",
+  "reportGeneralTypeIssues": "none",
+  "reportIndexIssue": "none",
+  "reportMissingImports": "none",
+  "reportPrivateImportUsage": "none",
+  "reportSelfClsParameterName": "none",
+  "reportTypedDictNotRequiredAccess": "none",
+  "reportUnsupportedDunderAll": "none"
+}
diff --git a/src/agents/agent.py b/src/agents/agent.py
@@ -745,6 +745,7 @@ def _find_mirrored_approval_record(
 
             if run_result is None:
                 if on_stream is not None:
+                    stream_handler = on_stream
                     run_result_streaming = Runner.run_streamed(
                         starting_agent=cast(Agent[Any], self),
                         input=resume_state or resolved_input,
@@ -765,7 +766,7 @@ def _find_mirrored_approval_record(
                     async def _run_handler(payload: AgentToolStreamEvent) -> None:
                         """Execute the user callback while capturing exceptions."""
                         try:
-                            maybe_result = on_stream(payload)
+                            maybe_result = stream_handler(payload)
                             if inspect.isawaitable(maybe_result):
                                 await maybe_result
                         except Exception:
diff --git a/src/agents/extensions/memory/advanced_sqlite_session.py b/src/agents/extensions/memory/advanced_sqlite_session.py
@@ -438,7 +438,7 @@ def _add_structure_sync():
                 self._logger.error(f"Failed to cleanup orphaned messages: {cleanup_error}")
             # Don't re-raise - structure metadata is supplementary
 
-    async def _cleanup_orphaned_messages(self) -> None:
+    async def _cleanup_orphaned_messages(self) -> int:
         """Remove messages that exist in agent_messages but not in message_structure.
 
         This can happen if _add_structure_metadata fails after super().add_items() succeeds.
diff --git a/src/agents/extensions/memory/async_sqlite_session.py b/src/agents/extensions/memory/async_sqlite_session.py
@@ -11,6 +11,7 @@
 
 from ...items import TResponseInputItem
 from ...memory import SessionABC
+from ...memory.session_settings import SessionSettings
 
 
 class AsyncSQLiteSession(SessionABC):
@@ -21,6 +22,8 @@ class AsyncSQLiteSession(SessionABC):
     For persistent storage, provide a file path.
     """
 
+    session_settings: SessionSettings | None = None
+
     def __init__(
         self,
         session_id: str,
diff --git a/src/agents/extensions/models/litellm_model.py b/src/agents/extensions/models/litellm_model.py
@@ -186,7 +186,7 @@ async def get_response(
                 choice = response.choices[0]
                 if isinstance(choice, litellm.types.utils.Choices):
                     first_choice = choice
-                    message = first_choice.message
+                    message = choice.message
 
             if _debug.DONT_LOG_MODEL_DATA:
                 logger.debug("Received model response")
diff --git a/src/agents/mcp/server.py b/src/agents/mcp/server.py
@@ -71,6 +71,19 @@ class _UnsetType:
     from ..agent import AgentBase
 
 
+MCPStreamTransport = (
+    tuple[
+        MemoryObjectReceiveStream[SessionMessage | Exception],
+        MemoryObjectSendStream[SessionMessage],
+    ]
+    | tuple[
+        MemoryObjectReceiveStream[SessionMessage | Exception],
+        MemoryObjectSendStream[SessionMessage],
+        GetSessionIdCallback | None,
+    ]
+)
+
+
 class MCPServer(abc.ABC):
     """Base class for Model Context Protocol servers."""
 
@@ -420,13 +433,7 @@ async def _apply_dynamic_tool_filter(
     @abc.abstractmethod
     def create_streams(
         self,
-    ) -> AbstractAsyncContextManager[
-        tuple[
-            MemoryObjectReceiveStream[SessionMessage | Exception],
-            MemoryObjectSendStream[SessionMessage],
-            GetSessionIdCallback | None,
-        ]
-    ]:
+    ) -> AbstractAsyncContextManager[MCPStreamTransport]:
         """Create the streams for the server."""
         pass
 
@@ -860,13 +867,7 @@ def __init__(
 
     def create_streams(
         self,
-    ) -> AbstractAsyncContextManager[
-        tuple[
-            MemoryObjectReceiveStream[SessionMessage | Exception],
-            MemoryObjectSendStream[SessionMessage],
-            GetSessionIdCallback | None,
-        ]
-    ]:
+    ) -> AbstractAsyncContextManager[MCPStreamTransport]:
         """Create the streams for the server."""
         return stdio_client(self.params)
 
@@ -970,13 +971,7 @@ def __init__(
 
     def create_streams(
         self,
-    ) -> AbstractAsyncContextManager[
-        tuple[
-            MemoryObjectReceiveStream[SessionMessage | Exception],
-            MemoryObjectSendStream[SessionMessage],
-            GetSessionIdCallback | None,
-        ]
-    ]:
+    ) -> AbstractAsyncContextManager[MCPStreamTransport]:
         """Create the streams for the server."""
         return sse_client(
             url=self.params["url"],
@@ -1092,13 +1087,7 @@ def __init__(
 
     def create_streams(
         self,
-    ) -> AbstractAsyncContextManager[
-        tuple[
-            MemoryObjectReceiveStream[SessionMessage | Exception],
-            MemoryObjectSendStream[SessionMessage],
-            GetSessionIdCallback | None,
-        ]
-    ]:
+    ) -> AbstractAsyncContextManager[MCPStreamTransport]:
         """Create the streams for the server."""
         # Only pass httpx_client_factory if it's provided
         if "httpx_client_factory" in self.params:
diff --git a/src/agents/prompts.py b/src/agents/prompts.py
@@ -2,7 +2,7 @@
 
 import inspect
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any, Callable, cast
 
 from openai.types.responses.response_prompt_param import (
     ResponsePromptParam,
@@ -47,6 +47,11 @@ class GenerateDynamicPromptData:
 """A function that dynamically generates a prompt."""
 
 
+def _coerce_prompt_dict(prompt: Prompt | dict[object, object]) -> Prompt:
+    """Convert a runtime-validated prompt dict into the Prompt TypedDict view."""
+    return cast(Prompt, prompt)
+
+
 class PromptUtil:
     @staticmethod
     async def to_model_input(
@@ -59,7 +64,7 @@ async def to_model_input(
 
         resolved_prompt: Prompt
         if isinstance(prompt, dict):
-            resolved_prompt = prompt
+            resolved_prompt = _coerce_prompt_dict(prompt)
         else:
             func_result = prompt(GenerateDynamicPromptData(context=context, agent=agent))
             if inspect.isawaitable(func_result):
diff --git a/src/agents/run_internal/tool_execution.py b/src/agents/run_internal/tool_execution.py
@@ -85,6 +85,7 @@
 from ..tracing import Span, SpanError, function_span, get_current_trace
 from ..util import _coro, _error_tracing
 from ..util._approvals import evaluate_needs_approval_setting
+from ..util._types import MaybeAwaitable
 from ._asyncio_progress import get_function_tool_task_progress_deadline
 from .approvals import append_approval_error_output
 from .items import (
@@ -945,16 +946,22 @@ async def with_tool_function_span(
     *,
     config: RunConfig,
     tool_name: str,
-    fn: Callable[[Span[Any] | None], Any],
+    fn: Callable[[Span[Any] | None], MaybeAwaitable[TToolSpanResult]],
 ) -> TToolSpanResult:
     """Execute a tool callback in a function span when tracing is active."""
     if config.tracing_disabled or get_current_trace() is None:
         result = fn(None)
-        return await result if inspect.isawaitable(result) else cast(TToolSpanResult, result)
+        if inspect.isawaitable(result):
+            return await result
+        direct_result: object = result
+        return cast(TToolSpanResult, direct_result)
 
     with function_span(tool_name) as span:
         result = fn(span)
-        return await result if inspect.isawaitable(result) else cast(TToolSpanResult, result)
+        if inspect.isawaitable(result):
+            return await result
+        span_result: object = result
+        return cast(TToolSpanResult, span_result)
 
 
 def build_litellm_json_tool_call(output: ResponseFunctionToolCall) -> FunctionTool:
diff --git a/tests/mcp/test_prompt_server.py b/tests/mcp/test_prompt_server.py
@@ -93,6 +93,7 @@ async def test_list_prompts():
 
     assert len(result.prompts) == 1
     assert result.prompts[0].name == "generate_code_review_instructions"
+    assert result.prompts[0].description is not None
     assert "code review" in result.prompts[0].description
 
 
diff --git a/tests/test_session.py b/tests/test_session.py
@@ -526,7 +526,12 @@ def add_item(item):
 
         # Retrieve all items and verify all are present
         retrieved = await session.get_items()
-        contents = {item.get("content") for item in retrieved}
+        contents = {
+            content
+            for item in retrieved
+            for content in [item.get("content")]
+            if isinstance(content, str)
+        }
         expected = {f"Message {i}" for i in range(10)}
         assert contents == expected
         session.close()
diff --git a/tests/test_session_protocol_typing.py b/tests/test_session_protocol_typing.py
diff --git a/tests/test_strict_schema_oneof.py b/tests/test_strict_schema_oneof.py
@@ -119,10 +119,8 @@ class BuyFoodStep(BaseModel):
         action: Literal["buy_food"]
         args: FoodArgs
 
-    Step = Annotated[Union[BuyFruitStep, BuyFoodStep], Field(discriminator="action")]
-
     class Actions(BaseModel):
-        steps: list[Step]
+        steps: list[Annotated[Union[BuyFruitStep, BuyFoodStep], Field(discriminator="action")]]
 
     output_schema = AgentOutputSchema(Actions)
     schema = output_schema.json_schema()
diff --git a/tests/voice/test_pipeline.py b/tests/voice/test_pipeline.py
@@ -73,6 +73,7 @@ async def run(self, text: str, settings: TTSModelSettings):
     audio_chunks: list[bytes] = []
     while True:
         event = await local_queue.get()
+        assert event is not None
         if isinstance(event, VoiceStreamEventAudio) and event.data is not None:
             audio_chunks.append(event.data.tobytes())
         if isinstance(event, VoiceStreamEventLifecycle) and event.event == "turn_ended":
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -74,6 +74,7 @@ dev = [`
`74`	`74`	`"dapr>=1.14.0",`
`75`	`75`	`"grpcio>=1.60.0",`
`76`	`76`	`"testcontainers==4.12.0", # pinned to 4.12.0 because 4.13.0 has a warning bug in wait_for_logs, see https://github.com/testcontainers/testcontainers-python/issues/874`
	`77`	`+ "pyright==1.1.408",`
`77`	`78`	`]`
`78`	`79`
`79`	`80`	`[tool.uv.workspace]`