archastro.platform.channels.api_chat_channel

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 068983a8456f
  4
  5from collections.abc import Callable
  6from datetime import datetime
  7from typing import TYPE_CHECKING, Any, Literal, Required, TypedDict
  8
  9if TYPE_CHECKING:
 10    from archastro.phx_channel.socket import Socket
 11
 12
 13class ApiChatForkThreadInput(TypedDict, total=False):
 14    "Fork a sub-thread from an existing message"
 15
 16    message_id: Required[str]
 17    title: str
 18
 19
 20class ApiChatMarkThreadReadInput(TypedDict):
 21    "Mark a thread as read up to a given message"
 22
 23    message_id: str
 24
 25
 26class ApiChatLoadMoreMessagesInput(TypedDict, total=False):
 27    "Load additional messages with cursor-based pagination"
 28
 29    after_cursor: str
 30    before_cursor: str
 31    include_metadata: bool
 32    limit: int
 33
 34
 35class ApiChatPostMessageInput(TypedDict, total=False):
 36    "Post a new message with optional uploads and reply-to"
 37
 38    content: Required[str]
 39    idempotency_key: str
 40    reply_to: str
 41    uploads: list[dict[str, Any]]
 42
 43
 44class ApiChatPostSimpleMessageInput(TypedDict, total=False):
 45    "Post a simple text message"
 46
 47    content: str
 48    idempotency_key: str
 49    reply_to: str
 50
 51
 52class ApiChatEditMessageInput(TypedDict):
 53    "Edit an existing message's content"
 54
 55    content: str
 56    message_id: str
 57
 58
 59class ApiChatDeleteMessageInput(TypedDict):
 60    "Delete a message"
 61
 62    message_id: str
 63
 64
 65class ApiChatAddReactionInput(TypedDict):
 66    "Add an emoji reaction to a message"
 67
 68    emoji: str
 69    message_id: str
 70
 71
 72class ApiChatRemoveReactionInput(TypedDict):
 73    "Remove an emoji reaction from a message"
 74
 75    emoji: str
 76    message_id: str
 77
 78
 79class ApiChatTypingInput(TypedDict):
 80    "Signal that the current user has started or stopped typing in the thread"
 81
 82    is_typing: bool
 83
 84
 85class MessageAddedPayloadMessageAclAddItem(TypedDict, total=False):
 86    actions: Required[list[str]]
 87    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
 88    principal: str | None
 89    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
 90    principal_type: Required[str]
 91    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 92
 93
 94class MessageAddedPayloadMessageAclGrantsItem(TypedDict, total=False):
 95    actions: Required[list[str]]
 96    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
 97    principal: str | None
 98    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
 99    principal_type: Required[str]
100    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
101
102
103class MessageAddedPayloadMessageAclRemoveItem(TypedDict, total=False):
104    principal: str | None
105    'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.'
106    principal_type: Required[str]
107    'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
108
109
110class MessageAddedPayloadMessageAcl(TypedDict, total=False):
111    add: list[MessageAddedPayloadMessageAclAddItem] | None
112    "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`."
113    grants: list[MessageAddedPayloadMessageAclGrantsItem] | None
114    "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`."
115    remove: list[MessageAddedPayloadMessageAclRemoveItem] | None
116    "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."
117
118
119class MessageAddedPayloadMessageActorsItemProfilePicture(TypedDict, total=False):
120    file: str | None
121    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
122    height: int | None
123    "Height of the image in pixels. `null` if not known."
124    media: str | None
125    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
126    mime_type: str | None
127    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
128    refresh_url: str | None
129    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
130    url: str | None
131    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
132    width: int | None
133    "Width of the image in pixels. `null` if not known."
134
135
136class MessageAddedPayloadMessageActorsItem(TypedDict, total=False):
137    alias: str | None
138    "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured."
139    id: str | None
140    'Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.'
141    name: str | None
142    "Display name of the actor shown in the UI. `null` if no name is set."
143    profile_picture: MessageAddedPayloadMessageActorsItemProfilePicture | None
144    "Profile picture for the actor. `null` if the actor has no profile picture."
145
146
147class MessageAddedPayloadMessageAttachmentsItemImageSource(TypedDict, total=False):
148    file: str | None
149    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
150    height: int | None
151    "Height of the image in pixels. `null` if not known."
152    media: str | None
153    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
154    mime_type: str | None
155    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
156    refresh_url: str | None
157    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
158    url: str | None
159    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
160    width: int | None
161    "Width of the image in pixels. `null` if not known."
162
163
164class MessageAddedPayloadMessageAttachmentsItemVariantsItemImageSource(TypedDict, total=False):
165    file: str | None
166    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
167    height: int | None
168    "Height of the image in pixels. `null` if not known."
169    media: str | None
170    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
171    mime_type: str | None
172    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
173    refresh_url: str | None
174    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
175    url: str | None
176    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
177    width: int | None
178    "Width of the image in pixels. `null` if not known."
179
180
181class MessageAddedPayloadMessageAttachmentsItemVariantsItem(TypedDict, total=False):
182    content_type: str | None
183    'MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.'
184    created_at: datetime | None
185    "When this variant was created (ISO 8601)."
186    file: str | None
187    "ID of the underlying storage file that backs this variant (`fil_...`)."
188    filename: str | None
189    "Original filename of the uploaded file for this variant. `null` if the file is not loaded."
190    height: int | None
191    "Height of this variant in pixels. `null` if not recorded."
192    id: Required[str]
193    "Media variant ID (`mvr_...`)."
194    image_source: MessageAddedPayloadMessageAttachmentsItemVariantsItemImageSource | None
195    "Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types."
196    updated_at: datetime | None
197    "When this variant was last updated (ISO 8601)."
198    url: str | None
199    "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable."
200    variant_key: str | None
201    'Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).'
202    width: int | None
203    "Width of this variant in pixels. `null` if not recorded."
204
205
206class MessageAddedPayloadMessageAttachmentsItem(TypedDict, total=False):
207    content_type: str | None
208    'MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.'
209    description: str | None
210    "Short description. The page meta-description for `scraped_link`, the artifact description for `artifact`, and the task description for `task` types. `null` on other types."
211    filename: str | None
212    'Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.'
213    height: int | None
214    "Height in pixels of the media item. Present on `media` type only. `null` otherwise."
215    id: Required[str]
216    "Unique identifier for this attachment within the message."
217    image_height: int | None
218    "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise."
219    image_source: MessageAddedPayloadMessageAttachmentsItemImageSource | None
220    "Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise."
221    image_url: str | None
222    "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise."
223    image_width: int | None
224    "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise."
225    media_type: str | None
226    'The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.'
227    name: str | None
228    "Display name of the media item. Present on `media` type only. `null` otherwise."
229    object: dict[str, Any] | None
230    "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types."
231    title: str | None
232    "Display title. The page title for `scraped_link`, the artifact name for `artifact`, and the task title for `task` types. `null` on other types."
233    type: Required[str]
234    'The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, `"action"`, or `"chart"`. Determines which additional fields are present.'
235    url: str | None
236    "URL to access the resource. A signed download URL for `file` and `artifact` types; the original URL for `scraped_link`; a media playback URL for `media`. `null` on `task` and `action` types."
237    variants: list[MessageAddedPayloadMessageAttachmentsItemVariantsItem] | None
238    "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise."
239    version: int | None
240    "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise."
241    width: int | None
242    "Width in pixels of the media item. Present on `media` type only. `null` otherwise."
243
244
245class MessageAddedPayloadMessageReactionsItem(TypedDict, total=False):
246    payload: dict[str, Any] | None
247    'Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).'
248    type: Required[str]
249    'Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.'
250    user: str | None
251    "Public ID of the user who added the reaction (`usr_...`)."
252
253
254class MessageAddedPayloadMessage(TypedDict, total=False):
255    acl: MessageAddedPayloadMessageAcl | None
256    "Access control list for private messages (grants with `read` action). Only returned to resource owners (and privileged/org-admin viewers) via server-side `field_redactions: [acl: :owner]`; `null` for everyone else."
257    actors: list[MessageAddedPayloadMessageActorsItem] | None
258    "Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry."
259    agent: str | None
260    "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users."
261    agent_mode: Literal["cli", "embedded"] | None
262    "Local agent execution mode for this message. One of `cli`, `embedded`, or `null` when the message was not created by a local agent execution path."
263    attachments: list[MessageAddedPayloadMessageAttachmentsItem] | None
264    "Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments."
265    branched_thread: str | None
266    "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread."
267    content: str | None
268    "Text content of the message. `null` for messages that contain only attachments."
269    created_at: str | None
270    "When the message was posted (ISO 8601)."
271    has_replies: bool | None
272    "Whether this message has at least one reply. Only present when explicitly requested or computed by the server."
273    id: Required[str]
274    "Message ID (`msg_...`)."
275    idempotency_key: str | None
276    "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one."
277    is_deleted: bool | None
278    "Whether this message is a deletion tombstone. `true` only on the `message_updated` broadcast emitted when a message is deleted: the original content is replaced with a placeholder and the message no longer exists on the server. Always `false` for live messages."
279    legacy_agent: str | None
280    "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users."
281    metadata: dict[str, Any] | None
282    "Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set."
283    org: str | None
284    "ID of the organization that owns this message (`org_...`)."
285    reactions: list[MessageAddedPayloadMessageReactionsItem] | None
286    "Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded."
287    rendering_mode: str | None
288    'Display hint for how the message should be rendered. One of `"reply"`, `"direct"`, or `"inline"`. `null` for user-authored messages, which are always rendered as standard replies.'
289    replies: list[dict[str, Any]] | None
290    "Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message."
291    replies_after_cursor: str | None
292    "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response."
293    replies_before_cursor: str | None
294    "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response."
295    reply_count: int | None
296    "Total number of direct replies to this message. Only present when explicitly requested or computed by the server."
297    reply_to: dict[str, Any] | None
298    "The parent message this message is a reply to, expanded as a full message object when loaded. `null` if this is a top-level message or the association is not preloaded."
299    root_message_id: str | None
300    "ID of the root message in this reply chain (`msg_...`). `null` for a top-level message. The value is persisted when the reply is created, so callers can correlate a multi-turn session without walking parent messages."
301    sandbox: str | None
302    "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages."
303    team: str | None
304    "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped."
305    thread: str | None
306    "ID of the thread this message belongs to (`thr_...`)."
307    type: str | None
308    "Optional client-defined classification for the message (for example `note` or `status`). Free-form string up to 64 characters. The value `system` is reserved for platform-authored messages and cannot be set by clients. `null` when unset."
309    user: str | dict[str, Any] | None
310    "The human user who sent this message. Returns a public ID string (`usr_...`) when the association is not preloaded, or an expanded user object when it is. `null` for messages sent by agents."
311    visibility: Literal["default", "private"] | None
312    "Message-level visibility. `default` is visible to anyone who can see the parent thread. `private` is restricted to the sender and explicit ACL `read` grantees."
313
314
315class MessageAddedPayload(TypedDict, total=False):
316    "Broadcast when a new message is added to a thread"
317
318    after_cursor: str | None
319    before_cursor: str | None
320    message: MessageAddedPayloadMessage | None
321    "A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata."
322    thread_id: str | None
323
324
325class MessageUpdatedPayloadMessageAclAddItem(TypedDict, total=False):
326    actions: Required[list[str]]
327    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
328    principal: str | None
329    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
330    principal_type: Required[str]
331    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
332
333
334class MessageUpdatedPayloadMessageAclGrantsItem(TypedDict, total=False):
335    actions: Required[list[str]]
336    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
337    principal: str | None
338    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
339    principal_type: Required[str]
340    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
341
342
343class MessageUpdatedPayloadMessageAclRemoveItem(TypedDict, total=False):
344    principal: str | None
345    'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.'
346    principal_type: Required[str]
347    'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
348
349
350class MessageUpdatedPayloadMessageAcl(TypedDict, total=False):
351    add: list[MessageUpdatedPayloadMessageAclAddItem] | None
352    "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`."
353    grants: list[MessageUpdatedPayloadMessageAclGrantsItem] | None
354    "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`."
355    remove: list[MessageUpdatedPayloadMessageAclRemoveItem] | None
356    "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."
357
358
359class MessageUpdatedPayloadMessageActorsItemProfilePicture(TypedDict, total=False):
360    file: str | None
361    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
362    height: int | None
363    "Height of the image in pixels. `null` if not known."
364    media: str | None
365    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
366    mime_type: str | None
367    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
368    refresh_url: str | None
369    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
370    url: str | None
371    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
372    width: int | None
373    "Width of the image in pixels. `null` if not known."
374
375
376class MessageUpdatedPayloadMessageActorsItem(TypedDict, total=False):
377    alias: str | None
378    "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured."
379    id: str | None
380    'Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.'
381    name: str | None
382    "Display name of the actor shown in the UI. `null` if no name is set."
383    profile_picture: MessageUpdatedPayloadMessageActorsItemProfilePicture | None
384    "Profile picture for the actor. `null` if the actor has no profile picture."
385
386
387class MessageUpdatedPayloadMessageAttachmentsItemImageSource(TypedDict, total=False):
388    file: str | None
389    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
390    height: int | None
391    "Height of the image in pixels. `null` if not known."
392    media: str | None
393    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
394    mime_type: str | None
395    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
396    refresh_url: str | None
397    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
398    url: str | None
399    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
400    width: int | None
401    "Width of the image in pixels. `null` if not known."
402
403
404class MessageUpdatedPayloadMessageAttachmentsItemVariantsItemImageSource(TypedDict, total=False):
405    file: str | None
406    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
407    height: int | None
408    "Height of the image in pixels. `null` if not known."
409    media: str | None
410    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
411    mime_type: str | None
412    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
413    refresh_url: str | None
414    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
415    url: str | None
416    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
417    width: int | None
418    "Width of the image in pixels. `null` if not known."
419
420
421class MessageUpdatedPayloadMessageAttachmentsItemVariantsItem(TypedDict, total=False):
422    content_type: str | None
423    'MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.'
424    created_at: datetime | None
425    "When this variant was created (ISO 8601)."
426    file: str | None
427    "ID of the underlying storage file that backs this variant (`fil_...`)."
428    filename: str | None
429    "Original filename of the uploaded file for this variant. `null` if the file is not loaded."
430    height: int | None
431    "Height of this variant in pixels. `null` if not recorded."
432    id: Required[str]
433    "Media variant ID (`mvr_...`)."
434    image_source: MessageUpdatedPayloadMessageAttachmentsItemVariantsItemImageSource | None
435    "Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types."
436    updated_at: datetime | None
437    "When this variant was last updated (ISO 8601)."
438    url: str | None
439    "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable."
440    variant_key: str | None
441    'Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).'
442    width: int | None
443    "Width of this variant in pixels. `null` if not recorded."
444
445
446class MessageUpdatedPayloadMessageAttachmentsItem(TypedDict, total=False):
447    content_type: str | None
448    'MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.'
449    description: str | None
450    "Short description. The page meta-description for `scraped_link`, the artifact description for `artifact`, and the task description for `task` types. `null` on other types."
451    filename: str | None
452    'Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.'
453    height: int | None
454    "Height in pixels of the media item. Present on `media` type only. `null` otherwise."
455    id: Required[str]
456    "Unique identifier for this attachment within the message."
457    image_height: int | None
458    "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise."
459    image_source: MessageUpdatedPayloadMessageAttachmentsItemImageSource | None
460    "Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise."
461    image_url: str | None
462    "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise."
463    image_width: int | None
464    "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise."
465    media_type: str | None
466    'The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.'
467    name: str | None
468    "Display name of the media item. Present on `media` type only. `null` otherwise."
469    object: dict[str, Any] | None
470    "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types."
471    title: str | None
472    "Display title. The page title for `scraped_link`, the artifact name for `artifact`, and the task title for `task` types. `null` on other types."
473    type: Required[str]
474    'The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, `"action"`, or `"chart"`. Determines which additional fields are present.'
475    url: str | None
476    "URL to access the resource. A signed download URL for `file` and `artifact` types; the original URL for `scraped_link`; a media playback URL for `media`. `null` on `task` and `action` types."
477    variants: list[MessageUpdatedPayloadMessageAttachmentsItemVariantsItem] | None
478    "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise."
479    version: int | None
480    "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise."
481    width: int | None
482    "Width in pixels of the media item. Present on `media` type only. `null` otherwise."
483
484
485class MessageUpdatedPayloadMessageReactionsItem(TypedDict, total=False):
486    payload: dict[str, Any] | None
487    'Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).'
488    type: Required[str]
489    'Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.'
490    user: str | None
491    "Public ID of the user who added the reaction (`usr_...`)."
492
493
494class MessageUpdatedPayloadMessage(TypedDict, total=False):
495    acl: MessageUpdatedPayloadMessageAcl | None
496    "Access control list for private messages (grants with `read` action). Only returned to resource owners (and privileged/org-admin viewers) via server-side `field_redactions: [acl: :owner]`; `null` for everyone else."
497    actors: list[MessageUpdatedPayloadMessageActorsItem] | None
498    "Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry."
499    agent: str | None
500    "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users."
501    agent_mode: Literal["cli", "embedded"] | None
502    "Local agent execution mode for this message. One of `cli`, `embedded`, or `null` when the message was not created by a local agent execution path."
503    attachments: list[MessageUpdatedPayloadMessageAttachmentsItem] | None
504    "Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments."
505    branched_thread: str | None
506    "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread."
507    content: str | None
508    "Text content of the message. `null` for messages that contain only attachments."
509    created_at: str | None
510    "When the message was posted (ISO 8601)."
511    has_replies: bool | None
512    "Whether this message has at least one reply. Only present when explicitly requested or computed by the server."
513    id: Required[str]
514    "Message ID (`msg_...`)."
515    idempotency_key: str | None
516    "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one."
517    is_deleted: bool | None
518    "Whether this message is a deletion tombstone. `true` only on the `message_updated` broadcast emitted when a message is deleted: the original content is replaced with a placeholder and the message no longer exists on the server. Always `false` for live messages."
519    legacy_agent: str | None
520    "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users."
521    metadata: dict[str, Any] | None
522    "Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set."
523    org: str | None
524    "ID of the organization that owns this message (`org_...`)."
525    reactions: list[MessageUpdatedPayloadMessageReactionsItem] | None
526    "Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded."
527    rendering_mode: str | None
528    'Display hint for how the message should be rendered. One of `"reply"`, `"direct"`, or `"inline"`. `null` for user-authored messages, which are always rendered as standard replies.'
529    replies: list[dict[str, Any]] | None
530    "Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message."
531    replies_after_cursor: str | None
532    "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response."
533    replies_before_cursor: str | None
534    "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response."
535    reply_count: int | None
536    "Total number of direct replies to this message. Only present when explicitly requested or computed by the server."
537    reply_to: dict[str, Any] | None
538    "The parent message this message is a reply to, expanded as a full message object when loaded. `null` if this is a top-level message or the association is not preloaded."
539    root_message_id: str | None
540    "ID of the root message in this reply chain (`msg_...`). `null` for a top-level message. The value is persisted when the reply is created, so callers can correlate a multi-turn session without walking parent messages."
541    sandbox: str | None
542    "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages."
543    team: str | None
544    "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped."
545    thread: str | None
546    "ID of the thread this message belongs to (`thr_...`)."
547    type: str | None
548    "Optional client-defined classification for the message (for example `note` or `status`). Free-form string up to 64 characters. The value `system` is reserved for platform-authored messages and cannot be set by clients. `null` when unset."
549    user: str | dict[str, Any] | None
550    "The human user who sent this message. Returns a public ID string (`usr_...`) when the association is not preloaded, or an expanded user object when it is. `null` for messages sent by agents."
551    visibility: Literal["default", "private"] | None
552    "Message-level visibility. `default` is visible to anyone who can see the parent thread. `private` is restricted to the sender and explicit ACL `read` grantees."
553
554
555class MessageUpdatedPayload(TypedDict, total=False):
556    "Broadcast when a message is updated or removed"
557
558    message: MessageUpdatedPayloadMessage | None
559    "A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata."
560    thread_id: str | None
561
562
563class ThreadEventPayload(TypedDict, total=False):
564    "Broadcast thread-level events (agent updates, read state, unread counts)"
565
566    payload: dict[str, Any] | None
567    thread_id: str | None
568    type: str | None
569
570
571class SystemEventPayload(TypedDict, total=False):
572    "Broadcast system-wide events"
573
574    event: dict[str, Any] | None
575
576
577class TypingPayloadActorProfilePicture(TypedDict, total=False):
578    file: str | None
579    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
580    height: int | None
581    "Height of the image in pixels. `null` if not known."
582    media: str | None
583    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
584    mime_type: str | None
585    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
586    refresh_url: str | None
587    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
588    url: str | None
589    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
590    width: int | None
591    "Width of the image in pixels. `null` if not known."
592
593
594class TypingPayloadActor(TypedDict, total=False):
595    alias: str | None
596    "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured."
597    id: str | None
598    'Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.'
599    name: str | None
600    "Display name of the actor shown in the UI. `null` if no name is set."
601    profile_picture: TypingPayloadActorProfilePicture | None
602    "Profile picture for the actor. `null` if the actor has no profile picture."
603
604
605class TypingPayload(TypedDict, total=False):
606    "Broadcast when a participant (human or agent) starts or stops typing. Ephemeral; never persisted."
607
608    actor: TypingPayloadActor | None
609    "The entity that authored a message, either a human user or an agent."
610    is_typing: bool | None
611    thread_id: str | None
612
613
614# Channel for real-time chat messaging.
615# Supports team-scoped and user-scoped threads with keyed, transient, and direct
616# thread access patterns.
617class ApiChatChannel:
618    def __init__(self, channel, join_response=None):
619        self._channel = channel
620        self.join_response = join_response
621
622    # Join a team-scoped thread by ID
623    @staticmethod
624    def topic_team_thread(team_id: str, thread_id: str) -> str:
625        return f"api:chat:team:{team_id}:thread:{thread_id}"
626
627    # Join a team-scoped thread by ID
628    @classmethod
629    async def join_team_thread(
630        cls,
631        socket: "Socket",
632        team_id: str,
633        thread_id: str,
634        *,
635        after_cursor: str | None = None,
636        before_cursor: str | None = None,
637        include_metadata: bool | None = None,
638        limit: int | None = None,
639    ) -> "ApiChatChannel":
640        topic = cls.topic_team_thread(team_id, thread_id)
641        channel = socket.channel(topic)
642        payload: dict[str, object] = {}
643        if after_cursor is not None:
644            payload["after_cursor"] = after_cursor
645        if before_cursor is not None:
646            payload["before_cursor"] = before_cursor
647        if include_metadata is not None:
648            payload["include_metadata"] = include_metadata
649        if limit is not None:
650            payload["limit"] = limit
651        join_response = await channel.join(payload)
652        return cls(channel, join_response)
653
654    # Join or create a team-scoped keyed thread
655    @staticmethod
656    def topic_team_keyed(team_id: str, key: str) -> str:
657        return f"api:chat:team:{team_id}:key:{key}"
658
659    # Join or create a team-scoped keyed thread
660    @classmethod
661    async def join_team_keyed(
662        cls,
663        socket: "Socket",
664        team_id: str,
665        key: str,
666        *,
667        after_cursor: str | None = None,
668        before_cursor: str | None = None,
669        include_metadata: bool | None = None,
670        limit: int | None = None,
671    ) -> "ApiChatChannel":
672        topic = cls.topic_team_keyed(team_id, key)
673        channel = socket.channel(topic)
674        payload: dict[str, object] = {}
675        if after_cursor is not None:
676            payload["after_cursor"] = after_cursor
677        if before_cursor is not None:
678            payload["before_cursor"] = before_cursor
679        if include_metadata is not None:
680            payload["include_metadata"] = include_metadata
681        if limit is not None:
682            payload["limit"] = limit
683        join_response = await channel.join(payload)
684        return cls(channel, join_response)
685
686    # Join a team-scoped transient (ephemeral) thread
687    @staticmethod
688    def topic_team_transient(team_id: str, key: str) -> str:
689        return f"api:chat:team:{team_id}:transient:{key}"
690
691    # Join a team-scoped transient (ephemeral) thread
692    @classmethod
693    async def join_team_transient(
694        cls,
695        socket: "Socket",
696        team_id: str,
697        key: str,
698        *,
699        after_cursor: str | None = None,
700        before_cursor: str | None = None,
701        include_metadata: bool | None = None,
702        limit: int | None = None,
703    ) -> "ApiChatChannel":
704        topic = cls.topic_team_transient(team_id, key)
705        channel = socket.channel(topic)
706        payload: dict[str, object] = {}
707        if after_cursor is not None:
708            payload["after_cursor"] = after_cursor
709        if before_cursor is not None:
710            payload["before_cursor"] = before_cursor
711        if include_metadata is not None:
712            payload["include_metadata"] = include_metadata
713        if limit is not None:
714            payload["limit"] = limit
715        join_response = await channel.join(payload)
716        return cls(channel, join_response)
717
718    # Join a user-scoped thread by ID, optionally supplying local tools for a personal thread
719    @staticmethod
720    def topic_user_thread(thread_id: str) -> str:
721        return f"api:chat:user:thread:{thread_id}"
722
723    # Join a user-scoped thread by ID, optionally supplying local tools for a personal thread
724    @classmethod
725    async def join_user_thread(
726        cls,
727        socket: "Socket",
728        thread_id: str,
729        *,
730        after_cursor: str | None = None,
731        before_cursor: str | None = None,
732        include_metadata: bool | None = None,
733        limit: int | None = None,
734        local_tool_provider_id: str | None = None,
735        local_tools: list[dict[str, Any]] | None = None,
736    ) -> "ApiChatChannel":
737        topic = cls.topic_user_thread(thread_id)
738        channel = socket.channel(topic)
739        payload: dict[str, object] = {}
740        if after_cursor is not None:
741            payload["after_cursor"] = after_cursor
742        if before_cursor is not None:
743            payload["before_cursor"] = before_cursor
744        if include_metadata is not None:
745            payload["include_metadata"] = include_metadata
746        if limit is not None:
747            payload["limit"] = limit
748        if local_tool_provider_id is not None:
749            payload["local_tool_provider_id"] = local_tool_provider_id
750        if local_tools is not None:
751            payload["local_tools"] = local_tools
752        join_response = await channel.join(payload)
753        return cls(channel, join_response)
754
755    # Join or create a user-scoped keyed thread
756    @staticmethod
757    def topic_user_keyed(key: str) -> str:
758        return f"api:chat:user:key:{key}"
759
760    # Join or create a user-scoped keyed thread
761    @classmethod
762    async def join_user_keyed(
763        cls,
764        socket: "Socket",
765        key: str,
766        *,
767        after_cursor: str | None = None,
768        before_cursor: str | None = None,
769        include_metadata: bool | None = None,
770        limit: int | None = None,
771    ) -> "ApiChatChannel":
772        topic = cls.topic_user_keyed(key)
773        channel = socket.channel(topic)
774        payload: dict[str, object] = {}
775        if after_cursor is not None:
776            payload["after_cursor"] = after_cursor
777        if before_cursor is not None:
778            payload["before_cursor"] = before_cursor
779        if include_metadata is not None:
780            payload["include_metadata"] = include_metadata
781        if limit is not None:
782            payload["limit"] = limit
783        join_response = await channel.join(payload)
784        return cls(channel, join_response)
785
786    # Join a user-scoped transient (ephemeral) thread
787    @staticmethod
788    def topic_user_transient(key: str) -> str:
789        return f"api:chat:user:transient:{key}"
790
791    # Join a user-scoped transient (ephemeral) thread
792    @classmethod
793    async def join_user_transient(
794        cls,
795        socket: "Socket",
796        key: str,
797        *,
798        after_cursor: str | None = None,
799        before_cursor: str | None = None,
800        include_metadata: bool | None = None,
801        limit: int | None = None,
802    ) -> "ApiChatChannel":
803        topic = cls.topic_user_transient(key)
804        channel = socket.channel(topic)
805        payload: dict[str, object] = {}
806        if after_cursor is not None:
807            payload["after_cursor"] = after_cursor
808        if before_cursor is not None:
809            payload["before_cursor"] = before_cursor
810        if include_metadata is not None:
811            payload["include_metadata"] = include_metadata
812        if limit is not None:
813            payload["limit"] = limit
814        join_response = await channel.join(payload)
815        return cls(channel, join_response)
816
817    # Leave the underlying channel.
818    async def leave(self):
819        await self._channel.leave()
820
821    # Fork a sub-thread from an existing message
822    async def api_chat_fork_thread(self, payload: ApiChatForkThreadInput) -> dict[str, Any]:
823        return await self._channel.push("api:chat:fork_thread", payload)
824
825    # Mark a thread as read up to a given message
826    async def api_chat_mark_thread_read(
827        self, payload: ApiChatMarkThreadReadInput
828    ) -> dict[str, Any]:
829        return await self._channel.push("api:chat:mark_thread_read", payload)
830
831    # List all messages in the current thread
832    async def api_chat_list_messages(self, payload: dict) -> dict[str, Any]:
833        return await self._channel.push("api:chat:list_messages", payload)
834
835    # Load additional messages with cursor-based pagination
836    async def api_chat_load_more_messages(
837        self, payload: ApiChatLoadMoreMessagesInput
838    ) -> dict[str, Any]:
839        return await self._channel.push("api:chat:load_more_messages", payload)
840
841    # Post a new message with optional uploads and reply-to
842    async def api_chat_post_message(self, payload: ApiChatPostMessageInput) -> dict[str, Any]:
843        return await self._channel.push("api:chat:post_message", payload)
844
845    # Post a simple text message
846    async def api_chat_post_simple_message(
847        self, payload: ApiChatPostSimpleMessageInput
848    ) -> dict[str, Any]:
849        return await self._channel.push("api:chat:post_simple_message", payload)
850
851    # Edit an existing message's content
852    async def api_chat_edit_message(self, payload: ApiChatEditMessageInput) -> dict[str, Any]:
853        return await self._channel.push("api:chat:edit_message", payload)
854
855    # Delete a message
856    async def api_chat_delete_message(self, payload: ApiChatDeleteMessageInput) -> dict[str, Any]:
857        return await self._channel.push("api:chat:delete_message", payload)
858
859    # Add an emoji reaction to a message
860    async def api_chat_add_reaction(self, payload: ApiChatAddReactionInput) -> dict[str, Any]:
861        return await self._channel.push("api:chat:add_reaction", payload)
862
863    # Remove an emoji reaction from a message
864    async def api_chat_remove_reaction(self, payload: ApiChatRemoveReactionInput) -> dict[str, Any]:
865        return await self._channel.push("api:chat:remove_reaction", payload)
866
867    # Signal that the current user has started or stopped typing in the thread
868    async def api_chat_typing(self, payload: ApiChatTypingInput) -> dict[str, Any]:
869        return await self._channel.push("api:chat:typing", payload)
870
871    # Broadcast when a new message is added to a thread
872    def on_message_added(
873        self, callback: Callable[[MessageAddedPayload], None]
874    ) -> Callable[[], None]:
875        return self._channel.on("message_added", callback)
876
877    # Broadcast when a message is updated or removed
878    def on_message_updated(
879        self, callback: Callable[[MessageUpdatedPayload], None]
880    ) -> Callable[[], None]:
881        return self._channel.on("message_updated", callback)
882
883    # Broadcast thread-level events (agent updates, read state, unread counts)
884    def on_thread_event(self, callback: Callable[[ThreadEventPayload], None]) -> Callable[[], None]:
885        return self._channel.on("thread_event", callback)
886
887    # Broadcast system-wide events
888    def on_system_event(self, callback: Callable[[SystemEventPayload], None]) -> Callable[[], None]:
889        return self._channel.on("system_event", callback)
890
891    # Broadcast when a participant (human or agent) starts or stops typing. Ephemeral; never persisted.
892    def on_typing(self, callback: Callable[[TypingPayload], None]) -> Callable[[], None]:
893        return self._channel.on("typing", callback)