Skip to content

client

Class info

Classes

Name Children Inherits
McpHttpSession
pyt3client.mcp
One MCP session against a T3 Code environment's `/mcp`.
    T3Client
    pyt3client.client
    Typed client for one T3 Code environment, over its `/mcp` endpoint.
      T3ProtocolError
      pyt3client.errors
      The server answered in a shape this client does not understand.
        T3ToolError
        pyt3client.errors
        A tool call was refused.
          ThreadWaitInput
          pyt3client.models.tools

            🛈 DocStrings

            High-level async client for a T3 Code environment.

            MAX_WAIT_CHUNK_SECONDS module-attribute

            MAX_WAIT_CHUNK_SECONDS = 50.0
            

            Longest single t3_thread_wait call wait_for_thread makes.

            /mcp sends nothing while a wait is open, and T3 Connect's edge drops idle requests after about 100 s, so upstream splits forwarded waits into calls of at most 50 s (see "Peer links" in docs/internals/remote.md upstream).

            T3Client

            Typed client for one T3 Code environment, over its /mcp endpoint.

            Every tool the environment offers is reachable through call, typed by the ToolSpec constants in pyt3client.models.tools:

            from pyt3client import T3Client, pair
            from pyt3client.models.tools import THREAD_LAUNCH, ThreadLaunchInput
            
            credentials = await pair("http://127.0.0.1:3773", "PAIRING-CODE")
            async with T3Client.from_credentials(credentials) as t3:
                launched = await t3.call(
                    THREAD_LAUNCH,
                    ThreadLaunchInput(project_id="...", title="Fix tests", message="Fix the tests"),
                )
                done = await t3.wait_for_thread(launched.thread_id, run_id=launched.run_id)
            

            Get credentials with pyt3client.pair(); T3 Code's server reference for the tools is docs/orchestration-v2/orchestrator-mcp-server.md upstream.

            Source code in src/pyt3client/client.py
             43
             44
             45
             46
             47
             48
             49
             50
             51
             52
             53
             54
             55
             56
             57
             58
             59
             60
             61
             62
             63
             64
             65
             66
             67
             68
             69
             70
             71
             72
             73
             74
             75
             76
             77
             78
             79
             80
             81
             82
             83
             84
             85
             86
             87
             88
             89
             90
             91
             92
             93
             94
             95
             96
             97
             98
             99
            100
            101
            102
            103
            104
            105
            106
            107
            108
            109
            110
            111
            112
            113
            114
            115
            116
            117
            118
            119
            120
            121
            122
            123
            124
            125
            126
            127
            128
            129
            130
            131
            132
            133
            134
            135
            136
            137
            138
            139
            140
            141
            142
            143
            144
            145
            146
            147
            148
            149
            150
            151
            152
            153
            154
            155
            156
            157
            158
            159
            160
            161
            162
            163
            164
            165
            166
            167
            168
            169
            170
            171
            172
            173
            174
            175
            176
            177
            178
            179
            180
            181
            182
            183
            184
            185
            186
            187
            188
            189
            190
            191
            192
            193
            194
            195
            196
            197
            198
            199
            200
            201
            202
            203
            204
            205
            206
            207
            208
            209
            210
            211
            212
            213
            214
            215
            216
            217
            218
            219
            220
            221
            222
            223
            224
            225
            226
            227
            228
            229
            230
            231
            232
            233
            234
            235
            236
            237
            238
            239
            240
            241
            242
            243
            244
            245
            246
            247
            248
            249
            250
            251
            252
            253
            254
            255
            256
            257
            258
            class T3Client:
                """Typed client for one T3 Code environment, over its `/mcp` endpoint.
            
                Every tool the environment offers is reachable through `call`, typed by the
                `ToolSpec` constants in `pyt3client.models.tools`:
            
                ```python
                from pyt3client import T3Client, pair
                from pyt3client.models.tools import THREAD_LAUNCH, ThreadLaunchInput
            
                credentials = await pair("http://127.0.0.1:3773", "PAIRING-CODE")
                async with T3Client.from_credentials(credentials) as t3:
                    launched = await t3.call(
                        THREAD_LAUNCH,
                        ThreadLaunchInput(project_id="...", title="Fix tests", message="Fix the tests"),
                    )
                    done = await t3.wait_for_thread(launched.thread_id, run_id=launched.run_id)
                ```
            
                Get credentials with `pyt3client.pair()`; T3 Code's server reference for the
                tools is docs/orchestration-v2/orchestrator-mcp-server.md upstream.
                """
            
                def __init__(
                    self,
                    base_url: str,
                    token: str | SecretStr,
                    *,
                    mode_limit: tuple[RuntimeMode, InteractionMode] | None = None,
                    client_name: str = "pyt3client",
                    timeout: float = 60.0,
                    http_client: httpx.AsyncClient | None = None,
                ) -> None:
                    """Create a client; the MCP session opens on first use.
            
                    Args:
                        base_url: Environment origin, such as `http://127.0.0.1:3773`.
                        token: MCP bearer token, as returned by `pair()`.
                        mode_limit: Narrow this client below its approved level for every call:
                            threads it starts or steers run with at most this runtime and
                            interaction mode. Sent as the `t3-mode-limit` header, which the
                            server only ever uses to narrow (upstream `MODE_LIMIT_HEADER` in
                            apps/server/src/mcp/McpInvocationContext.ts).
                        client_name: Name reported in the MCP `initialize` handshake.
                        timeout: Default HTTP timeout in seconds.
                        http_client: Client to use; created and owned by this instance otherwise.
                    """
                    self.base_url = base_url.rstrip("/").removesuffix("/mcp")
                    self._owns_http = http_client is None
                    self._http = http_client or httpx.AsyncClient(timeout=timeout)
                    headers = (
                        {} if mode_limit is None else {"t3-mode-limit": f"{mode_limit[0]}/{mode_limit[1]}"}
                    )
                    self._session = McpHttpSession(
                        f"{self.base_url}/mcp",
                        token if isinstance(token, SecretStr) else SecretStr(token),
                        http_client=self._http,
                        headers=headers,
                        client_name=client_name,
                    )
            
                @classmethod
                def from_credentials(
                    cls,
                    credentials: T3Credentials,
                    *,
                    mode_limit: tuple[RuntimeMode, InteractionMode] | None = None,
                    client_name: str = "pyt3client",
                    timeout: float = 60.0,
                    http_client: httpx.AsyncClient | None = None,
                ) -> Self:
                    """Create a client from the result of `pair()`.
            
                    Args:
                        credentials: Credentials from `pair()`.
                        mode_limit: See `T3Client`.
                        client_name: See `T3Client`.
                        timeout: See `T3Client`.
                        http_client: See `T3Client`.
                    """
                    return cls(
                        credentials.base_url,
                        credentials.access_token,
                        mode_limit=mode_limit,
                        client_name=client_name,
                        timeout=timeout,
                        http_client=http_client,
                    )
            
                async def __aenter__(self) -> Self:
                    return self
            
                async def __aexit__(
                    self,
                    exc_type: type[BaseException] | None,
                    exc_value: BaseException | None,
                    traceback: TracebackType | None,
                ) -> None:
                    await self.aclose()
            
                async def aclose(self) -> None:
                    """End the MCP session and close the HTTP client if this instance owns it."""
                    await self._session.close()
                    if self._owns_http:
                        await self._http.aclose()
            
                @property
                def server_info(self) -> dict[str, JsonValue] | None:
                    """`serverInfo` from the MCP handshake, once a request has been made."""
                    return self._session.server_info
            
                async def descriptor(self) -> EnvironmentDescriptor:
                    """The environment's public descriptor (id, version, capability flags)."""
                    return await fetch_descriptor(self.base_url, http_client=self._http)
            
                async def list_tools(self) -> list[ToolInfo]:
                    """Tools the server offers this credential, with their JSON Schemas.
            
                    Useful to detect drift against the generated models: a newer server
                    may offer tools `pyt3client.models.tools` does not know yet.
                    """
                    return await self._session.list_tools()
            
                async def call[InputT: BaseModel, OutputT: BaseModel](
                    self,
                    tool: ToolSpec[InputT, OutputT],
                    params: InputT | None = None,
                    *,
                    timeout: float | None = None,
                ) -> OutputT:
                    """Call a tool with typed arguments and return its typed result.
            
                    Args:
                        tool: The tool, such as `pyt3client.models.tools.THREAD_LIST`.
                        params: Its arguments; `tool.input_type()` (all defaults) when omitted.
                        timeout: HTTP read timeout in seconds for this call.
            
                    Raises:
                        T3ToolError: The tool refused, such as `thread_not_found` or
                            `capability_denied` (a read-only sign-in calling a write tool).
                        T3McpError: The request was rejected, such as invalid arguments.
                        T3ProtocolError: The result does not match the generated model.
                    """
                    arguments = (params if params is not None else tool.input_type()).model_dump(
                        mode="json", by_alias=True, exclude_unset=True
                    )
                    result = await self._session.call_tool(tool.name, arguments, timeout=timeout)
                    payload = _payload(tool.name, result)
                    try:
                        return tool.output_type.model_validate(payload)
                    except ValidationError as error:
                        msg = (
                            f"{tool.name}: result does not match the generated model; the server may be"
                            f" newer than the snapshot (regenerate with scripts/generate_models.py): {error}"
                        )
                        raise T3ProtocolError(msg) from error
            
                async def call_raw(
                    self,
                    name: str,
                    arguments: Mapping[str, JsonValue] | None = None,
                    *,
                    timeout: float | None = None,
                ) -> JsonValue:
                    """Call any tool by name with untyped arguments; for tools newer than the models.
            
                    Raises:
                        T3ToolError: The tool refused.
                        T3McpError: The request was rejected.
                    """
                    result = await self._session.call_tool(name, arguments or {}, timeout=timeout)
                    return _payload(name, result)
            
                async def wait_for_thread(
                    self,
                    thread_id: str,
                    *,
                    run_id: str | None = None,
                    timeout: float | None = None,
                    until_delegated_work_settled: bool = False,
                    environment_id: str | None = None,
                ) -> ThreadWaitOutput:
                    """Wait until a thread's run ends, for longer than one HTTP request may stay idle.
            
                    Repeats `t3_thread_wait` in chunks of at most `MAX_WAIT_CHUNK_SECONDS`.
                    A run ends as `completed`, `failed`, `cancelled`, `interrupted` or
                    `rolled_back`; an idle thread returns at once. Timing out does not stop
                    the run: the result then has `timed_out=True` and the latest status.
            
                    Args:
                        thread_id: Thread to wait on.
                        run_id: Run to wait for. Without it the server pins the thread's latest
                            run on the first call, and later chunks keep waiting on that run.
                        timeout: Overall limit in seconds; waits until the run ends otherwise.
                        until_delegated_work_settled: Also wait for the run's subagents and
                            background tasks; `result_run` then names the run with the answer.
                        environment_id: Linked environment the thread lives in, if not this one.
                    """
                    deadline = None if timeout is None else time.monotonic() + timeout
                    while True:
                        chunk = MAX_WAIT_CHUNK_SECONDS
                        if deadline is not None:
                            chunk = min(chunk, max(deadline - time.monotonic(), 0.0))
                        params = ThreadWaitInput(thread_id=thread_id, timeout_ms=chunk * 1000)
                        if run_id is not None:
                            params.run_id = run_id
                        if until_delegated_work_settled:
                            params.until_delegated_work_settled = True
                        if environment_id is not None:
                            params.environment_id = environment_id
                        result = await self.call(THREAD_WAIT, params, timeout=chunk + _WAIT_SLACK_SECONDS)
                        if not result.timed_out:
                            return result
                        if deadline is not None and time.monotonic() >= deadline:
                            return result
                        run_id = result.run_id or run_id
            

            server_info property

            server_info: dict[str, JsonValue] | None
            

            serverInfo from the MCP handshake, once a request has been made.

            __init__

            __init__(
                base_url: str,
                token: str | SecretStr,
                *,
                mode_limit: tuple[RuntimeMode, InteractionMode] | None = None,
                client_name: str = "pyt3client",
                timeout: float = 60.0,
                http_client: AsyncClient | None = None
            ) -> None
            

            Create a client; the MCP session opens on first use.

            Parameters:

            Name Type Description Default
            base_url str

            Environment origin, such as http://127.0.0.1:3773.

            required
            token str | SecretStr

            MCP bearer token, as returned by pair().

            required
            mode_limit tuple[RuntimeMode, InteractionMode] | None

            Narrow this client below its approved level for every call: threads it starts or steers run with at most this runtime and interaction mode. Sent as the t3-mode-limit header, which the server only ever uses to narrow (upstream MODE_LIMIT_HEADER in apps/server/src/mcp/McpInvocationContext.ts).

            None
            client_name str

            Name reported in the MCP initialize handshake.

            'pyt3client'
            timeout float

            Default HTTP timeout in seconds.

            60.0
            http_client AsyncClient | None

            Client to use; created and owned by this instance otherwise.

            None
            Source code in src/pyt3client/client.py
             66
             67
             68
             69
             70
             71
             72
             73
             74
             75
             76
             77
             78
             79
             80
             81
             82
             83
             84
             85
             86
             87
             88
             89
             90
             91
             92
             93
             94
             95
             96
             97
             98
             99
            100
            101
            102
            def __init__(
                self,
                base_url: str,
                token: str | SecretStr,
                *,
                mode_limit: tuple[RuntimeMode, InteractionMode] | None = None,
                client_name: str = "pyt3client",
                timeout: float = 60.0,
                http_client: httpx.AsyncClient | None = None,
            ) -> None:
                """Create a client; the MCP session opens on first use.
            
                Args:
                    base_url: Environment origin, such as `http://127.0.0.1:3773`.
                    token: MCP bearer token, as returned by `pair()`.
                    mode_limit: Narrow this client below its approved level for every call:
                        threads it starts or steers run with at most this runtime and
                        interaction mode. Sent as the `t3-mode-limit` header, which the
                        server only ever uses to narrow (upstream `MODE_LIMIT_HEADER` in
                        apps/server/src/mcp/McpInvocationContext.ts).
                    client_name: Name reported in the MCP `initialize` handshake.
                    timeout: Default HTTP timeout in seconds.
                    http_client: Client to use; created and owned by this instance otherwise.
                """
                self.base_url = base_url.rstrip("/").removesuffix("/mcp")
                self._owns_http = http_client is None
                self._http = http_client or httpx.AsyncClient(timeout=timeout)
                headers = (
                    {} if mode_limit is None else {"t3-mode-limit": f"{mode_limit[0]}/{mode_limit[1]}"}
                )
                self._session = McpHttpSession(
                    f"{self.base_url}/mcp",
                    token if isinstance(token, SecretStr) else SecretStr(token),
                    http_client=self._http,
                    headers=headers,
                    client_name=client_name,
                )
            

            aclose async

            aclose() -> None
            

            End the MCP session and close the HTTP client if this instance owns it.

            Source code in src/pyt3client/client.py
            143
            144
            145
            146
            147
            async def aclose(self) -> None:
                """End the MCP session and close the HTTP client if this instance owns it."""
                await self._session.close()
                if self._owns_http:
                    await self._http.aclose()
            

            call async

            call(
                tool: ToolSpec[InputT, OutputT], params: InputT | None = None, *, timeout: float | None = None
            ) -> OutputT
            

            Call a tool with typed arguments and return its typed result.

            Parameters:

            Name Type Description Default
            tool ToolSpec[InputT, OutputT]

            The tool, such as pyt3client.models.tools.THREAD_LIST.

            required
            params InputT | None

            Its arguments; tool.input_type() (all defaults) when omitted.

            None
            timeout float | None

            HTTP read timeout in seconds for this call.

            None

            Raises:

            Type Description
            T3ToolError

            The tool refused, such as thread_not_found or capability_denied (a read-only sign-in calling a write tool).

            T3McpError

            The request was rejected, such as invalid arguments.

            T3ProtocolError

            The result does not match the generated model.

            Source code in src/pyt3client/client.py
            166
            167
            168
            169
            170
            171
            172
            173
            174
            175
            176
            177
            178
            179
            180
            181
            182
            183
            184
            185
            186
            187
            188
            189
            190
            191
            192
            193
            194
            195
            196
            197
            198
            async def call[InputT: BaseModel, OutputT: BaseModel](
                self,
                tool: ToolSpec[InputT, OutputT],
                params: InputT | None = None,
                *,
                timeout: float | None = None,
            ) -> OutputT:
                """Call a tool with typed arguments and return its typed result.
            
                Args:
                    tool: The tool, such as `pyt3client.models.tools.THREAD_LIST`.
                    params: Its arguments; `tool.input_type()` (all defaults) when omitted.
                    timeout: HTTP read timeout in seconds for this call.
            
                Raises:
                    T3ToolError: The tool refused, such as `thread_not_found` or
                        `capability_denied` (a read-only sign-in calling a write tool).
                    T3McpError: The request was rejected, such as invalid arguments.
                    T3ProtocolError: The result does not match the generated model.
                """
                arguments = (params if params is not None else tool.input_type()).model_dump(
                    mode="json", by_alias=True, exclude_unset=True
                )
                result = await self._session.call_tool(tool.name, arguments, timeout=timeout)
                payload = _payload(tool.name, result)
                try:
                    return tool.output_type.model_validate(payload)
                except ValidationError as error:
                    msg = (
                        f"{tool.name}: result does not match the generated model; the server may be"
                        f" newer than the snapshot (regenerate with scripts/generate_models.py): {error}"
                    )
                    raise T3ProtocolError(msg) from error
            

            call_raw async

            call_raw(
                name: str, arguments: Mapping[str, JsonValue] | None = None, *, timeout: float | None = None
            ) -> JsonValue
            

            Call any tool by name with untyped arguments; for tools newer than the models.

            Raises:

            Type Description
            T3ToolError

            The tool refused.

            T3McpError

            The request was rejected.

            Source code in src/pyt3client/client.py
            200
            201
            202
            203
            204
            205
            206
            207
            208
            209
            210
            211
            212
            213
            214
            async def call_raw(
                self,
                name: str,
                arguments: Mapping[str, JsonValue] | None = None,
                *,
                timeout: float | None = None,
            ) -> JsonValue:
                """Call any tool by name with untyped arguments; for tools newer than the models.
            
                Raises:
                    T3ToolError: The tool refused.
                    T3McpError: The request was rejected.
                """
                result = await self._session.call_tool(name, arguments or {}, timeout=timeout)
                return _payload(name, result)
            

            descriptor async

            descriptor() -> EnvironmentDescriptor
            

            The environment's public descriptor (id, version, capability flags).

            Source code in src/pyt3client/client.py
            154
            155
            156
            async def descriptor(self) -> EnvironmentDescriptor:
                """The environment's public descriptor (id, version, capability flags)."""
                return await fetch_descriptor(self.base_url, http_client=self._http)
            

            from_credentials classmethod

            from_credentials(
                credentials: T3Credentials,
                *,
                mode_limit: tuple[RuntimeMode, InteractionMode] | None = None,
                client_name: str = "pyt3client",
                timeout: float = 60.0,
                http_client: AsyncClient | None = None
            ) -> Self
            

            Create a client from the result of pair().

            Parameters:

            Name Type Description Default
            credentials T3Credentials

            Credentials from pair().

            required
            mode_limit tuple[RuntimeMode, InteractionMode] | None

            See T3Client.

            None
            client_name str

            See T3Client.

            'pyt3client'
            timeout float

            See T3Client.

            60.0
            http_client AsyncClient | None

            See T3Client.

            None
            Source code in src/pyt3client/client.py
            104
            105
            106
            107
            108
            109
            110
            111
            112
            113
            114
            115
            116
            117
            118
            119
            120
            121
            122
            123
            124
            125
            126
            127
            128
            129
            130
            @classmethod
            def from_credentials(
                cls,
                credentials: T3Credentials,
                *,
                mode_limit: tuple[RuntimeMode, InteractionMode] | None = None,
                client_name: str = "pyt3client",
                timeout: float = 60.0,
                http_client: httpx.AsyncClient | None = None,
            ) -> Self:
                """Create a client from the result of `pair()`.
            
                Args:
                    credentials: Credentials from `pair()`.
                    mode_limit: See `T3Client`.
                    client_name: See `T3Client`.
                    timeout: See `T3Client`.
                    http_client: See `T3Client`.
                """
                return cls(
                    credentials.base_url,
                    credentials.access_token,
                    mode_limit=mode_limit,
                    client_name=client_name,
                    timeout=timeout,
                    http_client=http_client,
                )
            

            list_tools async

            list_tools() -> list[ToolInfo]
            

            Tools the server offers this credential, with their JSON Schemas.

            Useful to detect drift against the generated models: a newer server may offer tools pyt3client.models.tools does not know yet.

            Source code in src/pyt3client/client.py
            158
            159
            160
            161
            162
            163
            164
            async def list_tools(self) -> list[ToolInfo]:
                """Tools the server offers this credential, with their JSON Schemas.
            
                Useful to detect drift against the generated models: a newer server
                may offer tools `pyt3client.models.tools` does not know yet.
                """
                return await self._session.list_tools()
            

            wait_for_thread async

            wait_for_thread(
                thread_id: str,
                *,
                run_id: str | None = None,
                timeout: float | None = None,
                until_delegated_work_settled: bool = False,
                environment_id: str | None = None
            ) -> ThreadWaitOutput
            

            Wait until a thread's run ends, for longer than one HTTP request may stay idle.

            Repeats t3_thread_wait in chunks of at most MAX_WAIT_CHUNK_SECONDS. A run ends as completed, failed, cancelled, interrupted or rolled_back; an idle thread returns at once. Timing out does not stop the run: the result then has timed_out=True and the latest status.

            Parameters:

            Name Type Description Default
            thread_id str

            Thread to wait on.

            required
            run_id str | None

            Run to wait for. Without it the server pins the thread's latest run on the first call, and later chunks keep waiting on that run.

            None
            timeout float | None

            Overall limit in seconds; waits until the run ends otherwise.

            None
            until_delegated_work_settled bool

            Also wait for the run's subagents and background tasks; result_run then names the run with the answer.

            False
            environment_id str | None

            Linked environment the thread lives in, if not this one.

            None
            Source code in src/pyt3client/client.py
            216
            217
            218
            219
            220
            221
            222
            223
            224
            225
            226
            227
            228
            229
            230
            231
            232
            233
            234
            235
            236
            237
            238
            239
            240
            241
            242
            243
            244
            245
            246
            247
            248
            249
            250
            251
            252
            253
            254
            255
            256
            257
            258
            async def wait_for_thread(
                self,
                thread_id: str,
                *,
                run_id: str | None = None,
                timeout: float | None = None,
                until_delegated_work_settled: bool = False,
                environment_id: str | None = None,
            ) -> ThreadWaitOutput:
                """Wait until a thread's run ends, for longer than one HTTP request may stay idle.
            
                Repeats `t3_thread_wait` in chunks of at most `MAX_WAIT_CHUNK_SECONDS`.
                A run ends as `completed`, `failed`, `cancelled`, `interrupted` or
                `rolled_back`; an idle thread returns at once. Timing out does not stop
                the run: the result then has `timed_out=True` and the latest status.
            
                Args:
                    thread_id: Thread to wait on.
                    run_id: Run to wait for. Without it the server pins the thread's latest
                        run on the first call, and later chunks keep waiting on that run.
                    timeout: Overall limit in seconds; waits until the run ends otherwise.
                    until_delegated_work_settled: Also wait for the run's subagents and
                        background tasks; `result_run` then names the run with the answer.
                    environment_id: Linked environment the thread lives in, if not this one.
                """
                deadline = None if timeout is None else time.monotonic() + timeout
                while True:
                    chunk = MAX_WAIT_CHUNK_SECONDS
                    if deadline is not None:
                        chunk = min(chunk, max(deadline - time.monotonic(), 0.0))
                    params = ThreadWaitInput(thread_id=thread_id, timeout_ms=chunk * 1000)
                    if run_id is not None:
                        params.run_id = run_id
                    if until_delegated_work_settled:
                        params.until_delegated_work_settled = True
                    if environment_id is not None:
                        params.environment_id = environment_id
                    result = await self.call(THREAD_WAIT, params, timeout=chunk + _WAIT_SLACK_SECONDS)
                    if not result.timed_out:
                        return result
                    if deadline is not None and time.monotonic() >= deadline:
                        return result
                    run_id = result.run_id or run_id