Skip to content

models

Class info

Classes

Name Children Inherits
ApprovalOption
pyt3client.native.models
A choice an approval request offers (`ProviderApprovalOption`).
    DomainEvent
    pyt3client.native.models
    A thread event (`OrchestrationV2DomainEvent`); `payload` depends on `type`.
      NativeItemRef
      pyt3client.native.models
      The provider's own id of what an item stands for (`OrchestrationV2ProviderRef`).
        Run
        pyt3client.native.models
        A run of a thread (`run.created` / `run.updated`).
          RuntimeRequest
          pyt3client.native.models
          An approval or question a provider waits on (`OrchestrationV2RuntimeRequest`).
            T3Model
            pyt3client.models._base
            Snake-case Python fields over T3 Code's camelCase wire names.
            ThreadEvent
            pyt3client.native.models
            One event of the thread, in `sequence` order.
              ThreadSnapshot
              pyt3client.native.models
              The thread as it is when the subscription starts; events continue after it.
                ThreadSynchronized
                pyt3client.native.models
                The subscription caught up with the thread.
                  TurnItem
                  pyt3client.native.models
                  A timeline row (`OrchestrationV2TurnItem`): a message, reasoning, tool work, a request.
                    UnknownStreamItem
                    pyt3client.native.models
                    A stream item of a kind this client does not know (newer servers).
                      _Open
                      pyt3client.native.models

                      🛈 DocStrings

                      What orchestration.subscribeThread streams, as far as clients of pyt3client need it.

                      Hand-written, unlike the MCP models: the native contracts are Effect Schemas with no JSON Schema endpoint. Fields not listed here are kept (extra="allow"), so model_extra holds what newer servers add.

                      Upstream (packages/contracts/src/orchestrationV2.ts):

                      • OrchestrationV2ThreadStreamItem: snapshot (the thread's projection), then events (OrchestrationV2DomainEvent, numbered by sequence), synchronized.
                      • OrchestrationV2TurnItem (the payload of turn-item.updated): one row of the timeline. Text items grow in place while streaming is true.
                      • OrchestrationV2RuntimeRequest (runtime-request.updated): an approval or a question the provider waits on; answer it with runtime-request.respond.

                      ApprovalDecision

                      ApprovalDecision = Literal['accept', 'acceptForSession', 'acceptAlways', 'decline', 'cancel']
                      

                      ProviderApprovalDecision (upstream packages/contracts/src/providerPolicy.ts).

                      ApprovalOption

                      Bases: _Open

                      A choice an approval request offers (ProviderApprovalOption).

                      Source code in src/pyt3client/native/models.py
                      34
                      35
                      36
                      37
                      38
                      39
                      class ApprovalOption(_Open):
                          """A choice an approval request offers (`ProviderApprovalOption`)."""
                      
                          decision: ApprovalDecision
                          label: str
                          warning: str | None = None
                      

                      DomainEvent

                      Bases: _Open

                      A thread event (OrchestrationV2DomainEvent); payload depends on type.

                      Source code in src/pyt3client/native/models.py
                      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
                      class DomainEvent(_Open):
                          """A thread event (`OrchestrationV2DomainEvent`); `payload` depends on `type`."""
                      
                          type: str
                          thread_id: str | None = None
                          run_id: str | None = None
                          payload: dict[str, JsonValue]
                      
                          def turn_item(self) -> TurnItem | None:
                              """The item of a `turn-item.updated` event."""
                              if self.type != "turn-item.updated":
                                  return None
                              return TurnItem.model_validate(self.payload)
                      
                          def run(self) -> Run | None:
                              """The run of a `run.created` or `run.updated` event."""
                              if self.type not in ("run.created", "run.updated"):
                                  return None
                              return Run.model_validate(self.payload)
                      
                          def runtime_request(self) -> RuntimeRequest | None:
                              """The request of a `runtime-request.updated` event."""
                              if self.type != "runtime-request.updated":
                                  return None
                              return RuntimeRequest.model_validate(self.payload)
                      

                      run

                      run() -> Run | None
                      

                      The run of a run.created or run.updated event.

                      Source code in src/pyt3client/native/models.py
                      122
                      123
                      124
                      125
                      126
                      def run(self) -> Run | None:
                          """The run of a `run.created` or `run.updated` event."""
                          if self.type not in ("run.created", "run.updated"):
                              return None
                          return Run.model_validate(self.payload)
                      

                      runtime_request

                      runtime_request() -> RuntimeRequest | None
                      

                      The request of a runtime-request.updated event.

                      Source code in src/pyt3client/native/models.py
                      128
                      129
                      130
                      131
                      132
                      def runtime_request(self) -> RuntimeRequest | None:
                          """The request of a `runtime-request.updated` event."""
                          if self.type != "runtime-request.updated":
                              return None
                          return RuntimeRequest.model_validate(self.payload)
                      

                      turn_item

                      turn_item() -> TurnItem | None
                      

                      The item of a turn-item.updated event.

                      Source code in src/pyt3client/native/models.py
                      116
                      117
                      118
                      119
                      120
                      def turn_item(self) -> TurnItem | None:
                          """The item of a `turn-item.updated` event."""
                          if self.type != "turn-item.updated":
                              return None
                          return TurnItem.model_validate(self.payload)
                      

                      NativeItemRef

                      Bases: _Open

                      The provider's own id of what an item stands for (OrchestrationV2ProviderRef).

                      An approval request shares it with the tool call it is about.

                      Source code in src/pyt3client/native/models.py
                      42
                      43
                      44
                      45
                      46
                      47
                      48
                      49
                      class NativeItemRef(_Open):
                          """The provider's own id of what an item stands for (`OrchestrationV2ProviderRef`).
                      
                          An approval request shares it with the tool call it is about.
                          """
                      
                          driver: str
                          native_id: str
                      

                      Run

                      Bases: _Open

                      A run of a thread (run.created / run.updated).

                      Source code in src/pyt3client/native/models.py
                      88
                      89
                      90
                      91
                      92
                      93
                      94
                      95
                      class Run(_Open):
                          """A run of a thread (`run.created` / `run.updated`)."""
                      
                          id: str
                          thread_id: str
                          status: str
                          """`preparing`, `queued`, `starting`, `running`, `waiting`, `completed`,
                          `interrupted`, `failed`, `cancelled` or `rolled_back`."""
                      

                      status instance-attribute

                      status: str
                      

                      preparing, queued, starting, running, waiting, completed, interrupted, failed, cancelled or rolled_back.

                      RuntimeRequest

                      Bases: _Open

                      An approval or question a provider waits on (OrchestrationV2RuntimeRequest).

                      Source code in src/pyt3client/native/models.py
                       98
                       99
                      100
                      101
                      102
                      103
                      104
                      105
                      class RuntimeRequest(_Open):
                          """An approval or question a provider waits on (`OrchestrationV2RuntimeRequest`)."""
                      
                          id: str
                          kind: str
                          """A `ProviderRequestKind`, or `dynamic_tool_call`, `user_input`, `auth_refresh`."""
                          status: Literal["pending", "resolved", "expired", "cancelled"]
                          decision: ApprovalDecision | None = None
                      

                      kind instance-attribute

                      kind: str
                      

                      A ProviderRequestKind, or dynamic_tool_call, user_input, auth_refresh.

                      ThreadEvent

                      Bases: _Open

                      One event of the thread, in sequence order.

                      Source code in src/pyt3client/native/models.py
                      144
                      145
                      146
                      147
                      148
                      149
                      class ThreadEvent(_Open):
                          """One event of the thread, in `sequence` order."""
                      
                          kind: Literal["event"]
                          sequence: int
                          event: DomainEvent
                      

                      ThreadSnapshot

                      Bases: _Open

                      The thread as it is when the subscription starts; events continue after it.

                      Source code in src/pyt3client/native/models.py
                      135
                      136
                      137
                      138
                      139
                      140
                      141
                      class ThreadSnapshot(_Open):
                          """The thread as it is when the subscription starts; events continue after it."""
                      
                          kind: Literal["snapshot"]
                          snapshot_sequence: int
                          projection: dict[str, JsonValue]
                          """`OrchestrationV2ThreadProjection`: thread, runs, turn items, requests, ..."""
                      

                      projection instance-attribute

                      projection: dict[str, JsonValue]
                      

                      OrchestrationV2ThreadProjection: thread, runs, turn items, requests, ...

                      ThreadSynchronized

                      Bases: _Open

                      The subscription caught up with the thread.

                      Source code in src/pyt3client/native/models.py
                      152
                      153
                      154
                      155
                      class ThreadSynchronized(_Open):
                          """The subscription caught up with the thread."""
                      
                          kind: Literal["synchronized"]
                      

                      TurnItem

                      Bases: _Open

                      A timeline row (OrchestrationV2TurnItem): a message, reasoning, tool work, a request.

                      type is e.g. user_message, assistant_message, reasoning, command_execution, file_change, dynamic_tool, approval_request, user_input_request, checkpoint. status is one of idle, pending, running, waiting, completed, interrupted, failed, cancelled, rolled_back.

                      Source code in src/pyt3client/native/models.py
                      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
                      class TurnItem(_Open):
                          """A timeline row (`OrchestrationV2TurnItem`): a message, reasoning, tool work, a request.
                      
                          `type` is e.g. `user_message`, `assistant_message`, `reasoning`, `command_execution`,
                          `file_change`, `dynamic_tool`, `approval_request`, `user_input_request`,
                          `checkpoint`. `status` is one of `idle`, `pending`, `running`, `waiting`,
                          `completed`, `interrupted`, `failed`, `cancelled`, `rolled_back`.
                          """
                      
                          id: str
                          thread_id: str
                          run_id: str | None = None
                          type: str
                          status: str
                          title: str | None = None
                          text: str | None = None
                          """Text of message and reasoning items; complete once `streaming` is false."""
                          streaming: bool | None = None
                          native_item_ref: NativeItemRef | None = None
                          request_id: str | None = None
                          """For `approval_request` and `user_input_request`: the runtime request to answer."""
                          request_kind: str | None = None
                          """For `approval_request`: `command`, `file-read`, `file-change`, `mcp-elicitation`
                          or `permission` (`ProviderRequestKind`)."""
                          prompt: str | None = None
                          """For `approval_request`: what is to be approved, such as the command."""
                          reason: str | None = None
                          options: list[ApprovalOption] | None = None
                          """For `approval_request`: the decisions on offer, when the provider names them."""
                      
                          @property
                          def item_id(self) -> str:
                              """The item's id, as `/mcp`'s thread reads name it (`itemId`)."""
                              return self.id
                      

                      item_id property

                      item_id: str
                      

                      The item's id, as /mcp's thread reads name it (itemId).

                      options class-attribute instance-attribute

                      options: list[ApprovalOption] | None = None
                      

                      For approval_request: the decisions on offer, when the provider names them.

                      prompt class-attribute instance-attribute

                      prompt: str | None = None
                      

                      For approval_request: what is to be approved, such as the command.

                      request_id class-attribute instance-attribute

                      request_id: str | None = None
                      

                      For approval_request and user_input_request: the runtime request to answer.

                      request_kind class-attribute instance-attribute

                      request_kind: str | None = None
                      

                      For approval_request: command, file-read, file-change, mcp-elicitation or permission (ProviderRequestKind).

                      text class-attribute instance-attribute

                      text: str | None = None
                      

                      Text of message and reasoning items; complete once streaming is false.

                      UnknownStreamItem

                      Bases: _Open

                      A stream item of a kind this client does not know (newer servers).

                      Source code in src/pyt3client/native/models.py
                      158
                      159
                      160
                      161
                      class UnknownStreamItem(_Open):
                          """A stream item of a kind this client does not know (newer servers)."""
                      
                          kind: str
                      

                      parse_stream_item

                      parse_stream_item(value: JsonValue) -> ThreadStreamItem
                      

                      A subscribeThread stream value as a model.

                      Raises:

                      Type Description
                      ValidationError

                      A known kind with an unexpected shape.

                      Source code in src/pyt3client/native/models.py
                      167
                      168
                      169
                      170
                      171
                      172
                      173
                      174
                      175
                      176
                      177
                      178
                      179
                      180
                      181
                      182
                      def parse_stream_item(value: JsonValue) -> ThreadStreamItem:
                          """A `subscribeThread` stream value as a model.
                      
                          Raises:
                              pydantic.ValidationError: A known kind with an unexpected shape.
                          """
                          kind = value.get("kind") if isinstance(value, dict) else None
                          match kind:
                              case "snapshot":
                                  return ThreadSnapshot.model_validate(value)
                              case "event":
                                  return ThreadEvent.model_validate(value)
                              case "synchronized":
                                  return ThreadSynchronized.model_validate(value)
                              case _:
                                  return UnknownStreamItem.model_validate(value)