Skip to content

T3Client

🛈 DocStrings

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

:fa-brands-github: Show source on GitHub