RiLdZddlmZddlZddlZddlZddlZddlZddlm Z m Z ddl m Z m Z ddl mZmZmZddlZddlmZmZddlmZmZdd lmZeeZerdd lmZmZGd d eZed Z GddejBee Z"Gdde"dZ#Gdde"ejHjJZ&Gdde"e'ejHjPejHjRzZ*y)zSEP-1686 client Task classes.) annotationsN) AwaitableCallable)datetimetimezone) TYPE_CHECKINGGenericTypeVar) GetTaskResultTaskStatusNotification)MessageMessageHandler) get_logger)CallToolResultClientc0eZdZdZdfd Zdfd ZxZS)TaskNotificationHandlerzEMessageHandler that routes task status notifications to Task objects.cVt|tj||_yN)super__init__weakrefref _client_ref)selfclient __class__s z/home/jay/workspace/.worktrees/task-2117-dev1/scripts/.codegraph-venv/lib/python3.12/site-packages/fastmcp/client/tasks.pyrz TaskNotificationHandler.__init__s 07 F0CcKt|tjjrGt|jt r-|j }|r|j|jt|%|d{y7w)z7Dispatch messages, including task status notifications.N) isinstancemcptypesServerNotificationrootr r _handle_task_status_notificationrdispatch)rmessagerrs rr'z TaskNotificationHandler.dispatch!s` gsyy;; <',,(>?))+;;GLLIgw'''sA>B BB )rr)r(r returnNone)__name__ __module__ __qualname____doc__rr' __classcell__rs@rrrsOD((rr TaskResultTceZdZdZ d ddZddZeddZeddZddZ ddZ dd Z e jdd Zdd d  dd ZddZdZy)Taska Abstract base class for MCP background tasks (SEP-1686). Provides a uniform API whether the server accepts background execution or executes synchronously (graceful degradation per SEP-1686). Subclasses: - ToolTask: For tool calls (result type: CallToolResult) - PromptTask: For prompts (future, result type: GetPromptResult) - ResourceTask: For resources (future, result type: ReadResourceResult) Ncx||_||_||_|du|_d|_d|_g|_d|_y)z Create a Task wrapper. Args: client: The FastMCP client task_id: The task identifier immediate_result: If server executed synchronously, the immediate result N)_client_task_id_immediate_result _is_immediate _status_cache _status_event_status_callbacks_cached_result)rrtask_idimmediate_results rrz Task.__init__<sP  !1-T94837  37rc|jry |jj}y#t$r}td|d}~wwxYw)zValidate that client context is still active. Raises: RuntimeError: If accessed outside client context (unless immediate) NzoCannot access task results outside client context. Task futures must be used within 'async with client:' block.)r8r5session RuntimeError)r_es r_check_client_connectedzTask._check_client_connectedWsL      $$A O  s& A ;Ac|jS)zGet the task ID.)r6rs rr=z Task.task_idhs}}rc|jS)zCheck if server executed the task immediately. Returns: True if server executed synchronously (graceful degradation or no task support) False if server accepted background execution )r8rFs rreturned_immediatelyzTask.returned_immediatelyms!!!rcF||_|j|jj|jD]5} ||}t j |rt j|7y#t$r$}tjd|dYd}~ad}~wwxYw)aProcess incoming notifications/tasks/status (internal). Called by Client when a notification is received for this task. Updates cache, triggers events, and invokes user callbacks. Args: status: Task status from notification NzTask callback error: T)exc_info) r9r:setr;inspect isawaitableasyncio create_task Exceptionloggerwarning)rstatuscallbackresultrCs r_handle_status_notificationz Task._handle_status_notificationws$    )    " " $.. KH K!&)&&v.''/  K  K!6qc:TJJ Ks2A33 B <BB c:|jj|y)a>Register callback for status change notifications. The callback will be invoked when a notifications/tasks/status is received for this task (optional server feature per SEP-1686 lines 436-444). Supports both sync and async callbacks (auto-detected). Args: callback: Function to call with GetTaskResult when status changes. Can return None (sync) or Awaitable[None] (async). Example: >>> task = await client.call_tool("slow_operation", {}, task=True) >>> >>> def on_update(status: GetTaskResult): ... print(f"Task {status.taskId} is now {status.status}") >>> >>> task.on_status_change(on_update) >>> result = await task # Callback fires when status changes N)r;append)rrTs ron_status_changezTask.on_status_changes0 %%h/rcrK|j|jr>tjtj }t |jd||ddS|j|j}|S|jj|jd{|_|jS7w)zGet current task status. If server executed immediately, returns synthetic completed status. Otherwise queries the server for current status. completedNi)taskIdrS createdAt lastUpdatedAtttl pollInterval) rDr8rnowrutcr r6r9r5get_task_status)rracacheds rrSz Task.statuss $$&   ,,x||,C }}"!!      )''FM$(<<#?#? #NN!!!OsBB7B5 B7c Kyw)zWait for and return the task result. Must be implemented by subclasses to return the appropriate result type. NrFs rrUz Task.results sgr@)statetimeoutc `K|j|jr|jd{S|jt j |_t j }hd}d} |jr9|jj}|||vr|jS||k(r |jSt j |z }||k\r#td|jd|xsdd|d||z } t j|jjt|| d{|jj7+7"#tj$r6|jj|jd{7|_YNwxYww) aWait for task to reach a specific state or complete. Uses event-based waiting when notifications are available (fast), with fallback to polling (reliable). Optimally wakes up immediately on status changes when server sends notifications/tasks/status. Args: state: Desired state ('submitted', 'working', 'completed', 'failed'). If None, waits for any terminal state (completed/failed) timeout: Maximum time to wait in seconds Returns: GetTaskResult: Final task status Raises: TimeoutError: If desired state not reached within timeout N>failed cancelledr[g?zTask z did not reach zterminal statez within s)rh)rDr8rSr:rNEventtimer9 TimeoutErrorr6wait_forwaitminclearr5rc) rrgrhstartterminal_states poll_intervalcurrentelapsed remainings rrqz Task.waits( $$&   & &    %!(D  > !!,,33=/1#111%---iikE)G'!"DMM?/%:SCS9TT\]d\eefg ')I W&&&&++-s=)7T""((*1'>'' W+/<<+G+G +V%V%V" WsR0F.EC F.E"F. E"";F+F  F+(F.*F++F.cK|jry|j|jj|jd{d|_y7 w)aOCancel this task, transitioning it to cancelled state. Sends a tasks/cancel protocol request. The server will attempt to halt execution and move the task to cancelled state. Note: If server executed immediately (graceful degradation), this is a no-op as there's no server-side task to cancel. N)r8rDr5 cancel_taskr6r9rFs rcancelz Task.cancelsI     $$&ll&&t}}555! 6sAAA Ac>|jjS)z!Allow 'await task' to get result.)rU __await__rFs rr~zTask.__await__!s{{}&&((rr)rrr=strr>zTaskResultT | None)r)r*)r)r)r)bool)rSr r)r*)rTz1Callable[[GetTaskResult], None | Awaitable[None]]r)r*)r)r )r)r1)rgz str | Nonerhfloatr)r )r+r,r-r.rrDpropertyr=rHrVrYrSabcabstractmethodrUrqr|r~rfrrr3r3/s  04 777- 76"""K40C0 04"<   &*E=W"=W49=W =W~"")rr3c>eZdZdZ d dfd ZddZxZS)ToolTaskaM Represents a tool call that may execute in background or immediately. Provides a uniform API whether the server accepts background execution or executes synchronously (graceful degradation per SEP-1686). Usage: task = await client.call_tool_as_task("analyze", args) # Check status status = await task.status() # Wait for completion await task.wait() # Get result (waits if needed) result = await task.result() # Returns CallToolResult # Or just await the task directly result = await task c6t||||||_y)a Create a ToolTask wrapper. Args: client: The FastMCP client task_id: The task identifier tool_name: Name of the tool being executed immediate_result: If server executed synchronously, the immediate result N)rr _tool_name)rrr= tool_namer>rs rrzToolTask.__init__=s *:;#rcK|j |jS|jr|jJ|j}n|j|j d{|j j |jd{}t|trZtjjj|}|j j|j|dd{}nt|tjjr1|j j|j|dd{}nt!|dr}t!|drqtjj|j"|j$|j&}|j j|j|dd{}n|}||_|S77[777w)a#Wait for and return the tool result. If server executed immediately, returns the immediate result. Otherwise waits for background task to complete and retrieves result. Returns: CallToolResult: The parsed tool result (same as call_tool returns) NT)raise_on_errorcontentstructured_content)rstructuredContent_meta)r<r8r7rDrqr5get_task_resultr6r!dictr"r#rmodel_validate_parse_call_tool_resultrhasattrrrmeta)rrU raw_result mcp_results rrUzToolTask.resultPs    *&& &   ))5 55++F  ( ( *))+   $||;;DMMJJJ*d+ YY55DDZP #||CCOOZ D J (@(@A#||CCOOZ D  :y1g 47"%!9!9 * 2 2*4*G*G(oo":"J $(<<#G#GD$H$F (F% I K  s]A$G7&G+',G7G.A(G7<G1=AG7G3BG7G5G7.G71G73G75G7r)rrr=rrrr>zCallToolResult | None)r)rr+r,r-r.rrUr/r0s@rrr&s=637 $$$ $ 0 $&9rrrc>eZdZdZ d dfd ZddZxZS) PromptTaskac Represents a prompt call that may execute in background or immediately. Provides a uniform API whether the server accepts background execution or executes synchronously (graceful degradation per SEP-1686). Usage: task = await client.get_prompt_as_task("analyze", args) result = await task # Returns GetPromptResult c6t||||||_y)a Create a PromptTask wrapper. Args: client: The FastMCP client task_id: The task identifier prompt_name: Name of the prompt being executed immediate_result: If server executed synchronously, the immediate result N)rr _prompt_name)rrr= prompt_namer>rs rrzPromptTask.__init__s *:;'rcK|j |jS|jr|jJ|j}n~|j|j d{|j j |jd{}tjjj|}||_|S7c78w)a#Wait for and return the prompt result. If server executed immediately, returns the immediate result. Otherwise waits for background task to complete and retrieves result. Returns: GetPromptResult: The prompt result with messages and description N) r<r8r7rDrqr5rr6r"r#GetPromptResultr)rrUrs rrUzPromptTask.results    *&& &   ))5 55++F  ( ( *))+   $||;;DMMJJJYY..==jIF%  Ks$A#C %C &,C C 7C  C r)rrr=rrrr>z mcp.types.GetPromptResult | None)r)zmcp.types.GetPromptResultrr0s@rrrs>  >B ((( ( ; (&rrcBeZdZdZ d dfd Z ddZxZS) ResourceTaskaw Represents a resource read that may execute in background or immediately. Provides a uniform API whether the server accepts background execution or executes synchronously (graceful degradation per SEP-1686). Usage: task = await client.read_resource_as_task("file://data.txt") contents = await task # Returns list[ReadResourceContents] c6t||||||_y)a Create a ResourceTask wrapper. Args: client: The FastMCP client task_id: The task identifier uri: URI of the resource being read immediate_result: If server executed synchronously, the immediate result N)rr_uri)rrr=urir>rs rrzResourceTask.__init__s& *:; rcdK|j |jS|jr|jJ|j}n^|j|j d{|j j |jd{}t|tjjrt|j}nt|trd|vrg}|dD]}t|trvd|vr9|jtjj j#|P|jtjj$j#||j||}nt|tr|n|g}||_|S7D7w)aWait for and return the resource contents. If server executed immediately, returns the immediate result. Otherwise waits for background task to complete and retrieves result. Returns: list[ReadResourceContents]: The resource contents Ncontentsblob)r<r8r7rDrqr5rr6r!r"r#ReadResourceResultlistrrrXBlobResourceContentsrTextResourceContents)rrUrparsed_contentsitems rrUzResourceTask.resultsw    *&& &   ))5 55++F  ( ( *))+   $||;;DMMJJJ*cii&B&BCj112J-* 2J"$&z2 5D!$-!T>+22 # > > M Md S,22 # > > M Md S(..t4 5)(2*d'C*% ? Ks%A$F0&F*',F0F-DF0-F0r)rrr=rrrr>zLlist[mcp.types.TextResourceContents | mcp.types.BlobResourceContents] | None)r)zElist[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]rr0s@rrrsE &   ,6 N6rr)+r. __future__rrrNrLrnrcollections.abcrrrrtypingrr r mcp.typesr"r r fastmcp.client.messagesr rfastmcp.utilities.loggingrr+rQfastmcp.client.clientrrrr1ABCr3rr#rrrrrrrfrrrs#"  /'22;;0 H <(n($m$ t)377GK(t)nct$%cL>cii//0>BZcii,,syy/M/MM NOZr