pyt3client
Class info¶
Classes¶
| Name | Children | Inherits |
|---|---|---|
| EnvironmentDescriptor pyt3client.models.environment `GET /.well-known/t3/environment`. |
||
| JsonOutput pyt3client.tool Result of a tool whose server advertises no `outputSchema`. |
||
| T3AuthError pyt3client.errors Signing in failed, or the server no longer accepts the credential. |
||
| T3Client pyt3client.client Typed client for one T3 Code environment, over its `/mcp` endpoint. |
||
| T3Credentials pyt3client.models.auth What a successful sign-in yields; persist it to reconnect without pairing again. |
||
| T3Error pyt3client.errors Base class for every error pyt3client raises. |
||
| T3HttpError pyt3client.errors The server answered with an unexpected HTTP status. |
||
| T3McpError pyt3client.errors The server answered a request with a JSON-RPC error. |
||
| 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. |
||
| T3RpcError pyt3client.errors A native RPC failed: the server ended the request with a failure, or the socket closed. |
||
| T3ToolError pyt3client.errors A tool call was refused. |
||
| ToolSpec pyt3client.tool A T3 Code MCP tool: its wire name plus the models for its arguments and result. |
🛈 DocStrings¶
pyt3client: thin, typed Python client for T3 Code environments.
T3 Code (https://github.com/pingdotgg/t3code) runs coding agents (Claude Code,
Codex, Cursor, OpenCode, ACP agents, ...) on a machine and exposes them to its
clients. This package talks to an environment through its MCP endpoint
(/mcp), the interface T3 Code offers to outside agents and scripts.
from pyt3client import T3Client, pair
from pyt3client.models.tools import THREAD_LIST, ThreadListInput
credentials = await pair("http://127.0.0.1:3773", "PAIRING-CODE")
async with T3Client.from_credentials(credentials) as t3:
threads = await t3.call(THREAD_LIST, ThreadListInput(all_projects=True))
EnvironmentDescriptor
¶
Bases: BaseModel
GET /.well-known/t3/environment.
Upstream ExecutionEnvironmentDescriptor in packages/contracts/src/environment.ts.
Clients read it before sending any credential: an address only gets a token
when it reports the expected environment_id.
Source code in src/pyt3client/models/environment.py
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 | |
capabilities
instance-attribute
¶
capabilities: dict[str, JsonValue]
Feature flags (upstream ExecutionEnvironmentCapabilities).
Dozens of mostly-boolean flags that grow with every release, so kept as a
mapping; use supports() to check one.
environment_id
class-attribute
instance-attribute
¶
environment_id: str = Field(alias='environmentId')
Stable across restarts and address changes; identifies the environment.
orchestration_protocol_version
class-attribute
instance-attribute
¶
orchestration_protocol_version: int | None = Field(None, alias='orchestrationProtocolVersion')
Version of the native WebSocket RPC protocol (ORCHESTRATION_PROTOCOL_VERSION).
supports
¶
supports(capability: str) -> bool
Whether the server advertises capability as enabled.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
capability
|
str
|
Flag name as sent by the server, such as |
required |
Source code in src/pyt3client/models/environment.py
44 45 46 47 48 49 50 | |
JsonOutput
¶
Bases: RootModel[JsonValue]
Result of a tool whose server advertises no outputSchema.
Those tools (for example t3_pending_request or t3_queue) still answer
with a JSON text block; it is decoded but not validated against a schema.
Source code in src/pyt3client/tool.py
16 17 18 19 20 21 | |
T3AuthError
¶
Bases: T3Error
Signing in failed, or the server no longer accepts the credential.
Raised for a rejected pairing code, a revoked or expired token (HTTP 401
on /mcp), and OAuth errors from /oauth/mcp/*.
Source code in src/pyt3client/errors.py
47 48 49 50 51 52 | |
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 | |
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 |
required |
token
|
str | SecretStr
|
MCP bearer token, as returned by |
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 |
None
|
client_name
|
str
|
Name reported in the MCP |
'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 | |
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 | |
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 |
required |
params
|
InputT | None
|
Its arguments; |
None
|
timeout
|
float | None
|
HTTP read timeout in seconds for this call. |
None
|
Raises:
| Type | Description |
|---|---|
T3ToolError
|
The tool refused, such as |
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 | |
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 | |
descriptor
async
¶
descriptor() -> EnvironmentDescriptor
The environment's public descriptor (id, version, capability flags).
Source code in src/pyt3client/client.py
154 155 156 | |
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 |
required |
mode_limit
|
tuple[RuntimeMode, InteractionMode] | None
|
See |
None
|
client_name
|
str
|
See |
'pyt3client'
|
timeout
|
float
|
See |
60.0
|
http_client
|
AsyncClient | None
|
See |
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 | |
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 | |
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; |
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 | |
T3Credentials
¶
Bases: BaseModel
What a successful sign-in yields; persist it to reconnect without pairing again.
The token is an ordinary environment session with subject mcp-client.
/mcp is the only endpoint that accepts it: the native WebSocket RPC and
REST API reject this subject, because their surface would let the client
act above its approved level. Revoke it in T3 Code under
Settings -> Sharing & access.
Source code in src/pyt3client/models/auth.py
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | |
T3Error
¶
Bases: Exception
Base class for every error pyt3client raises.
Source code in src/pyt3client/errors.py
34 35 | |
T3HttpError
¶
Bases: T3Error
The server answered with an unexpected HTTP status.
Source code in src/pyt3client/errors.py
38 39 40 41 42 43 44 | |
T3McpError
¶
Bases: T3Error
The server answered a request with a JSON-RPC error.
Unlike T3ToolError (a tool that ran and refused), this means the request
itself was rejected: an unknown tool, arguments that fail the tool's input
schema, or a malformed request.
Source code in src/pyt3client/errors.py
63 64 65 66 67 68 69 70 71 72 73 74 75 | |
T3NativeCredentials
¶
Bases: BaseModel
A sign-in for T3 Code's native surface: its WebSocket RPC and REST API.
That surface is what the web, desktop and mobile clients use. It streams a
thread's events as they happen and can answer approvals, which /mcp cannot.
It rejects MCP tokens, and /mcp rejects this one, so a client that uses
both holds two sign-ins. Obtained by exchanging a one-time pairing token
(t3 auth pairing create, or Settings -> Sharing & access) at /oauth/token.
Source code in src/pyt3client/models/auth.py
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | |
T3ProtocolError
¶
Bases: T3Error
The server answered in a shape this client does not understand.
Usually a version mismatch: regenerate the models against the server
(see scripts/generate_models.py) or update pyt3client.
Source code in src/pyt3client/errors.py
55 56 57 58 59 60 | |
T3RpcError
¶
Bases: T3Error
A native RPC failed: the server ended the request with a failure, or the socket closed.
Native RPC is Effect RPC over T3 Code's WebSocket (see pyt3client.native). A
request that fails ends with an Exit whose cause is a typed error (Fail, such
as OrchestrationV2DispatchCommandError), a defect (Die) or an interruption.
Source code in src/pyt3client/errors.py
92 93 94 95 96 97 98 99 100 101 102 103 104 105 | |
T3ToolError
¶
Bases: T3Error
A tool call was refused.
T3 Code reports expected refusals as an MCP result with isError: true
whose text is {"_tag": "OrchestratorMcpFailure", "code": ..., "message": ...}.
Source code in src/pyt3client/errors.py
78 79 80 81 82 83 84 85 86 87 88 89 | |
ToolSpec
dataclass
¶
A T3 Code MCP tool: its wire name plus the models for its arguments and result.
Source code in src/pyt3client/tool.py
24 25 26 27 28 29 30 31 32 33 | |
fetch_descriptor
async
¶
fetch_descriptor(base_url: str, *, http_client: AsyncClient | None = None) -> EnvironmentDescriptor
Read an environment's public descriptor; needs no credential.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_url
|
str
|
Environment origin, such as |
required |
http_client
|
AsyncClient | None
|
Client to reuse; a short-lived one is created otherwise. |
None
|
Source code in src/pyt3client/auth.py
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 | |
pair
async
¶
pair(
base_url: str,
pairing_code: str,
*,
access: McpAccess = "auto",
client_name: str = DEFAULT_CLIENT_NAME,
http_client: AsyncClient | None = None
) -> T3Credentials
Sign in to an environment's /mcp with a one-time pairing code.
The code is spent by this call. The resulting session shows up in T3 Code
under Settings -> Sharing & access with client_name as its label, lasts
30 days, and does not renew.
Agents only send credentials over https or to localhost, so use a
loopback, Tailscale HTTPS or T3 Connect address. A plain-http LAN address
works technically but sends the code unencrypted.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_url
|
str
|
Environment origin, such as |
required |
pairing_code
|
str
|
Code from |
required |
access
|
McpAccess
|
Level to approve the client at. Must not exceed what the code grants. |
'auto'
|
client_name
|
str
|
Label the environment shows for this client. |
DEFAULT_CLIENT_NAME
|
http_client
|
AsyncClient | None
|
Client to reuse; a short-lived one is created otherwise. |
None
|
Raises:
| Type | Description |
|---|---|
T3AuthError
|
The environment rejected the code or the sign-in. |
T3HttpError
|
The address does not answer like a T3 Code environment. |
Source code in src/pyt3client/auth.py
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 | |