arkruntime 0.5.0__tar.gz → 0.7.0__tar.gz

{arkruntime-0.5.0/src/arkruntime.egg-info → arkruntime-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkruntime
-Version: 0.5.0
+Version: 0.7.0
 Summary: Ark runtime SDK for Python
 Author: Volcengine
 License: Apache-2.0
@@ -16,6 +16,8 @@ Requires-Dist: sniffio
 Requires-Dist: typing-extensions>=4.7
 Requires-Dist: distro>=1.7.0
 Requires-Dist: volcengine-python-sdk>=5.0.20
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=1.0; python_version >= "3.10" and extra == "mcp"
 Dynamic: license-file
 
 # Ark Runtime Python SDK
@@ -337,6 +339,72 @@ See the [examples/](./examples) directory for runnable scripts:
 
 MCP examples are provided for both clouds and explicitly send `ark-beta-mcp: true`. Other built-in-tool examples are CN-only and show their required beta headers.
 
+## Self-hosted MCP tools
+
+The self-hosted worker core exposes a protocol-independent `MCPClient`
+interface without requiring the official MCP package. Install the optional
+adapter on Python 3.10 or newer when using an official MCP `ClientSession`:
+
+```bash
+pip install 'arkruntime[mcp]'
+```
+
+The official adapter runs through an AnyIO `BlockingPortal`, so it works with
+both asyncio and Trio backends. Create the portal and MCP `ClientSession` in
+the same AnyIO lifecycle, then use `custom_tool_items()` for the Agent
+declaration and `mcp_tools()` for the worker registry. Keep both alive for the
+entire worker lifetime. See the runnable
+[`self_hosted_mcp_worker`](./examples/self_hosted_mcp_worker) example.
+
+The adapter wraps an already connected MCP `ClientSession`, so applications may
+use stdio or another transport supported by their MCP client. One client
+session is reused across all Managed Agents Sessions handled by the worker;
+calls do not automatically include a Managed Agents `session_id` or `work_id`,
+and Session idle/deletion is not an MCP lifecycle notification. Use stateless
+tools or implement explicit tenant/session isolation in the MCP server.
+
+Applications that cannot install the optional package may implement
+`arkruntime.selfhosted.MCPClient` directly. The core SDK continues to support
+Python 3.8, while the official MCP adapter requires Python 3.10 or newer.
+
+Managed Agents currently accepts the top-level JSON Schema fields `type`,
+`properties`, and `required`. The helper keeps those fields structured, inlines
+local `$defs` and `definitions` references used by properties, and appends other
+top-level constraints as compact JSON to the tool description. The MCP server
+remains the authoritative validator when the worker executes the call. Agent
+tool descriptions, including appended constraints, must fit within 10,000
+characters.
+
+Fetch every `tools/list` page, then use the exact same selected definitions for
+the Agent and worker. Managed Agents currently accepts at most eight custom
+tools per Agent. Tool discovery happens at worker startup, so update the Agent
+while it is idle and restart the worker whenever the MCP server changes its
+tool list.
+
+Custom tools do not use Managed Agents permission policies. The worker executes
+each matching call, so implement approval, authorization, and operation
+allowlists in the MCP server or a wrapper tool. Only wrap trusted servers,
+avoid names that collide with built-in Agent tools, add prefixes when multiple
+servers expose the same name, and configure an MCP client timeout. Client-side
+MCP servers run with the worker's OS, filesystem, and network permissions, not
+in a Managed Agents sandbox. Run them with least privilege and a minimal
+environment, and do not pass `ARK_API_KEY` to an MCP subprocess. Tool names,
+descriptions, inputs, and results enter the model context and must be treated
+as untrusted content.
+
+### Tool result support
+
+The worker preserves MCP `isError` and supports text, `image/jpeg`,
+`image/png`, `image/gif`, and `image/webp` image blocks. Embedded resources may
+contain the same image MIME types, `application/pdf`, or text whose MIME type is
+absent, empty, or starts with `text/`. When a result has no content blocks but
+has `structuredContent`, the helper serializes it as compact JSON text.
+
+Audio, resource links, unknown content types, and other resource MIME types
+become an error result. If a result mixes supported and unsupported blocks, the
+whole converted result is an error; the supported blocks are not returned
+separately.
+
 ## Requirements
 
 - Python >= 3.8

{arkruntime-0.5.0 → arkruntime-0.7.0}/README.md

@@ -317,6 +317,72 @@ See the [examples/](./examples) directory for runnable scripts:
 
 MCP examples are provided for both clouds and explicitly send `ark-beta-mcp: true`. Other built-in-tool examples are CN-only and show their required beta headers.
 
+## Self-hosted MCP tools
+
+The self-hosted worker core exposes a protocol-independent `MCPClient`
+interface without requiring the official MCP package. Install the optional
+adapter on Python 3.10 or newer when using an official MCP `ClientSession`:
+
+```bash
+pip install 'arkruntime[mcp]'
+```
+
+The official adapter runs through an AnyIO `BlockingPortal`, so it works with
+both asyncio and Trio backends. Create the portal and MCP `ClientSession` in
+the same AnyIO lifecycle, then use `custom_tool_items()` for the Agent
+declaration and `mcp_tools()` for the worker registry. Keep both alive for the
+entire worker lifetime. See the runnable
+[`self_hosted_mcp_worker`](./examples/self_hosted_mcp_worker) example.
+
+The adapter wraps an already connected MCP `ClientSession`, so applications may
+use stdio or another transport supported by their MCP client. One client
+session is reused across all Managed Agents Sessions handled by the worker;
+calls do not automatically include a Managed Agents `session_id` or `work_id`,
+and Session idle/deletion is not an MCP lifecycle notification. Use stateless
+tools or implement explicit tenant/session isolation in the MCP server.
+
+Applications that cannot install the optional package may implement
+`arkruntime.selfhosted.MCPClient` directly. The core SDK continues to support
+Python 3.8, while the official MCP adapter requires Python 3.10 or newer.
+
+Managed Agents currently accepts the top-level JSON Schema fields `type`,
+`properties`, and `required`. The helper keeps those fields structured, inlines
+local `$defs` and `definitions` references used by properties, and appends other
+top-level constraints as compact JSON to the tool description. The MCP server
+remains the authoritative validator when the worker executes the call. Agent
+tool descriptions, including appended constraints, must fit within 10,000
+characters.
+
+Fetch every `tools/list` page, then use the exact same selected definitions for
+the Agent and worker. Managed Agents currently accepts at most eight custom
+tools per Agent. Tool discovery happens at worker startup, so update the Agent
+while it is idle and restart the worker whenever the MCP server changes its
+tool list.
+
+Custom tools do not use Managed Agents permission policies. The worker executes
+each matching call, so implement approval, authorization, and operation
+allowlists in the MCP server or a wrapper tool. Only wrap trusted servers,
+avoid names that collide with built-in Agent tools, add prefixes when multiple
+servers expose the same name, and configure an MCP client timeout. Client-side
+MCP servers run with the worker's OS, filesystem, and network permissions, not
+in a Managed Agents sandbox. Run them with least privilege and a minimal
+environment, and do not pass `ARK_API_KEY` to an MCP subprocess. Tool names,
+descriptions, inputs, and results enter the model context and must be treated
+as untrusted content.
+
+### Tool result support
+
+The worker preserves MCP `isError` and supports text, `image/jpeg`,
+`image/png`, `image/gif`, and `image/webp` image blocks. Embedded resources may
+contain the same image MIME types, `application/pdf`, or text whose MIME type is
+absent, empty, or starts with `text/`. When a result has no content blocks but
+has `structuredContent`, the helper serializes it as compact JSON text.
+
+Audio, resource links, unknown content types, and other resource MIME types
+become an error result. If a result mixes supported and unsupported blocks, the
+whole converted result is an error; the supported blocks are not returned
+separately.
+
 ## Requirements
 
 - Python >= 3.8

{arkruntime-0.5.0 → arkruntime-0.7.0}/THIRD_PARTY_NOTICES.md

@@ -5,9 +5,10 @@ from third-party open-source projects.
 
 ## Anthropic self-hosted worker SDK
 
-Portions of the self-hosted worker lifecycle and local agent tool
-implementations under `src/arkruntime/selfhosted` are structurally adapted
-from Anthropic's self-hosted worker SDK implementations:
+Portions of the self-hosted worker lifecycle, local agent tool, and client-side
+MCP helper implementations under `src/arkruntime/selfhosted` and
+`src/arkruntime/mcp.py` are structurally adapted from Anthropic's SDK
+implementations:
 
 - https://github.com/anthropics/anthropic-sdk-python
 - https://github.com/anthropics/anthropic-sdk-go

{arkruntime-0.5.0 → arkruntime-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arkruntime"
-version = "0.5.0"
+version = "0.7.0"
 description = "Ark runtime SDK for Python"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -23,6 +23,9 @@ dependencies = [
   "volcengine-python-sdk>=5.0.20",
 ]
 
+[project.optional-dependencies]
+mcp = ["mcp>=1.0,<3; python_version >= '3.10'"]
+
 [project.urls]
 Homepage = "https://github.com/volcengine/ark-runtime-python"
 
@@ -42,6 +45,7 @@ dev = [
     "pytest-cov>=5",
     "pytest-xdist>=3",
     "respx>=0.21",
+    "trio>=0.22",
 ]
 
 [tool.setuptools]

{arkruntime-0.5.0 → arkruntime-0.7.0}/src/arkruntime/_base_client.py

@@ -5,6 +5,7 @@
 from __future__ import annotations
 
 import asyncio
+import email.utils
 import json
 import logging
 import time
@@ -184,7 +185,7 @@ class BaseClient(Generic[_HttpxClientT]):
 
     @property
     def user_agent(self) -> str:
-        return "volc-sdk-python/" + VERSION
+        return "ark-runtime-python/" + VERSION
 
     def default_headers(self) -> Dict[str, str]:
         return {
@@ -199,10 +200,14 @@ class BaseClient(Generic[_HttpxClientT]):
     def _make_sse_decoder(self) -> SSEDecoder | SSEBytesDecoder:
         return SSEDecoder()
 
-    def _build_headers(self, options: RequestOptions) -> httpx.Headers:
+    def _build_headers(self, options: RequestOptions, *, retries_taken: int = 0) -> httpx.Headers:
         custom_headers = options.headers or {}
-        headers_dict = {**self.default_headers(), **custom_headers}
+        headers_dict = {
+            **self.default_headers(),
+            "x-stainless-retry-count": str(retries_taken),
+        }
         headers = httpx.Headers(headers_dict)
+        headers.update(custom_headers)
 
         return headers
 
@@ -237,7 +242,7 @@ class BaseClient(Generic[_HttpxClientT]):
             else:
                 raise RuntimeError(f"Unexpected JSON data type, {type(body)}, cannot merge with `extra_body`")
 
-        headers = self._build_headers(options)
+        headers = self._build_headers(options, retries_taken=retries_taken)
         params = options.params
         content_type = headers.get("Content-Type")
         files = options.files
@@ -338,9 +343,13 @@ class BaseClient(Generic[_HttpxClientT]):
         options: RequestOptions,
         response_headers: Optional[httpx.Headers] = None,
     ) -> float:
-        max_retries = options.max_retries if options.max_retries else self.max_retries
+        max_retries = options.get_max_retries(self.max_retries)
+
+        retry_after = self._parse_retry_after_header(response_headers)
+        if retry_after is not None and 0 < retry_after <= 60:
+            return retry_after
 
-        nb_retries = max_retries - remaining_retries
+        nb_retries = min(max(max_retries - remaining_retries - 1, 0), 1000)
 
         # Apply exponential backoff, but not more than the max.
         sleep_seconds = min(INITIAL_RETRY_DELAY * pow(2.0, nb_retries), MAX_RETRY_DELAY)
@@ -350,9 +359,31 @@ class BaseClient(Generic[_HttpxClientT]):
         timeout = sleep_seconds * jitter
         return timeout if timeout >= 0 else 0
 
+    def _parse_retry_after_header(self, response_headers: Optional[httpx.Headers] = None) -> Optional[float]:
+        if response_headers is None:
+            return None
+
+        try:
+            retry_after_ms = response_headers.get("retry-after-ms")
+            return float(retry_after_ms) / 1000
+        except (TypeError, ValueError):
+            pass
+
+        retry_after = response_headers.get("retry-after")
+        try:
+            return float(retry_after)
+        except (TypeError, ValueError):
+            pass
+
+        retry_date = email.utils.parsedate_tz(retry_after)
+        if retry_date is None:
+            return None
+        return float(email.utils.mktime_tz(retry_date) - time.time())
+
     def _should_retry(self, response: httpx.Response) -> bool:
         # Note: this is not a standard header
         should_retry_header = response.headers.get("x-should-retry")
+        should_retry_header = should_retry_header.lower() if should_retry_header else None
 
         # If the server explicitly says whether or not to retry, obey.
         if should_retry_header == "true":
@@ -503,7 +534,8 @@ class SyncAPIClient(BaseClient):
         stream_cls: type[_StreamT] | None,
     ) -> ResponseT | _StreamT:
         retries = self._remaining_retries(remaining_retries, options)
-        request = self._build_request(options)
+        max_retries = options.get_max_retries(self.max_retries)
+        request = self._build_request(options, retries_taken=max_retries - retries)
         req_id = request.headers.get(CLIENT_REQUEST_HEADER, "")
         try:
             response = self._client.send(
@@ -703,6 +735,7 @@ class SyncAPIClient(BaseClient):
         stream: bool = False,
         stream_cls: type[_StreamT] | None = None,
     ) -> ResponseT | _StreamT:
+        options = {**options, "max_retries": 0}
         opts = RequestOptions.construct(  # type: ignore
             method="post",
             url=path,
@@ -916,6 +949,7 @@ class AsyncAPIClient(BaseClient):
         stream: bool = False,
         stream_cls: type[_AsyncStreamT] | None = None,
     ) -> ResponseT | _AsyncStreamT:
+        options = {**options, "max_retries": 0}
         opts = RequestOptions.construct(
             method="post",
             url=path,
@@ -984,7 +1018,8 @@ class AsyncAPIClient(BaseClient):
         stream_cls: type[_AsyncStreamT] | None,
     ) -> ResponseT | _AsyncStreamT:
         retries = self._remaining_retries(remaining_retries, options)
-        request = self._build_request(options)
+        max_retries = options.get_max_retries(self.max_retries)
+        request = self._build_request(options, retries_taken=max_retries - retries)
         req_id = request.headers.get(CLIENT_REQUEST_HEADER, "")
         try:
             response = await self._client.send(

{arkruntime-0.5.0 → arkruntime-0.7.0}/src/arkruntime/_client.py

@@ -76,7 +76,7 @@ class Ark(SyncAPIClient):
                 sk: secret access key
                 api_key: api key，this api key will not be refreshed
                 timeout: timeout of client. default httpx.Timeout(timeout=60.0, connect=60.0)
-                max_retries: times of retry when request failed. default 1
+                max_retries: times of retry when request failed. default 2
                 http_client: specify customized http_client
             Returns:
                 ark client
@@ -229,7 +229,7 @@ class AsyncArk(AsyncAPIClient):
             sk: secret access key
             api_key: api key，this api key will not be refreshed
             timeout: timeout of client. default httpx.Timeout(timeout=60.0, connect=60.0)
-            max_retries: times of retry when request failed. default 1
+            max_retries: times of retry when request failed. default 2
             http_client: specify customized http_client
         Returns:
             async ark client

{arkruntime-0.5.0 → arkruntime-0.7.0}/src/arkruntime/_constants.py

@@ -4,7 +4,8 @@
 
 import httpx
 
-VERSION = "1.0.0"
+from ._version import VERSION as VERSION
+
 BASE_URL = "https://ark.cn-beijing.volces.com/api/v3"
 
 

arkruntime-0.7.0/src/arkruntime/_version.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+import re
+from importlib.metadata import version
+from pathlib import Path
+
+
+def _get_version() -> str:
+    # Source and editable imports must use this checkout, even if another
+    # arkruntime distribution is installed. Releases use wheel metadata,
+    # which setuptools derives from the same pyproject.toml project.version.
+    source_root = Path(__file__).resolve().parent.parent
+    pyproject = source_root.parent / "pyproject.toml"
+    if source_root.name == "src" and pyproject.is_file():
+        # The project declares a static, single-line version. Read only the
+        # [project] table without requiring a TOML dependency on Python 3.8.
+        project = re.search(r"(?ms)^\[project\][ \t]*\n(.*?)(?=^\[|\Z)", pyproject.read_text(encoding="utf-8"))
+        if project is not None:
+            declared = re.search(r"""(?m)^version\s*=\s*["']([^"'\r\n]+)["'][ \t]*(?:#.*)?$""", project[1])
+            if declared is not None:
+                return declared[1]
+        raise RuntimeError("Expected a static project.version in " + str(pyproject))
+    return version("arkruntime")
+
+
+VERSION = _get_version()

arkruntime-0.7.0/src/arkruntime/mcp.py

@@ -0,0 +1,197 @@
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+"""把官方 MCP Python SDK 适配到方舟 self-hosted MCP 接口。
+
+安装可选依赖：``pip install 'arkruntime[mcp]'``。官方 MCP 包需要
+Python 3.10 或更高版本。调用方应在 AnyIO 事件循环中创建
+``BlockingPortal``，并保证 portal 与 MCP ``ClientSession`` 的生命周期覆盖 worker。
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+import contextlib
+import time
+from typing import Any, Dict, Iterable, List, Optional
+
+try:
+    from anyio.from_thread import BlockingPortal
+    from mcp import ClientSession, types
+except ImportError as exc:  # pragma: no cover - depends on the optional extra.
+    raise ImportError(
+        "The 'mcp' package is required for MCP helpers. Install it with: "
+        "pip install 'arkruntime[mcp]'. Python 3.10 or newer is required."
+    ) from exc
+
+from arkruntime.selfhosted.mcp import (
+    MCPCallToolResult,
+    MCPClient,
+    MCPContent,
+    MCPResource,
+    MCPToolDefinition,
+)
+from arkruntime.selfhosted.mcp import (
+    custom_tool_item as core_custom_tool_item,
+)
+from arkruntime.selfhosted.mcp import (
+    custom_tool_items as core_custom_tool_items,
+)
+from arkruntime.selfhosted.mcp import (
+    mcp_tool as core_mcp_tool,
+)
+from arkruntime.selfhosted.mcp import (
+    mcp_tools as core_mcp_tools,
+)
+from arkruntime.selfhosted.tools import Tool, ToolContext
+from arkruntime.types.agent import ToolItem
+
+__all__ = ["AnyIOMCPClient", "custom_tool_item", "custom_tool_items", "mcp_tool", "mcp_tools"]
+
+_MISSING = object()
+
+
+def _field(value: Any, snake_name: str, camel_name: str, default: Any = _MISSING) -> Any:
+    if hasattr(value, snake_name):
+        return getattr(value, snake_name)
+    if hasattr(value, camel_name):
+        return getattr(value, camel_name)
+    if default is not _MISSING:
+        return default
+    raise AttributeError(snake_name)
+
+
+class AnyIOMCPClient(MCPClient):
+    """通过 AnyIO portal 从 worker 线程调用异步 MCP ClientSession。"""
+
+    def __init__(
+        self,
+        client: ClientSession,
+        portal: BlockingPortal,
+        *,
+        timeout: Optional[float] = None,
+        poll_interval: float = 0.25,
+    ) -> None:
+        if client is None:
+            raise ValueError("mcp client is required")
+        if portal is None:
+            raise ValueError("anyio blocking portal is required")
+        if timeout is not None and timeout <= 0:
+            raise ValueError("timeout must be positive")
+        if poll_interval <= 0:
+            raise ValueError("poll_interval must be positive")
+        self._client = client
+        self._portal = portal
+        self._timeout = timeout
+        self._poll_interval = poll_interval
+
+    def call_tool(
+        self,
+        name: str,
+        arguments: Dict[str, Any],
+        context: ToolContext,
+    ) -> Optional[MCPCallToolResult]:
+        future = self._portal.start_task_soon(self._client.call_tool, name, arguments)
+        started = time.monotonic()
+        while True:
+            try:
+                return _call_tool_result(future.result(timeout=self._poll_interval))
+            except concurrent.futures.TimeoutError:
+                if _is_cancelled(context):
+                    _cancel_and_wait(future)
+                    raise RuntimeError("execution canceled")
+                if self._timeout is not None and time.monotonic() - started >= self._timeout:
+                    _cancel_and_wait(future)
+                    raise RuntimeError(f"execution timed out after {self._timeout:g} seconds")
+
+
+def custom_tool_item(tool: "types.Tool") -> ToolItem:
+    """把官方 MCP Tool 转换成 Agent custom tool 声明。"""
+
+    return core_custom_tool_item(_tool_definition(tool))
+
+
+def custom_tool_items(tools: Iterable["types.Tool"]) -> List[ToolItem]:
+    """批量转换官方 MCP Tools。"""
+
+    return core_custom_tool_items([_tool_definition(tool) for tool in tools])
+
+
+def mcp_tool(
+    tool: "types.Tool",
+    client: ClientSession,
+    *,
+    portal: BlockingPortal,
+    timeout: Optional[float] = None,
+) -> Tool:
+    """把官方 MCP Tool 包装成 worker Custom Tool。"""
+
+    return core_mcp_tool(_tool_definition(tool), AnyIOMCPClient(client, portal, timeout=timeout))
+
+
+def mcp_tools(
+    tools: Iterable["types.Tool"],
+    client: ClientSession,
+    *,
+    portal: BlockingPortal,
+    timeout: Optional[float] = None,
+) -> Dict[str, Tool]:
+    """批量包装官方 MCP Tools。"""
+
+    return core_mcp_tools(
+        [_tool_definition(tool) for tool in tools],
+        AnyIOMCPClient(client, portal, timeout=timeout),
+    )
+
+
+def _tool_definition(tool: "types.Tool") -> MCPToolDefinition:
+    if tool is None:
+        raise ValueError("mcp tool is required")
+    return MCPToolDefinition(
+        name=tool.name,
+        description=tool.description or "",
+        input_schema=_field(tool, "input_schema", "inputSchema", {"type": "object"}),
+    )
+
+
+def _call_tool_result(result: "types.CallToolResult") -> Optional[MCPCallToolResult]:
+    if result is None:
+        return None
+    return MCPCallToolResult(
+        content=[_content(item) for item in result.content],
+        structured_content=_field(result, "structured_content", "structuredContent", None),
+        is_error=bool(_field(result, "is_error", "isError", False)),
+    )
+
+
+def _content(content: "types.ContentBlock") -> MCPContent:
+    if isinstance(content, types.TextContent):
+        return MCPContent(type="text", text=content.text)
+    if isinstance(content, types.ImageContent):
+        return MCPContent(
+            type="image",
+            mime_type=_field(content, "mime_type", "mimeType"),
+            data=content.data,
+        )
+    if isinstance(content, types.EmbeddedResource):
+        return MCPContent(type="resource", resource=_resource(content.resource))
+    return MCPContent(type=str(getattr(content, "type", type(content).__name__)))
+
+
+def _resource(resource: Any) -> MCPResource:
+    return MCPResource(
+        uri=str(resource.uri),
+        mime_type=_field(resource, "mime_type", "mimeType", None),
+        text=getattr(resource, "text", None),
+        blob=getattr(resource, "blob", None),
+    )
+
+
+def _is_cancelled(context: ToolContext) -> bool:
+    cancel_event = context.cancel_event
+    return cancel_event is not None and bool(getattr(cancel_event, "is_set", lambda: False)())
+
+
+def _cancel_and_wait(future: "concurrent.futures.Future[Any]") -> None:
+    future.cancel()
+    with contextlib.suppress(concurrent.futures.CancelledError, concurrent.futures.TimeoutError):
+        future.result(timeout=1)

{arkruntime-0.5.0 → arkruntime-0.7.0}/src/arkruntime/resources/environments/work.py

@@ -26,9 +26,9 @@ def _path(environment_id: str, suffix: str) -> str:
     return f"/environments/{quote(environment_id, safe='')}/work/{suffix.lstrip('/')}"
 
 
-def _query(*, block_ms: int = 0, reclaim_older_than_ms: int = 0) -> dict:
+def _query(*, block_ms: Optional[int] = 0, reclaim_older_than_ms: int = 0) -> dict:
     query = {}
-    if block_ms > 0:
+    if block_ms is not None and block_ms > 0:
         query["block_ms"] = block_ms
     if reclaim_older_than_ms > 0:
         query["reclaim_older_than_ms"] = reclaim_older_than_ms
@@ -48,7 +48,7 @@ class EnvironmentWork(SyncAPIResource):
         environment_id: str,
         *,
         worker_id: str = "",
-        block_ms: int = 999,
+        block_ms: Optional[int] = 999,
         reclaim_older_than_ms: int = 0,
         extra_headers=None,
         extra_query=None,
@@ -144,7 +144,7 @@ class AsyncEnvironmentWork(AsyncAPIResource):
         environment_id: str,
         *,
         worker_id: str = "",
-        block_ms: int = 999,
+        block_ms: Optional[int] = 999,
         reclaim_older_than_ms: int = 0,
         extra_headers=None,
         extra_query=None,