Test Failure Analysis

Summary: The Windows Python 3.10 test failed with a 5-second timeout in test_init_with_explicit_params from test_workos.py. This appears to be an unrelated, pre-existing Windows-specific issue with SQLite disk access, not caused by the PR changes.

Root Cause: The timeout occurs during WorkOSProvider initialization when creating a DiskStore object, specifically at:

# oauth_proxy.py:822
key_value=DiskStore(directory=settings.home / "oauth-proxy")

The stack trace shows the hang happens in sqlite3.connect() within the diskcache library. This is a known Windows issue where SQLite can timeout due to file locking or disk access delays.

Why This is NOT Related to the PR:

1. The PR only modifies Context.report_progress() in context.py
2. The failing test (test_init_with_explicit_params) never calls report_progress() - it only creates a provider object
3. The import added by the PR (from docket.dependencies import Dependency) is inside the report_progress method and only executed when the method is called
4. All other test suites passed, including Ubuntu Python 3.10, 3.13, integration tests, and lowest-direct dependencies

Evidence:

• Only Windows Python 3.10 failed; Ubuntu Python 3.10/3.13 passed ✅
• The timeout is in provider initialization (DiskStore/SQLite), not progress reporting
• The failing test doesn't exercise any code path modified by this PR

File "oauth_proxy.py", line 822, in __init__
    key_value=DiskStore(directory=settings.home / "oauth-proxy"),
File "diskcache/core.py", line 623, in _con
    con = self._local.con = sqlite3.connect(
+++++++++++++++++++++++++++++++++++ Timeout +++++++++++++++++++++++++++++++++++

Suggested Solution:

This is a flaky Windows test issue, not a PR regression. Options:

1. Re-run the Windows tests to see if it passes on retry (recommended)
2. Investigate the Windows SQLite timeout separately as a flaky test issue
3. Consider adding a longer timeout or mark as flaky specifically for Windows

The PR changes are sound and all related tests pass. The failure is coincidental timing with an unrelated infrastructure issue.

Walkthrough

The report_progress method in the Context class has been updated to support an optional message parameter and implement dual-context progress reporting. When a progress_token is available, it sends MCP foreground progress notifications. Otherwise, it attempts to update Docket background progress in Redis by retrieving the current Execution, computing progress deltas, and propagating messages. The implementation includes graceful error handling for unavailable Docket contexts and conditional background progress handling that depends on Docket availability and worker context.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Test Failure Analysis

Summary: Type checker (ty) is failing because redis.blpop() expects a list of keys but is being passed a single string, and redis.lpush() has ambiguous return type handling.

Root Cause: The PR changes elicitation response handling from polling to BLPOP/LPUSH for efficiency. However, the Redis client's type signatures require:

1. blpop() expects keys: List (multiple keys to check), not a single string
2. lpush() may return different types (sync/async) depending on the Redis client variant, causing type ambiguity

Suggested Solution: Wrap the single key in a list for blpop() and ensure proper await handling for lpush().

Changes needed in src/fastmcp/server/tasks/elicitation.py:

1. Line 149-152: Change blpop() to accept a list:

   result = await redis.blpop(
       [docket.key(response_key)],  # Wrap in list
       timeout=max_wait_seconds,
   )

2. Line 230-233: Ensure lpush() result is properly awaited (likely already correct, but type checker needs clarity):

   await redis.lpush(
       docket.key(response_key),
       json.dumps(response),
   )

   If the issue persists, may need to cast or annotate the redis client type more explicitly.

error[invalid-argument-type]: Argument to bound method `blpop` is incorrect
   --> src/fastmcp/server/tasks/elicitation.py:150:17
    |
150 |                 docket.key(response_key),
    |                 ^^^^^^^^^^^^^^^^^^^^^^^^ Expected `list[Unknown]`, found `Unknown | str`

def blpop(
    self, keys: List, timeout: Optional[Number] = 0
) -> Union[Awaitable[list], list]:

error[invalid-await]: `Unknown | Awaitable[int] | int` is not awaitable
   --> src/fastmcp/server/tasks/elicitation.py:230:15

Test Failure Analysis

Summary: Type checker () is failing because expects a list of keys as the first argument, but the code is passing a single string.

Root Cause: The PR changes the elicitation mechanism from polling with to blocking with . However, the method in redis-py requires its first argument to be a list of keys, not a single string:

# Current code (line 149):
result = await redis.blpop(
    docket.key(response_key),  # ❌ Single string
    timeout=max_wait_seconds,
)

# Should be:
result = await redis.blpop(
    [docket.key(response_key)],  # ✅ List of keys
    timeout=max_wait_seconds,
)

The type errors are:

1. Line 149: invalid-await - Type checker sees return type as ambiguous because it can't match the call signature
2. Lines 150: invalid-argument-type - Expected list[Unknown], found Unknown | str
3. Line 238: invalid-await - Similar issue with redis.lpush() which also needs proper type hints

Suggested Solution:

1. Fix the blpop call by wrapping the key in a list:

   result = await redis.blpop(
       [docket.key(response_key)],
       timeout=max_wait_seconds,
   )

2. Fix the lpush call similarly if needed (line 238) - check if lpush also requires a list

def blpop(self, keys: List, timeout: Optional[Number] = 0) -> Union[Awaitable[list], list]

error[invalid-await]: `Unknown | Awaitable[list[Unknown]] | list[Unknown]` is not awaitable

error[invalid-argument-type]: Expected `list[Unknown]`, found `Unknown | str`

Test Failure Analysis

Summary: Static analysis (type checking) failed due to incorrect argument types for Redis blpop and lpush methods in the elicitation refactoring.

Root Cause: The PR refactored from polling with redis.get()/redis.set() to blocking operations with redis.blpop()/redis.lpush(), but the argument types don't match the redis-py signatures:

1. Line 150: redis.blpop() expects keys: List but receives a single string from docket.key(response_key)
2. Line 238: redis.lpush() isn't being properly awaited according to the type checker (union type issue)

Suggested Solution:

Fix 1: Wrap the key in a list for blpop:

# Line 149-151
result = await redis.blpop(
    [docket.key(response_key)],  # Wrap in list
    timeout=max_wait_seconds,
)

Fix 2: Cast or handle the lpush return type properly:

# Line 238-241
await redis.lpush(
    docket.key(response_key),
    json.dumps(response),
)

The lpush issue might be a false positive from the type checker due to the union type Unknown | Awaitable[int] | int. Since you're already using await, this should work at runtime, but you might need to add a type ignore comment if the type checker continues to complain after fixing the blpop issue.

error[invalid-argument-type]: Argument to bound method `blpop` is incorrect
   --> src/fastmcp/server/tasks/elicitation.py:150:17
    |
150 |                 docket.key(response_key),
    |                 ^^^^^^^^^^^^^^^^^^^^^^^^ Expected `list[Unknown]`, found `Unknown | str`

error[invalid-await]: `Unknown | Awaitable[int] | int` is not awaitable
   --> src/fastmcp/server/tasks/elicitation.py:238:15
    |
238 |           await redis.lpush(
    |  _______________^
239 | |             docket.key(response_key),
240 | |             json.dumps(response),
241 | |         )
    | |_________^

Test Failure Analysis

Summary: All tests are failing on import with ImportError: cannot import name 'UTC' from 'datetime' in the newly added notifications.py file.

Root Cause: The new file src/fastmcp/server/tasks/notifications.py imports UTC from the datetime module at line 25:

from datetime import UTC, datetime

However, datetime.UTC was only added in Python 3.11. FastMCP supports Python ≥3.10 (as stated in CLAUDE.md and pyproject.toml), and the CI is testing on Python 3.10.19, causing an immediate import error that prevents any tests from running.

Suggested Solution: Use timezone.utc instead, which is the Python 3.10-compatible approach already used throughout the codebase.

Change needed in src/fastmcp/server/tasks/notifications.py:25:

# Current (line 25):
from datetime import UTC, datetime

# Should be:
from datetime import datetime, timezone

Then update any usage of UTC in the file to timezone.utc.

ImportError: cannot import name 'UTC' from 'datetime' 
(/home/runner/work/_temp/uv-python-dir/cpython-3.10.19-linux-x86_64-gnu/lib/python3.10/datetime.py)

Updated analysis based on latest workflow run (21670322009) - 2026-02-04

Test Failure Analysis

Summary: All Python 3.10 tests are failing due to ImportError: cannot import name 'UTC' in the newly added notifications.py file.

Root Cause: The new file src/fastmcp/server/tasks/notifications.py uses from datetime import UTC, datetime at line 25. However, datetime.UTC was only added in Python 3.11, while FastMCP supports Python ≥3.10.

Suggested Solution: Replace UTC with timezone.utc to maintain Python 3.10 compatibility. This is the pattern used consistently throughout the codebase.

In src/fastmcp/server/tasks/notifications.py:

• Change line 25 from: from datetime import UTC, datetime
• To: from datetime import datetime, timezone
• Change line 66 from: "enqueued_at": datetime.now(UTC).isoformat(),
• To: "enqueued_at": datetime.now(timezone.utc).isoformat(),

src/fastmcp/server/tasks/__init__.py:14: in <module>
    from fastmcp.server.tasks.notifications import (
src/fastmcp/server/tasks/notifications.py:25: in <module>
    from datetime import UTC, datetime
E   ImportError: cannot import name 'UTC' from 'datetime'

Updated analysis based on workflow run 21672391648 - 2026-02-04 13:00 UTC

hey team 👋

follow-up to #2905 — this adds distributed notification support so elicitation actually works for background tasks running on remote workers.

ran a deep review loop and caught a few things worth mentioning:

fixes included in this pr:

• set_current() instead of increment() for progress — atomic, no race condition if the same tool reports from multiple contexts
• fail-fast on push_notification failure — no 1-hour hang waiting for a response that'll never come
• cleanup registration via exit_stack — stop_subscriber actually gets called now
• get_task_context().session_id as single source of truth — removes closure capture mismatch risk

tests: 280 passed, 3 skipped. rebased on main.

happy to walk through any of the implementation details if that would help. is there anything specific you'd like me to adjust before this gets merged?

cc @jlowin @chrisguidry

Test Failure Analysis

Summary: All Python 3.10 tests fail with ImportError: cannot import name 'UTC' from 'datetime' in the new notifications.py file.

Root Cause: The PR adds src/fastmcp/server/tasks/notifications.py:25 with:

from datetime import UTC, datetime

However, datetime.UTC was only introduced in Python 3.11. FastMCP supports Python ≥3.10 (see pyproject.toml), so this import fails on Python 3.10.x.

Suggested Solution: Replace datetime.UTC with the Python 3.10-compatible alternative:

# In src/fastmcp/server/tasks/notifications.py line 25
from datetime import datetime, timezone

# Then use timezone.utc instead of UTC throughout the file
# Example: datetime.now(timezone.utc) instead of datetime.now(UTC)

tests/conftest.py:15 → fastmcp/__init__.py:15 → fastmcp/server/__init__.py:1 
→ fastmcp/server/context.py:28 → fastmcp/resources/__init__.py:1 
→ fastmcp/resources/function_resource.py:17 → fastmcp/resources/resource.py:32 
→ fastmcp/server/tasks/__init__.py:14 
→ fastmcp/server/tasks/notifications.py:25
ImportError: cannot import name 'UTC' from 'datetime'

This is looking really compelling so far, @gfortaine, thank you!

However, similar to the last PR, I'm having trouble with the style of the tests here. I think these heavily mocked tests are going to end up being difficult to maintain over time, because they are mocking many internal implementation details (including of redis itself). Take a look at the surrounding tests task-related tests and you'll see a very stark difference in style.

Can we rework these tests to be simpler by just setting up example MCP servers with task support that make elicitations and then assert that the client sees those elicitations? We should be able to write tests that just "do the thing" because we have redis available (via the memory:// broker) while the tests are running.

In our /python-tests skill in the repo, we've got some good guidance here: https://github.com/jlowin/fastmcp/blob/main/.claude/skills/python-tests/SKILL.md#dont-mock-what-you-own

Test Failure Analysis

Summary: Static type checking failed due to incorrect argument types for Redis blocking operations (blpop, brpop, lpush).

Root Cause: The Redis blpop and brpop methods expect a list of keys as the first argument, but the code passes a single string key. This is a type signature issue in the new elicitation and notification code.

Suggested Solution: Wrap all Redis blocking operation keys in a list:

1. src/fastmcp/server/tasks/elicitation.py:175-178

   result = await redis.blpop(
       [docket.key(response_key)],  # Wrap in list
       timeout=max_wait_seconds,
   )

2. src/fastmcp/server/tasks/notifications.py:107-109

   result = await redis.brpop(
       [queue_key],  # Wrap in list
       timeout=SUBSCRIBER_TIMEOUT_SECONDS
   )

These changes will fix all the type errors because blpop/brpop are designed to accept multiple keys (for fairness when waiting on multiple queues), even though this use case only needs one.

Updated: 2026-02-07 (latest static analysis failure)

Test Failure Analysis

Summary: Static type checking failed with 11 type errors in Redis blocking operations (blpop, brpop, lpush) and test argument types.

Root Cause:

1. Redis blpop/brpop methods expect a list of keys, but the code passes single strings
2. Redis lpush has union return types (Awaitable[int] | int) causing await ambiguity in type checker
3. Test passes potentially None values where str is required

Suggested Solution:

Fix 1: Wrap Redis keys in lists

# src/fastmcp/server/tasks/elicitation.py:175-178
result = await redis.blpop(
    [docket.key(response_key)],  # Wrap in list
    timeout=max_wait_seconds,
)

# src/fastmcp/server/tasks/notifications.py:107-109
result = await redis.brpop(
    [queue_key],  # Wrap in list
    timeout=SUBSCRIBER_TIMEOUT_SECONDS
)

Fix 2: Add type ignores for lpush union types

# src/fastmcp/server/tasks/elicitation.py:264
await redis.lpush(  # type: ignore[misc]
    docket.key(response_key),
    json.dumps(response),
)

# src/fastmcp/server/tasks/notifications.py:70
await redis.lpush(key, message)  # type: ignore[misc]

# src/fastmcp/server/tasks/notifications.py:132
await redis.lpush(queue_key, json.dumps(message))  # type: ignore[misc]

Fix 3: Handle None values in test

# tests/server/tasks/test_notifications.py:53-59
success = await handle_task_input(
    task_id=captured["task_id"] or "",  # Provide fallback
    session_id=captured["session_id"] or "",  # Provide fallback
    action="accept",
    content={"value": "hello"},
    fastmcp=mcp,
)

Updated: 2026-02-08 01:00 UTC (Workflow run 21789768033)

@chrisguidry totally fair — mocking redis internals creates maintenance debt and the contrast with the surrounding task tests was stark. rewrote everything.

• test_context_background_task.py: 896 → 394 lines. Client(mcp) + memory://, zero mocks. tests just spin up a server, call tools with task=True, elicit, assert.
• test_notifications.py: added NotificationCaptureHandler that verifies the client sees notifications/tasks/status with input_required metadata — exactly the end-to-end assertion you asked for.
• only surgical mock: TestElicitFailFast patches push_notification to test fail-fast. everything else is real.

also switched to TaskStatusNotification.model_validate() for typed notification path and fixed the ty static analysis issues.

rebased on v3.0.0b2 (4 commits). how does this land for you?