Skip to content

client

Class info

Classes

Name Children Inherits
RpcSocket
pyt3client.native.rpc
Requests and streams over one Effect RPC WebSocket; many may run at once.
    T3AuthError
    pyt3client.errors
    Signing in failed, or the server no longer accepts the credential.
      T3HttpError
      pyt3client.errors
      The server answered with an unexpected HTTP status.
        T3NativeClient
        pyt3client.native.client
        One socket to an environment's native RPC; subscriptions and commands share it.
          T3NativeCredentials
          pyt3client.models.auth
          A sign-in for T3 Code's native surface: its WebSocket RPC and REST API.
            T3ProtocolError
            pyt3client.errors
            The server answered in a shape this client does not understand.
              _Dispatched
              pyt3client.native.client
                _Ticket
                pyt3client.native.client
                  _TokenResponse
                  pyt3client.native.client

                    🛈 DocStrings

                    Sign-in and client for T3 Code's native surface (WebSocket RPC).

                    Sign-in (upstream packages/client-runtime/src/authorization/remote.ts, bootstrapRemoteBearerSession): a one-time pairing token is exchanged at /oauth/token (grant_type token exchange, subject_token_type urn:t3:params:oauth:token-type:environment-bootstrap) for a bearer. Each socket then needs a short-lived ticket from POST /api/auth/websocket-ticket and opens /ws?orchestrationProtocol=2&wsTicket=.... Pairing tokens come from t3 auth pairing create or Settings -> Sharing & access in T3 Code.

                    ORCHESTRATION_PROTOCOL module-attribute

                    ORCHESTRATION_PROTOCOL = 2
                    

                    ORCHESTRATION_PROTOCOL_VERSION (upstream packages/contracts/src/environment.ts).

                    T3NativeClient

                    One socket to an environment's native RPC; subscriptions and commands share it.

                    async with T3NativeClient.from_credentials(credentials) as t3:
                        async for item in t3.subscribe_thread(thread_id):
                            ...
                    
                    Source code in src/pyt3client/native/client.py
                    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
                    259
                    260
                    261
                    class T3NativeClient:
                        """One socket to an environment's native RPC; subscriptions and commands share it.
                    
                        ```python
                        async with T3NativeClient.from_credentials(credentials) as t3:
                            async for item in t3.subscribe_thread(thread_id):
                                ...
                        ```
                        """
                    
                        def __init__(
                            self, base_url: str, access_token: str, *, http_client: httpx.AsyncClient | None = None
                        ) -> None:
                            self.base_url = _origin(base_url)
                            self._access_token = access_token
                            self._http_client = http_client
                            self._socket: RpcSocket | None = None
                            self._connection: AbstractAsyncContextManager[RpcSocket] | None = None
                    
                        @classmethod
                        def from_credentials(
                            cls, credentials: T3NativeCredentials, *, http_client: httpx.AsyncClient | None = None
                        ) -> Self:
                            return cls(
                                credentials.base_url,
                                credentials.access_token.get_secret_value(),
                                http_client=http_client,
                            )
                    
                        async def __aenter__(self) -> Self:
                            url = await websocket_url(self.base_url, self._access_token, http_client=self._http_client)
                            connection = RpcSocket.connect(url)
                            self._socket = await connection.__aenter__()
                            self._connection = connection
                            return self
                    
                        async def __aexit__(
                            self,
                            exc_type: type[BaseException] | None,
                            exc_val: BaseException | None,
                            exc_tb: TracebackType | None,
                        ) -> None:
                            if self._connection is not None:
                                await self._connection.__aexit__(exc_type, exc_val, exc_tb)
                            self._connection = self._socket = None
                    
                        @property
                        def socket(self) -> RpcSocket:
                            """The open socket, for methods this client has no wrapper for."""
                            if self._socket is None:
                                msg = "T3NativeClient is not connected; use `async with`"
                                raise RuntimeError(msg)
                            return self._socket
                    
                        async def subscribe_thread(
                            self, thread_id: str, *, after_sequence: int | None = None
                        ) -> AsyncIterator[ThreadStreamItem]:
                            """The thread's snapshot, then its events as they happen (`subscribeThread`).
                    
                            Args:
                                thread_id: The thread to follow.
                                after_sequence: Resume after this event (a snapshot's `snapshot_sequence`
                                    or an event's `sequence`) instead of starting with a snapshot.
                            """
                            payload: dict[str, JsonValue] = {"threadId": thread_id}
                            if after_sequence is not None:
                                payload["afterSequence"] = after_sequence
                            async for value in self.socket.stream("orchestration.subscribeThread", payload):
                                yield parse_stream_item(value)
                    
                        async def dispatch(self, command: Mapping[str, JsonValue]) -> int:
                            """Run an orchestration command (`dispatchCommand`); returns its event sequence.
                    
                            `command` is an `OrchestrationV2Command` (upstream `orchestrationV2.ts`), such
                            as `{"type": "thread.interrupt", "threadId": ...}`; a `commandId` is added
                            when missing.
                    
                            Raises:
                                T3RpcError: The command was refused.
                            """
                            payload = {"commandId": str(uuid4()), **command}
                            result = await self.socket.call("orchestration.dispatchCommand", payload)
                            try:
                                return _Dispatched.model_validate(result).sequence
                            except ValueError as error:
                                msg = f"dispatchCommand: unexpected result {result!r}"
                                raise T3ProtocolError(msg) from error
                    
                        async def respond_to_request(
                            self,
                            thread_id: str,
                            request_id: str,
                            *,
                            decision: ApprovalDecision | None = None,
                            answers: Mapping[str, JsonValue] | None = None,
                            feedback: str | None = None,
                        ) -> int:
                            """Answer an approval (`decision`) or a question (`answers`) a thread waits on.
                    
                            Args:
                                thread_id: The thread.
                                request_id: The runtime request (`TurnItem.request_id`).
                                decision: For approvals.
                                answers: For questions: question id -> answer.
                                feedback: Text sent along with the decision, where the provider takes it.
                            """
                            command: dict[str, JsonValue] = {
                                "type": "runtime-request.respond",
                                "threadId": thread_id,
                                "requestId": request_id,
                            }
                            if decision is not None:
                                command["decision"] = decision
                            if answers is not None:
                                command["answers"] = dict(answers)
                            if feedback is not None:
                                command["feedback"] = feedback
                            return await self.dispatch(command)
                    

                    socket property

                    socket: RpcSocket
                    

                    The open socket, for methods this client has no wrapper for.

                    dispatch async

                    dispatch(command: Mapping[str, JsonValue]) -> int
                    

                    Run an orchestration command (dispatchCommand); returns its event sequence.

                    command is an OrchestrationV2Command (upstream orchestrationV2.ts), such as {"type": "thread.interrupt", "threadId": ...}; a commandId is added when missing.

                    Raises:

                    Type Description
                    T3RpcError

                    The command was refused.

                    Source code in src/pyt3client/native/client.py
                    214
                    215
                    216
                    217
                    218
                    219
                    220
                    221
                    222
                    223
                    224
                    225
                    226
                    227
                    228
                    229
                    230
                    async def dispatch(self, command: Mapping[str, JsonValue]) -> int:
                        """Run an orchestration command (`dispatchCommand`); returns its event sequence.
                    
                        `command` is an `OrchestrationV2Command` (upstream `orchestrationV2.ts`), such
                        as `{"type": "thread.interrupt", "threadId": ...}`; a `commandId` is added
                        when missing.
                    
                        Raises:
                            T3RpcError: The command was refused.
                        """
                        payload = {"commandId": str(uuid4()), **command}
                        result = await self.socket.call("orchestration.dispatchCommand", payload)
                        try:
                            return _Dispatched.model_validate(result).sequence
                        except ValueError as error:
                            msg = f"dispatchCommand: unexpected result {result!r}"
                            raise T3ProtocolError(msg) from error
                    

                    respond_to_request async

                    respond_to_request(
                        thread_id: str,
                        request_id: str,
                        *,
                        decision: ApprovalDecision | None = None,
                        answers: Mapping[str, JsonValue] | None = None,
                        feedback: str | None = None
                    ) -> int
                    

                    Answer an approval (decision) or a question (answers) a thread waits on.

                    Parameters:

                    Name Type Description Default
                    thread_id str

                    The thread.

                    required
                    request_id str

                    The runtime request (TurnItem.request_id).

                    required
                    decision ApprovalDecision | None

                    For approvals.

                    None
                    answers Mapping[str, JsonValue] | None

                    For questions: question id -> answer.

                    None
                    feedback str | None

                    Text sent along with the decision, where the provider takes it.

                    None
                    Source code in src/pyt3client/native/client.py
                    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
                    259
                    260
                    261
                    async def respond_to_request(
                        self,
                        thread_id: str,
                        request_id: str,
                        *,
                        decision: ApprovalDecision | None = None,
                        answers: Mapping[str, JsonValue] | None = None,
                        feedback: str | None = None,
                    ) -> int:
                        """Answer an approval (`decision`) or a question (`answers`) a thread waits on.
                    
                        Args:
                            thread_id: The thread.
                            request_id: The runtime request (`TurnItem.request_id`).
                            decision: For approvals.
                            answers: For questions: question id -> answer.
                            feedback: Text sent along with the decision, where the provider takes it.
                        """
                        command: dict[str, JsonValue] = {
                            "type": "runtime-request.respond",
                            "threadId": thread_id,
                            "requestId": request_id,
                        }
                        if decision is not None:
                            command["decision"] = decision
                        if answers is not None:
                            command["answers"] = dict(answers)
                        if feedback is not None:
                            command["feedback"] = feedback
                        return await self.dispatch(command)
                    

                    subscribe_thread async

                    subscribe_thread(
                        thread_id: str, *, after_sequence: int | None = None
                    ) -> AsyncIterator[ThreadStreamItem]
                    

                    The thread's snapshot, then its events as they happen (subscribeThread).

                    Parameters:

                    Name Type Description Default
                    thread_id str

                    The thread to follow.

                    required
                    after_sequence int | None

                    Resume after this event (a snapshot's snapshot_sequence or an event's sequence) instead of starting with a snapshot.

                    None
                    Source code in src/pyt3client/native/client.py
                    198
                    199
                    200
                    201
                    202
                    203
                    204
                    205
                    206
                    207
                    208
                    209
                    210
                    211
                    212
                    async def subscribe_thread(
                        self, thread_id: str, *, after_sequence: int | None = None
                    ) -> AsyncIterator[ThreadStreamItem]:
                        """The thread's snapshot, then its events as they happen (`subscribeThread`).
                    
                        Args:
                            thread_id: The thread to follow.
                            after_sequence: Resume after this event (a snapshot's `snapshot_sequence`
                                or an event's `sequence`) instead of starting with a snapshot.
                        """
                        payload: dict[str, JsonValue] = {"threadId": thread_id}
                        if after_sequence is not None:
                            payload["afterSequence"] = after_sequence
                        async for value in self.socket.stream("orchestration.subscribeThread", payload):
                            yield parse_stream_item(value)
                    

                    sign_in_native async

                    sign_in_native(
                        base_url: str,
                        pairing_token: str,
                        *,
                        label: str = "pyt3client",
                        scopes: Sequence[str] | None = None,
                        http_client: AsyncClient | None = None
                    ) -> T3NativeCredentials
                    

                    Exchange a one-time pairing token for a native bearer.

                    Parameters:

                    Name Type Description Default
                    base_url str

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

                    required
                    pairing_token str

                    The pairing token's credential (it can be used once).

                    required
                    label str

                    Client name shown in T3 Code under Settings -> Sharing & access.

                    'pyt3client'
                    scopes Sequence[str] | None

                    Scopes to ask for, at most those of the pairing token; all of them when omitted.

                    None
                    http_client AsyncClient | None

                    Client to reuse; a short-lived one is created otherwise.

                    None

                    Raises:

                    Type Description
                    T3AuthError

                    The pairing token was refused (used, expired or revoked).

                    Source code in src/pyt3client/native/client.py
                     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
                    async def sign_in_native(
                        base_url: str,
                        pairing_token: str,
                        *,
                        label: str = "pyt3client",
                        scopes: Sequence[str] | None = None,
                        http_client: httpx.AsyncClient | None = None,
                    ) -> T3NativeCredentials:
                        """Exchange a one-time pairing token for a native bearer.
                    
                        Args:
                            base_url: Environment origin, such as `http://127.0.0.1:3773`.
                            pairing_token: The pairing token's credential (it can be used once).
                            label: Client name shown in T3 Code under Settings -> Sharing & access.
                            scopes: Scopes to ask for, at most those of the pairing token; all of them
                                when omitted.
                            http_client: Client to reuse; a short-lived one is created otherwise.
                    
                        Raises:
                            T3AuthError: The pairing token was refused (used, expired or revoked).
                        """
                        origin = _origin(base_url)
                        form = {
                            "grant_type": _TOKEN_EXCHANGE,
                            "subject_token": pairing_token.strip(),
                            "subject_token_type": _BOOTSTRAP_TOKEN,
                            "requested_token_type": _ACCESS_TOKEN,
                            "client_label": label,
                            "client_device_type": "bot",
                        }
                        if scopes:
                            form["scope"] = " ".join(scopes)
                        async with _client(http_client) as client:
                            response = await client.post(f"{origin}/oauth/token", data=form)
                        if response.status_code in (httpx.codes.BAD_REQUEST, httpx.codes.UNAUTHORIZED):
                            msg = f"the pairing token was refused: {response.text[:300]}"
                            raise T3AuthError(msg)
                        if response.status_code != httpx.codes.OK:
                            msg = "native sign-in failed"
                            raise T3HttpError(msg, status=response.status_code, body=response.text)
                        token = _TokenResponse.model_validate_json(response.content)
                        return T3NativeCredentials(
                            base_url=origin,
                            access_token=SecretStr(token.access_token),
                            expires_at=datetime.now(UTC) + timedelta(seconds=token.expires_in),
                            scopes=tuple(token.scope.split()),
                        )
                    

                    websocket_url async

                    websocket_url(base_url: str, access_token: str, *, http_client: AsyncClient | None = None) -> str
                    

                    The URL of a new socket, with a fresh one-time ticket.

                    Raises:

                    Type Description
                    T3AuthError

                    The bearer was refused (revoked, expired, or an MCP token).

                    Source code in src/pyt3client/native/client.py
                    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
                    async def websocket_url(
                        base_url: str, access_token: str, *, http_client: httpx.AsyncClient | None = None
                    ) -> str:
                        """The URL of a new socket, with a fresh one-time ticket.
                    
                        Raises:
                            T3AuthError: The bearer was refused (revoked, expired, or an MCP token).
                        """
                        origin = _origin(base_url)
                        headers = {
                            "authorization": f"Bearer {access_token}",
                            "x-t3-orchestration-protocol": str(ORCHESTRATION_PROTOCOL),
                        }
                        async with _client(http_client) as client:
                            response = await client.post(f"{origin}/api/auth/websocket-ticket", headers=headers)
                        if response.status_code == httpx.codes.UNAUTHORIZED:
                            msg = (
                                "the environment refused the native credential: it may be revoked or expired,"
                                " or be an MCP token (the native surface needs its own sign-in)"
                            )
                            raise T3AuthError(msg)
                        if response.status_code != httpx.codes.OK:
                            msg = "websocket ticket"
                            raise T3HttpError(msg, status=response.status_code, body=response.text)
                        ticket = _Ticket.model_validate_json(response.content).ticket
                        scheme = "wss" if origin.startswith("https:") else "ws"
                        host = origin.split("://", 1)[1]
                        return (
                            f"{scheme}://{host}/ws?orchestrationProtocol={ORCHESTRATION_PROTOCOL}"
                            f"&wsTicket={quote(ticket, safe='')}"
                        )