Rmj(dZddlZddlmZmZddlmZmZddlm Z m Z ddl m Z ddl mZddlmZdd lmZdd lmZdd lmZdd lmZmZdd lmZmZmZmZmZm Z m!Z!m"Z"m#Z#m$Z$dZ%eGddZ&dS)a  Experimental request context features. This module provides the Experimental class which gives access to experimental features within a request context, such as task-augmented request handling. WARNING: These APIs are experimental and may change without notice. N) AwaitableCallable) dataclassfield)Anyoverload) deprecated)ServerTaskContext)scoped_task_id) TaskSupport) ServerSession)McpError)MODEL_IMMEDIATE_RESPONSE_KEY is_terminal) METHOD_NOT_FOUNDTASK_FORBIDDEN TASK_REQUIREDClientCapabilitiesCreateTaskResult ErrorDataResultTaskExecutionMode TaskMetadataToolaRPassing an explicit task_id to run_task is deprecated. A task created with an explicit ID is not associated with the session that created it: any requestor that presents the ID can read its status and result or cancel it, and it never appears in tasks/list. Omit task_id to let the SDK generate an ID associated with the creating session.c LeZdZUdZdZedzed<eddZe dzed<eddZ e dzed<eddZ e dzed<ed efd Zed efd Zd d dedzded edzfdZd d deded edzfdZdedzd efdZeddddeegeefdddedzd efdZee e!dddeegeefdededzd efdZddddeegeefdedzdedzd efdZdS) Experimentala Experimental features context for task-augmented requests. Provides helpers for validating task execution compatibility and running tasks with automatic lifecycle management. WARNING: This API is experimental and may change without notice. N task_metadataF)defaultrepr_client_capabilities_session _task_supportreturnc|jduS)z(Check if this request is task-augmented.N)rselfs o/home/thesage/.hermes/hermes-agent/venv/lib/python3.11/site-packages/mcp/server/experimental/request_context.pyis_taskzExperimental.is_task=s!--c0|jdS|jjduS)z*Check if the client declared task support.NF)r tasksr%s r'client_supports_tasksz"Experimental.client_supports_tasksBs#  $ ,5(.d::r)T raise_errortool_task_moder.c|pt}d}|tkr|jsttd}n(|tkr|jrttd}||rt ||S)a Validate that the request is compatible with the tool's task execution mode. Per MCP spec: - "required": Clients MUST invoke as task. Server returns -32601 if not. - "forbidden" (or None): Clients MUST NOT invoke as task. Server returns -32601 if they do. - "optional": Either is acceptable. Args: tool_task_mode: The tool's execution.taskSupport value ("forbidden", "optional", "required", or None) raise_error: If True, raises McpError on validation failure. If False, returns ErrorData. Returns: None if valid, ErrorData if invalid and raise_error=False Raises: McpError: If invalid and raise_error=True Nz,This tool requires task-augmented invocation)codemessagez4This tool does not support task-augmented invocation)rrr(rrr)r&r/r.modeerrors r'validate_task_modezExperimental.validate_task_modeIs4/"& =  %FEE^ # # #%NE   5// ! r)toolcZ|jr |jjnd}|||S)a Validate that the request is compatible with the given tool. Convenience wrapper around validate_task_mode that extracts the mode from a Tool. Args: tool: The Tool definition raise_error: If True, raises McpError on validation failure. Returns: None if valid, ErrorData if invalid and raise_error=False Nr-) execution taskSupportr5)r&r6r.r3s r'validate_for_toolzExperimental.validate_for_toolws3$.2^Et~))&&t&EEEr)c@|pt}|tkr |jsdSdS)a Check if this client can use a tool with the given task mode. Useful for filtering tool lists or providing warnings. Returns False if tool requires "required" but client doesn't support tasks. Args: tool_task_mode: The tool's execution.taskSupport value Returns: True if the client can use this tool, False otherwise FT)rrr,)r&r/r3s r' can_use_toolzExperimental.can_use_tools+/ = )C 5tr))task_idmodel_immediate_responseworkr=r>c KdSNr&r?r=r>s r'run_taskzExperimental.run_tasks 3r))r>c KdSrArBrCs r'rDzExperimental.run_tasks 3r)cR K|!tjttd|jt d|jt d|jt d|j}|j}|$|jj }|j }|t|}|j |j|d{V}t||j |j|j|j d fd } || d} | t$|i} t'd d |i| rd | iniS)aV Create a task, spawn background work, and return CreateTaskResult immediately. This is the recommended way to handle task-augmented tool calls. It: 1. Creates a task in the store 2. Spawns the work function in a background task 3. Returns CreateTaskResult immediately The work function receives a ServerTaskContext with: - elicit() for sending elicitation requests - create_message() for sampling requests - update_status() for progress updates - complete()/fail() for finishing the task When work() returns a Result, the task is auto-completed with that result. If work() raises an exception, the task is auto-failed. Generated task IDs embed the session's task scope so that the default task handlers only serve the task to the session that created it. An explicitly provided `task_id` is used verbatim and is not associated with the session, so any session can access it through the default handlers; passing one is deprecated for that reason. Args: work: Async function that does the actual work task_id: Deprecated. Optional task ID, used verbatim and not associated with the creating session. Omit it to let the SDK generate one. model_immediate_response: Optional string to include in _meta as io.modelcontextprotocol/model-immediate-response Returns: CreateTaskResult to return to the client Raises: RuntimeError: If task support is not enabled or task_metadata is missing Example: @server.call_tool() async def handle_tool(name: str, args: dict): ctx = server.request_context async def work(task: ServerTaskContext) -> CallToolResult: result = await task.elicit( message="Are you sure?", requestedSchema={"type": "object", ...} ) confirmed = result.content.get("confirm", False) return CallToolResult(content=[TextContent(text="Done" if confirmed else "Cancelled")]) return await ctx.experimental.run_task(work) WARNING: This API is experimental and may change without notice. N) stacklevelzHTask support not enabled. Call server.experimental.enable_tasks() first.zSession not available.zgRequest is not task-augmented (no task field in params). The client must send a task-augmented request.)taskstoresessionqueuehandlerr#cZK d{V}tjjs|d{VdSdS#t$rR}tjjs.t |d{VYd}~dSYd}~dSd}~wwxYwrA)rrIstatuscomplete Exceptionfailstr)resultetask_ctxr?s r'executez&Experimental.run_task..executes 0#tH~~------"8=#7884"++F3333333333344 0 0 0"8=#7880"--A///////////////000000 0sAA B*AB%%B*rI_meta)r#NrB)warningswarnEXPLICIT_TASK_ID_DEPRECATIONDeprecationWarningr" RuntimeErrorr!r task_group _experimentaltask_session_scoper rJ create_taskr rLrM start_soonrr) r&r?r=r>supportr^features session_scoperIrWmetarVs ` @r'rDzExperimental.run_tasksz   M68JWX Y Y Y Y   %ijj j = 788 8   %A  $' ?}2H$7M((77]..t/A7KKKKKKKK$-M-O     0 0 0 0 0 0 0 g&&&&* # /02JKDMMTM-Lgt__"MMMr))"__name__ __module__ __qualname____doc__rr__annotations__rr rr!r r"r propertyboolr(r,rrr5rr:r<rrr rrrSrrDr r[rBr)r'rr-s *.M<$&---6;eDu6U6U6U,t3UUU%*U4e%D%D%DHmd"DDD(-d(G(G(GM;%GGG ....X.;t;;;X;! ,,,)D0, , T  ,,,,d! FFFF F T  FFFF*+  #&*   XZ,-- 04 )*If,==>  #&*   .-X#/3 lNlNlN)*If,==>lNt lN #&* lN  lNlNlNlNlNlNr)r)'rjrYcollections.abcrr dataclassesrrtypingrrtyping_extensionsr $mcp.server.experimental.task_contextr "mcp.server.experimental.task_scoper $mcp.server.experimental.task_supportr mcp.server.sessionr mcp.shared.exceptionsr%mcp.shared.experimental.tasks.helpersrr mcp.typesrrrrrrrrrrr[rrBr)r'rys////////(((((((( ((((((BBBBBB======<<<<<<,,,,,,******[[[[[[[[                        ! oNoNoNoNoNoNoN oNoNoNr)