Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.
| Chat and workspace agents: channels, DMs and named agents you talk to | 1 | /** |
| 2 | * Chat: channels, direct messages, threads and messages, kept by the chat | |
| 3 | * service (`services/chat`). People and agents are members alike. Plan: | |
| 4 | * docs/WORKSPACE.md. | |
| 5 | * | |
| 6 | * Wire shapes are snake_case end to end, so the site, the public API and | |
| 7 | * the live socket all carry the same objects. | |
| 8 | */ | |
| 9 | import type { ServiceBinding } from "./clients"; | |
| 10 | import type { User } from "./identity"; | |
| 11 | import type { Result } from "./result"; | |
| 12 | import type { AskerAccess } from "./workspace-agents"; | |
| 13 | ||
| 14 | /** Who is speaking: a person (by user id) or a workspace agent (by agent id). */ | |
| 15 | export type Principal = { kind: "user" | "agent"; id: string }; | |
| 16 | ||
| 17 | export function principalKey(principal: Principal): string { | |
| 18 | return `${principal.kind}:${principal.id}`; | |
| 19 | } | |
| 20 | ||
| 21 | export function parsePrincipalKey(key: string): Principal | null { | |
| 22 | const at = key.indexOf(":"); | |
| 23 | if (at < 0) return null; | |
| 24 | const kind = key.slice(0, at); | |
| 25 | const id = key.slice(at + 1); | |
| 26 | if ((kind !== "user" && kind !== "agent") || !id) return null; | |
| 27 | return { kind, id }; | |
| 28 | } | |
| 29 | ||
| 30 | /** How a member shows: resolved by the chat service when it answers. */ | |
| 31 | export type MemberProfile = Principal & { | |
| Cards you act on in chat; agents comment and review as themselves; names shown cleanly; commits on the calendar | 32 | /** `username` for a person (lowercased: what `@` mentions), `handle` for an agent. */ |
| Chat and workspace agents: channels, DMs and named agents you talk to | 33 | name: string; |
| Cards you act on in chat; agents comment and review as themselves; names shown cleanly; commits on the calendar | 34 | /** |
| 35 | * A person's username as they wrote it (`Ana`), when that differs from | |
| 36 | * `name`; absent for an agent. Shown in their card and in autocomplete. | |
| 37 | */ | |
| 38 | display_username?: string | null; | |
| 39 | /** | |
| 40 | * What chat shows them as: a person's display name, else their username | |
| 41 | * in its chosen case; an agent's display name. Read it with `memberName`. | |
| 42 | */ | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 43 | display_name: string; |
| 44 | /** Uploaded avatar hash for a person, or null for the letter avatar. */ | |
| 45 | avatar: string | null; | |
| 46 | /** An agent's one-line role ("Release manager for g1t"). */ | |
| 47 | role: string | null; | |
| Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002) | 48 | /** |
| 49 | * An agent's title ("QA Engineer"); null for a person. Chat always sets | |
| 50 | * it; optional so profiles a page makes for itself need not. | |
| 51 | */ | |
| 52 | title?: string | null; | |
| 53 | /** What an agent's pixel creature is drawn from; null for a person. Always set by chat. */ | |
| 54 | avatar_seed?: string | null; | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 55 | }; |
| 56 | ||
| Cards you act on in chat; agents comment and review as themselves; names shown cleanly; commits on the calendar | 57 | /** |
| 58 | * A member's handle as it shows (`@Ana`, without the `@`): a person's | |
| 59 | * username in its chosen case, an agent's handle. | |
| 60 | */ | |
| 61 | export function memberHandle(member: { name: string; display_username?: string | null }): string { | |
| 62 | const display = member.display_username; | |
| 63 | return display && display.toLowerCase() === member.name.toLowerCase() ? display : member.name; | |
| 64 | } | |
| 65 | ||
| 66 | /** | |
| 67 | * How a member's name is shown everywhere in chat (messages, the | |
| 68 | * sidebar, direct-message titles, typing, notifications and pushes): their | |
| 69 | * display name, else their handle in its chosen case. One rule, so every | |
| 70 | * surface agrees. | |
| 71 | */ | |
| 72 | export function memberName(member: { name: string; display_name?: string | null; display_username?: string | null }): string { | |
| 73 | return member.display_name?.trim() || memberHandle(member); | |
| 74 | } | |
| 75 | ||
| Chat and workspace agents: channels, DMs and named agents you talk to | 76 | export type ChannelKind = "channel" | "dm"; |
| 77 | ||
| 78 | export type Channel = { | |
| 79 | id: string; | |
| 80 | workspace_id: string; | |
| 81 | kind: ChannelKind; | |
| 82 | /** Lowercase, no `#`. Null for a direct message. */ | |
| 83 | name: string | null; | |
| 84 | topic: string | null; | |
| 85 | private: boolean; | |
| 86 | created_by: Principal; | |
| 87 | created_at: string; | |
| 88 | archived_at: string | null; | |
| 89 | last_message_at: string | null; | |
| 90 | }; | |
| 91 | ||
| 92 | export type ChannelMember = { | |
| 93 | channel_id: string; | |
| 94 | member: MemberProfile; | |
| 95 | role: "owner" | "member"; | |
| 96 | starred: boolean; | |
| 97 | muted: boolean; | |
| 98 | last_read_id: string | null; | |
| 99 | joined_at: string; | |
| 100 | }; | |
| 101 | ||
| 102 | /** A card g1t or an agent posts: an event, a task, an approval. */ | |
| 103 | export type MessageCard = { | |
| Cards you act on in chat; agents comment and review as themselves; names shown cleanly; commits on the calendar | 104 | /** What it is about, e.g. `pull`, `issue`, `task`, `deploy`, `approval`, `session`, `draft_issue`. */ |
| Chat and workspace agents: channels, DMs and named agents you talk to | 105 | kind: string; |
| 106 | title: string; | |
| 107 | /** A short line under the title: "3/3 checks · +214 −87". */ | |
| 108 | detail: string | null; | |
| 109 | /** A status shown on the right: "Needs approval", "Merged". */ | |
| 110 | state: string | null; | |
| 111 | /** Where clicking the card goes, relative to the site. */ | |
| 112 | href: string | null; | |
| Cards you act on in chat; agents comment and review as themselves; names shown cleanly; commits on the calendar | 113 | /** A preview in Markdown under the title: a draft issue's body, a report's first lines. */ |
| 114 | body?: string | null; | |
| 115 | /** Labelled facts shown in two columns: "Repository · acme/web", "Cap · $2.00". */ | |
| 116 | fields?: CardField[]; | |
| 117 | /** | |
| 118 | * What people can do right here. Pressing one goes to the service that | |
| 119 | * owns the card (`owner`), which checks the person may, does it, and | |
| 120 | * updates the card in place. A card without `owner` has no actions. | |
| 121 | */ | |
| 122 | actions?: CardAction[]; | |
| 123 | /** The service whose card this is and that answers its actions: `agents`. */ | |
| 124 | owner?: "agents" | null; | |
| 125 | /** What the card is about, for its owner: a session id, a draft id. */ | |
| 126 | ref?: string | null; | |
| 127 | }; | |
| 128 | ||
| 129 | export type CardField = { label: string; value: string }; | |
| 130 | ||
| 131 | /** A button on a card. */ | |
| 132 | export type CardAction = { | |
| 133 | /** Unique on the card: `stop`, `approve`, `file`. */ | |
| 134 | id: string; | |
| 135 | label: string; | |
| 136 | style?: "primary" | "danger" | "default"; | |
| 137 | /** Asked before it runs: "Stop this session and everything under it?". */ | |
| 138 | confirm?: string | null; | |
| 139 | /** A value it needs first, asked inline: an amount in dollars, or a line of text. */ | |
| 140 | input?: { kind: "money" | "text"; label: string; placeholder?: string | null; initial?: string | null } | null; | |
| 141 | /** A link instead of an action: opens this place in the site. */ | |
| 142 | href?: string | null; | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 143 | }; |
| 144 | ||
| Cards you act on in chat; agents comment and review as themselves; names shown cleanly; commits on the calendar | 145 | /** What pressing a card's action did, as the person who pressed it is told. */ |
| 146 | export type CardActionResult = { ok: boolean; message: string | null }; | |
| 147 | ||
| Chat and workspace agents: channels, DMs and named agents you talk to | 148 | export type ChatMessage = { |
| 149 | /** Time-sortable (ULID-like), so ordering by id is ordering by time. */ | |
| 150 | id: string; | |
| 151 | channel_id: string; | |
| 152 | author: MemberProfile; | |
| 153 | kind: "text" | "card"; | |
| 154 | body: string; | |
| 155 | card: MessageCard | null; | |
| 156 | /** The message this replies under, or null for a top-level message. */ | |
| 157 | thread_root: string | null; | |
| 158 | reply_count: number; | |
| 159 | last_reply_at: string | null; | |
| 160 | created_at: string; | |
| 161 | edited_at: string | null; | |
| 162 | deleted_at: string | null; | |
| Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002) | 163 | /** |
| 164 | * Its reactions, one per emoji in the order each was first used. Chat | |
| 165 | * always sets it; optional so messages a page makes for itself need not. | |
| 166 | */ | |
| 167 | reactions?: ChatReaction[]; | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 168 | }; |
| 169 | ||
| Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002) | 170 | /** |
| 171 | * One emoji's reactions on a message. `emoji` is a Unicode emoji or | |
| 172 | * `:name:` for one of the workspace's own (`CustomEmoji`). | |
| 173 | */ | |
| 174 | export type ChatReaction = { | |
| 175 | emoji: string; | |
| 176 | /** Everyone who reacted with it, people and agents alike. */ | |
| 177 | count: number; | |
| 178 | /** | |
| 179 | * Whether the viewer did. In live `message.*` events, which everyone in | |
| 180 | * the room gets, it is always false: keep your own from what you know. | |
| 181 | */ | |
| 182 | me: boolean; | |
| 183 | /** The first ten who reacted with it, for the hover list. */ | |
| 184 | by: MemberProfile[]; | |
| 185 | }; | |
| 186 | ||
| 187 | /** Who may add a workspace's emoji: every member (the default), or only its owners. */ | |
| 188 | export type EmojiUpload = "members" | "admins"; | |
| 189 | ||
| 190 | /** | |
| 191 | * One of a workspace's own emoji, used as `:name:`. Its image is served | |
| 192 | * from the usercontent origin at `/emoji/<file>` (never from the site). | |
| 193 | */ | |
| 194 | export type CustomEmoji = { | |
| 195 | name: string; | |
| 196 | /** For an alias, the emoji it is another name for; it shows that one's image. */ | |
| 197 | alias_of: string | null; | |
| 198 | /** The SHA-256 of the image's bytes. */ | |
| 199 | file: string; | |
| 200 | content_type: "image/png" | "image/gif" | "image/webp"; | |
| 201 | bytes: number; | |
| 202 | created_by: MemberProfile; | |
| 203 | created_at: string; | |
| 204 | }; | |
| 205 | ||
| 206 | export type EmojiList = { | |
| 207 | emoji: CustomEmoji[]; | |
| 208 | emoji_upload: EmojiUpload; | |
| 209 | /** Whether the viewer may add emoji and aliases. */ | |
| 210 | can_upload: boolean; | |
| 211 | /** Whether the viewer is an owner: may remove any emoji and change `emoji_upload`. */ | |
| 212 | can_manage: boolean; | |
| 213 | }; | |
| 214 | ||
| Chat controls, public profiles, shadcn selects, and no Docs tab in a project | 215 | /** Who may do something in a workspace's chat: every member, or only its owners. */ |
| 216 | export type ChatAllowed = "members" | "owners"; | |
| 217 | ||
| 218 | /** | |
| 219 | * Who may rename and archive a channel: its owners (whoever made it) and | |
| 220 | * the workspace's owners (the default), or the workspace's owners only. | |
| 221 | */ | |
| 222 | export type ChannelManagers = "channel_owners" | "owners"; | |
| 223 | ||
| 224 | /** | |
| 225 | * A workspace's chat settings, which its owners choose (Workspace, | |
| 226 | * Settings, Chat). The chat service enforces each one; the page only | |
| 227 | * hides what the viewer may not do. | |
| 228 | */ | |
| 229 | export type ChatSettings = { | |
| 230 | /** Who may create public channels. */ | |
| 231 | public_channels: ChatAllowed; | |
| 232 | /** Who may create private channels. */ | |
| 233 | private_channels: ChatAllowed; | |
| 234 | /** Who may rename, archive and unarchive channels. */ | |
| 235 | manage_channels: ChannelManagers; | |
| 236 | /** Who may add custom emoji (`admins` is the workspace's owners). */ | |
| 237 | emoji_upload: EmojiUpload; | |
| 238 | /** | |
| 239 | * The public channels someone new is put in the first time they open | |
| 240 | * Chat, by id. #general unless the owners chose otherwise. | |
| 241 | */ | |
| 242 | default_channels: string[]; | |
| 243 | }; | |
| 244 | ||
| 245 | /** What the viewer may do in a workspace's chat, from its settings and their role. */ | |
| 246 | export type ChatPermissions = { | |
| 247 | create_public_channels: boolean; | |
| 248 | create_private_channels: boolean; | |
| 249 | add_emoji: boolean; | |
| 250 | /** Whether they may change the workspace's chat settings: owners only. */ | |
| 251 | manage_settings: boolean; | |
| 252 | }; | |
| 253 | ||
| 254 | /** The chat settings page: the settings, what the viewer may do, and the public channels to choose defaults from. */ | |
| 255 | export type ChatSettingsView = { | |
| 256 | settings: ChatSettings; | |
| 257 | can: ChatPermissions; | |
| 258 | channels: Channel[]; | |
| 259 | }; | |
| 260 | ||
| 261 | /** A change to a channel: its name, its topic, or whether it is archived. Anything left out stays. */ | |
| 262 | export type ChannelChange = { name?: string; topic?: string | null; archived?: boolean }; | |
| 263 | ||
| Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002) | 264 | /** An image for a new emoji, as base64. Its type is read from its bytes, never taken from here. */ |
| 265 | export type EmojiFile = { data: string }; | |
| 266 | ||
| 267 | /** The largest custom emoji image, in bytes, and the widest or tallest, in pixels. */ | |
| 268 | export const MAX_EMOJI_BYTES = 256 * 1024; | |
| 269 | export const MAX_EMOJI_SIDE = 512; | |
| 270 | ||
| Chat and workspace agents: channels, DMs and named agents you talk to | 271 | /** One row of the Chat sidebar. */ |
| 272 | export type ChatSidebarEntry = { | |
| 273 | channel: Channel; | |
| 274 | /** "g1t-core", or the other members' names for a direct message. */ | |
| 275 | title: string; | |
| 276 | /** For a direct message: who else is in it (up to four). */ | |
| 277 | others: MemberProfile[]; | |
| 278 | starred: boolean; | |
| 279 | muted: boolean; | |
| 280 | unread: number; | |
| 281 | mentions: number; | |
| 282 | }; | |
| 283 | ||
| 284 | export type ChatSidebar = { | |
| 285 | entries: ChatSidebarEntry[]; | |
| 286 | /** Public channels in the workspace the viewer has not joined. */ | |
| 287 | browsable: number; | |
| Chat controls, public profiles, shadcn selects, and no Docs tab in a project | 288 | /** What the viewer may do, from the workspace's chat settings: the page hides what they may not. */ |
| 289 | can: ChatPermissions; | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 290 | }; |
| 291 | ||
| 292 | export type MessagePage = { | |
| 293 | messages: ChatMessage[]; | |
| 294 | /** Pass as `before` to read further back; null at the beginning. */ | |
| 295 | older: string | null; | |
| 296 | /** | |
| Write a thread up in Docs from chat; cards' buttons in notifications; a session's card stays at the top of its thread | 297 | * For a thread's first page: the message the thread is under, however |
| 298 | * many replies it has, so a thread panel always shows it (a session's | |
| 299 | * live card, say) at its top. | |
| 300 | */ | |
| 301 | root?: ChatMessage | null; | |
| 302 | /** | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 303 | * Set when the page was read with `after`: pass it as `after` again for |
| 304 | * the next messages, or null when this page reached the newest. | |
| 305 | */ | |
| 306 | newer?: string | null; | |
| 307 | }; | |
| 308 | ||
| 309 | export type NewChannel = { name: string; topic?: string | null; private?: boolean }; | |
| 310 | ||
| 311 | export type PostMessage = { body: string; thread_root?: string | null }; | |
| 312 | ||
| Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002) | 313 | /** |
| 314 | * Who will read what is said in a conversation (docs/WORKSPACE.md, "What | |
| 315 | * an agent can and can't know"): a direct message's or private channel's | |
| 316 | * people, or, for a public channel, the whole workspace. An agent answers | |
| 317 | * there only with what every one of them may see. | |
| 318 | */ | |
| 319 | export type ChatAudience = { | |
| 320 | kind: "dm" | "private" | "public"; | |
| 321 | /** The people in it (agents left out). For a public channel, its current members, for reference only. */ | |
| 322 | member_user_ids: string[]; | |
| 323 | member_count: number; | |
| 324 | }; | |
| 325 | ||
| 326 | /** A message an agent found by searching, with the conversation it is in. */ | |
| 327 | export type AgentFoundMessage = { | |
| 328 | channel_id: string; | |
| 329 | /** The channel's name, or null for a direct message. */ | |
| 330 | channel: string | null; | |
| 331 | message: ChatMessage; | |
| 332 | }; | |
| 333 | ||
| Chat and workspace agents: channels, DMs and named agents you talk to | 334 | /** The most agent-to-agent hops one person's request may start (docs/WORKSPACE.md, "Hop limit"). */ |
| 335 | export const CHAT_MAX_HOPS = 6; | |
| 336 | ||
| 337 | /** | |
| Merge branch 'worktree-agent-a1398e81ad1a64c5f' | 338 | * What an agent posts. An agent's message never wakes another agent, even |
| 339 | * when it @mentions one: only a hand-off does (`handOffAsAgent`). Its | |
| 340 | * mentions of anyone who is not a member of the conversation lose their | |
| 341 | * `@`, so they show as plain names and notify nobody. When it answers a | |
| 342 | * delivery, it passes that delivery's `hops`, `asked_by`, `asker` and | |
| 343 | * `chain` back, which a card that waits on the asker uses. Left out: asked | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 344 | * by the person who created the agent. |
| 345 | */ | |
| 346 | export type AgentPostMessage = PostMessage & { | |
| 347 | card?: MessageCard | null; | |
| 348 | hops?: number; | |
| 349 | asked_by?: string | null; | |
| 350 | /** The delivery's `asker`, handed on to agents this message wakes. Absent: none (they treat the asker as unable to change code). */ | |
| 351 | asker?: AskerAccess | null; | |
| Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002) | 352 | /** |
| 353 | * The delivery's `chain`: the agents that handled this request before | |
| 354 | * the one posting, oldest first. Chat adds the poster, and never hands | |
| 355 | * the message to the agent that sent the work to it (no ping-pong). | |
| 356 | */ | |
| 357 | chain?: string[]; | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 358 | }; |
| 359 | ||
| 360 | /** | |
| Merge branch 'worktree-agent-a1398e81ad1a64c5f' | 361 | * A conversation as an agent is told about it before every turn: what it |
| 362 | * is and who is in it, so it knows who reads what it says and who doesn't. | |
| 363 | * Every agent member is listed; people up to `CONVERSATION_PEOPLE_SHOWN` | |
| 364 | * (the person who asked always among them), with the totals beside. | |
| 365 | */ | |
| 366 | export type ConversationForAgent = { | |
| 367 | channel: Channel; | |
| 368 | /** Agents first, then people. */ | |
| 369 | members: MemberProfile[]; | |
| 370 | /** How many people and agents are in it, listed or not. */ | |
| 371 | people: number; | |
| 372 | agents: number; | |
| 373 | }; | |
| 374 | ||
| 375 | /** The most people `conversationForAgent` lists; the rest are a count. */ | |
| 376 | export const CONVERSATION_PEOPLE_SHOWN = 20; | |
| 377 | ||
| 378 | /** | |
| 379 | * An agent handing work to a colleague agent for the person who asked | |
| 380 | * (docs/WORKSPACE.md, "Agents know each other"). The fields after `brief` | |
| 381 | * are the delivery the agent is answering, passed back as for a post. | |
| 382 | */ | |
| 383 | export type AgentHandOff = { | |
| 384 | /** The colleague, by agent id. */ | |
| 385 | colleague_id: string; | |
| 386 | /** What they are asked to do, addressed to them. */ | |
| 387 | brief: string; | |
| 388 | thread_root?: string | null; | |
| 389 | hops?: number; | |
| 390 | asked_by: string; | |
| 391 | asker?: AskerAccess | null; | |
| 392 | chain?: string[]; | |
| 393 | }; | |
| 394 | ||
| 395 | /** | |
| 396 | * Where a hand-off went. `here`: the colleague is in this channel or group | |
| 397 | * direct message, and the brief was posted here. `group_dm`: the brief was | |
| 398 | * posted in the direct message of the person who asked, the agent and the | |
| 399 | * colleague (`opened` when it was new), and a card linking to it was | |
| 400 | * posted here. | |
| 401 | */ | |
| 402 | export type HandOffResult = { where: "here" | "group_dm"; channel_id: string; message_id: string; opened: boolean }; | |
| 403 | ||
| 404 | /** | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 405 | * What the live socket sends. The site opens |
| 406 | * `wss://<site>/<workspace>/chat/live?channel=<id>`; the site checks the | |
| 407 | * session and forwards the upgrade to the chat service with the viewer. | |
| 408 | */ | |
| 409 | export type ChatLiveEvent = | |
| 410 | | { type: "message.created"; message: ChatMessage } | |
| 411 | | { type: "message.updated"; message: ChatMessage } | |
| 412 | | { type: "message.deleted"; channel_id: string; id: string } | |
| 413 | | { type: "typing"; channel_id: string; member: MemberProfile; until: string } | |
| Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002) | 414 | | { type: "read"; channel_id: string; principal: Principal; last_read_id: string } |
| Chat controls, public profiles, shadcn selects, and no Docs tab in a project | 415 | | { type: "channel.updated"; channel: Channel } |
| Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002) | 416 | | { type: "reaction.added" | "reaction.removed"; channel_id: string; message_id: string; emoji: string; member: MemberProfile }; |
| Chat and workspace agents: channels, DMs and named agents you talk to | 417 | |
| 418 | /** | |
| 419 | * Header the site sets on a forwarded live socket: the viewer, as JSON. | |
| 420 | * The site forwards the upgrade to the chat service's | |
| 421 | * `GET /live?workspace=<slug>&channel=<id>` (`workspace` may be left out, | |
| 422 | * at the cost of looking up each of the viewer's workspaces). | |
| 423 | */ | |
| 424 | export const CHAT_VIEWER_HEADER = "x-g1t-chat-viewer"; | |
| 425 | ||
| Chat controls, public profiles, shadcn selects, and no Docs tab in a project | 426 | /** A channel with its members, and whether the viewer may rename or archive it. */ |
| 427 | export type ChannelDetail = { channel: Channel; members: ChannelMember[]; can_manage: boolean }; | |
| 428 | ||
| Chat and workspace agents: channels, DMs and named agents you talk to | 429 | export type ChatApi = { |
| 430 | sidebar(workspace: string, viewer: User): Promise<Result<ChatSidebar>>; | |
| 431 | channel( | |
| 432 | workspace: string, | |
| 433 | channelId: string, | |
| 434 | viewer: User, | |
| Chat controls, public profiles, shadcn selects, and no Docs tab in a project | 435 | ): Promise<Result<ChannelDetail>>; |
| Chat and workspace agents: channels, DMs and named agents you talk to | 436 | /** The same, found by its name in the workspace (`#general` or `general`), as the site's URLs name channels. */ |
| 437 | channelByName( | |
| 438 | workspace: string, | |
| 439 | name: string, | |
| 440 | viewer: User, | |
| Chat controls, public profiles, shadcn selects, and no Docs tab in a project | 441 | ): Promise<Result<ChannelDetail>>; |
| 442 | /** | |
| 443 | * Browse channels: every public channel, and the private ones the viewer | |
| 444 | * is in. With `archived`, the archived ones instead. | |
| 445 | */ | |
| 446 | browse(workspace: string, viewer: User, options?: { archived?: boolean }): Promise<Result<Channel[]>>; | |
| 447 | /** Makes a channel. Who may make a public or a private one is the workspace's setting. */ | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 448 | createChannel(workspace: string, viewer: User, input: NewChannel): Promise<Result<Channel>>; |
| 449 | /** | |
| Chat controls, public profiles, shadcn selects, and no Docs tab in a project | 450 | * Renames, archives or unarchives a channel (the workspace's |
| 451 | * `manage_channels` setting says who may), or changes its topic (any | |
| 452 | * member). #general is never renamed or archived. Everyone looking at it | |
| 453 | * gets `channel.updated`. | |
| 454 | */ | |
| 455 | updateChannel(workspace: string, channelId: string, viewer: User, change: ChannelChange): Promise<Result<Channel>>; | |
| 456 | /** The workspace's chat settings, for any member; only owners may change them. */ | |
| 457 | chatSettings(workspace: string, viewer: User): Promise<Result<ChatSettingsView>>; | |
| 458 | /** Owners only: changes some of the workspace's chat settings, and answers all of them. */ | |
| 459 | setChatSettings(workspace: string, viewer: User, change: Partial<ChatSettings>): Promise<Result<ChatSettings>>; | |
| 460 | /** | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 461 | * The direct message between the viewer and these members, created on |
| 462 | * first use. The same set of members always gets the same channel. | |
| 463 | */ | |
| 464 | openDm(workspace: string, viewer: User, members: Principal[]): Promise<Result<Channel>>; | |
| 465 | join(workspace: string, channelId: string, viewer: User): Promise<Result<null>>; | |
| 466 | leave(workspace: string, channelId: string, viewer: User): Promise<Result<null>>; | |
| 467 | /** Adds a person or an agent. An invite grants read, never write. */ | |
| 468 | invite(workspace: string, channelId: string, viewer: User, member: Principal): Promise<Result<null>>; | |
| 469 | /** | |
| 470 | * Newest first. Without `thread_root`, the channel's top-level messages; | |
| 471 | * with it, that thread's replies, plus the message they reply to as the | |
| 472 | * oldest once the page reaches the start of the thread (`older` null). | |
| 473 | * With `after` (catching up after a reconnect): the messages after that | |
| 474 | * id instead, oldest first, deleted ones included so the client can | |
| 475 | * drop them; `newer` says whether there are more. | |
| 476 | * Limit 50 by default, 200 at most. | |
| 477 | */ | |
| 478 | messages( | |
| 479 | workspace: string, | |
| 480 | channelId: string, | |
| 481 | viewer: User, | |
| 482 | page?: { before?: string | null; after?: string | null; limit?: number; thread_root?: string | null }, | |
| 483 | ): Promise<Result<MessagePage>>; | |
| 484 | post(workspace: string, channelId: string, viewer: User, message: PostMessage): Promise<Result<ChatMessage>>; | |
| 485 | edit(workspace: string, channelId: string, viewer: User, id: string, body: string): Promise<Result<ChatMessage>>; | |
| 486 | remove(workspace: string, channelId: string, viewer: User, id: string): Promise<Result<null>>; | |
| 487 | markRead(workspace: string, channelId: string, viewer: User, id: string): Promise<Result<null>>; | |
| 488 | setPreferences( | |
| 489 | workspace: string, | |
| 490 | channelId: string, | |
| 491 | viewer: User, | |
| 492 | prefs: { starred?: boolean; muted?: boolean }, | |
| 493 | ): Promise<Result<null>>; | |
| 494 | /** | |
| 495 | * Posts as an agent. Only the agents service calls this, for replies and | |
| 496 | * cards; the agent must be a member of the channel. | |
| 497 | */ | |
| 498 | postAsAgent( | |
| 499 | workspace: string, | |
| 500 | channelId: string, | |
| 501 | agentId: string, | |
| 502 | message: AgentPostMessage, | |
| 503 | ): Promise<Result<ChatMessage>>; | |
| Chat controls, public profiles, shadcn selects, and no Docs tab in a project | 504 | /** |
| 505 | * Changes a message an agent posted: its body, its card, or both. Only | |
| 506 | * the agents service calls this, to keep a session's live card current. | |
| 507 | * Changing a message wakes nobody. | |
| 508 | */ | |
| 509 | updateAsAgent( | |
| 510 | workspace: string, | |
| 511 | channelId: string, | |
| 512 | agentId: string, | |
| 513 | id: string, | |
| 514 | change: { body?: string; card?: MessageCard | null }, | |
| 515 | ): Promise<Result<ChatMessage>>; | |
| Cards you act on in chat; agents comment and review as themselves; names shown cleanly; commits on the calendar | 516 | /** |
| 517 | * A person presses an action on a card in a conversation they can read. | |
| 518 | * Chat hands it to the card's owner with the person, and the owner | |
| 519 | * decides, acts and updates the card. | |
| 520 | */ | |
| 521 | cardAction( | |
| 522 | workspace: string, | |
| 523 | channelId: string, | |
| 524 | viewer: User, | |
| 525 | messageId: string, | |
| 526 | actionId: string, | |
| 527 | input?: string | null, | |
| 528 | ): Promise<Result<CardActionResult>>; | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 529 | /** Shows "is typing" for an agent while it works on a reply. */ |
| 530 | agentTyping(workspace: string, channelId: string, agentId: string): Promise<Result<null>>; | |
| 531 | /** | |
| 532 | * What an agent reads before it replies, oldest first: with | |
| 533 | * `thread_root`, that thread (its root, then its replies); without, the | |
| 534 | * channel's or direct message's latest top-level messages. Only the | |
| 535 | * agents service calls this; the agent must be a member of the channel, | |
| 536 | * so it reads only what was said where it was invited. `limit` defaults | |
| 537 | * to 30, at most 100. | |
| 538 | */ | |
| 539 | historyForAgent( | |
| 540 | workspace: string, | |
| 541 | channelId: string, | |
| 542 | agentId: string, | |
| 543 | page?: { thread_root?: string | null; limit?: number }, | |
| 544 | ): Promise<Result<ChatMessage[]>>; | |
| Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002) | 545 | /** Internal: who reads a conversation. */ |
| 546 | audience(workspace: string, channelId: string): Promise<Result<ChatAudience>>; | |
| 547 | /** | |
| Merge branch 'worktree-agent-a1398e81ad1a64c5f' | 548 | * Internal, for an agent about to answer in `channelId`, which it must be |
| 549 | * a member of: the conversation and its members (`ConversationForAgent`). | |
| 550 | * `askedBy` (a user id) is always among the people listed. | |
| 551 | */ | |
| 552 | conversationForAgent(workspace: string, channelId: string, agentId: string, askedBy?: string | null): Promise<Result<ConversationForAgent>>; | |
| 553 | /** | |
| 554 | * Internal: `agentId`, answering in `channelId`, hands work to a | |
| 555 | * colleague agent for the person who asked. If the colleague is in this | |
| 556 | * channel or group direct message, the brief is posted here; otherwise in | |
| 557 | * the group direct message of the person, the agent and the colleague | |
| 558 | * (opened on first use), with a card here linking to it. Either way the | |
| 559 | * brief wakes the colleague, one hop further along the same chain, and | |
| 560 | * nobody else. Refused for an agent that is not of the workspace, the | |
| 561 | * agent itself, @g1t, one already in the chain, past the hop limit, or | |
| 562 | * when the person who asked is not in this conversation. | |
| 563 | */ | |
| 564 | handOffAsAgent(workspace: string, channelId: string, agentId: string, handOff: AgentHandOff): Promise<Result<HandOffResult>>; | |
| 565 | /** | |
| Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002) | 566 | * Internal, for an agent replying in `channelId`: messages matching |
| 567 | * `query` (newest first, at most 20) from conversations every person in | |
| 568 | * that conversation's audience is in, and from public channels. Never | |
| 569 | * another direct message unless it has exactly the same people. The | |
| 570 | * audience is worked out here from `channelId`, never taken from the | |
| 571 | * caller. | |
| 572 | */ | |
| 573 | searchForAgent(workspace: string, channelId: string, query: string, limit?: number): Promise<Result<AgentFoundMessage[]>>; | |
| 574 | /** | |
| 575 | * Internal, for an agent replying in `channelId`: a thread (`id`, its | |
| 576 | * root or any reply) in `targetChannelId`, oldest first, under the same | |
| 577 | * rule. A conversation the audience may not read is not found, exactly | |
| 578 | * as one that does not exist. | |
| 579 | */ | |
| 580 | threadForAgent(workspace: string, channelId: string, targetChannelId: string, id: string): Promise<Result<AgentFoundMessage[]>>; | |
| 581 | /** | |
| 582 | * Reacts to a message with `emoji` (one Unicode emoji, or `:name:` for | |
| 583 | * one of the workspace's own). Once per member per emoji; at most 50 | |
| 584 | * different emoji on a message. Answers the message's reactions now. | |
| 585 | */ | |
| 586 | react(workspace: string, channelId: string, viewer: User, messageId: string, emoji: string): Promise<Result<ChatReaction[]>>; | |
| 587 | unreact(workspace: string, channelId: string, viewer: User, messageId: string, emoji: string): Promise<Result<ChatReaction[]>>; | |
| 588 | /** Internal, for the agents service: an agent reacts (or, with `remove`, takes it back). It must be in the channel. */ | |
| 589 | reactAsAgent( | |
| 590 | workspace: string, | |
| 591 | channelId: string, | |
| 592 | agentId: string, | |
| 593 | messageId: string, | |
| 594 | emoji: string, | |
| 595 | remove?: boolean, | |
| 596 | ): Promise<Result<ChatReaction[]>>; | |
| 597 | /** The workspace's own emoji, by name, and who may add them. */ | |
| 598 | listEmoji(workspace: string, viewer: User): Promise<Result<EmojiList>>; | |
| 599 | /** Adds an emoji: a PNG, GIF or WebP of at most 256 KB and 512×512. */ | |
| 600 | addEmoji(workspace: string, viewer: User, name: string, file: EmojiFile): Promise<Result<CustomEmoji>>; | |
| 601 | /** Gives an existing emoji (`target`) another name. */ | |
| 602 | aliasEmoji(workspace: string, viewer: User, name: string, target: string): Promise<Result<CustomEmoji>>; | |
| 603 | /** Removes an emoji, and its aliases with it. Its creator or an owner may. */ | |
| 604 | removeEmoji(workspace: string, viewer: User, name: string): Promise<Result<null>>; | |
| 605 | /** Owners only: who may add emoji. */ | |
| 606 | setEmojiUpload(workspace: string, viewer: User, value: EmojiUpload): Promise<Result<EmojiUpload>>; | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 607 | }; |
| 608 | ||
| 609 | async function rpc<T>(service: ServiceBinding, method: string, args: object): Promise<T> { | |
| 610 | const response = await service.fetch(`https://service/rpc/${method}`, { | |
| 611 | method: "POST", | |
| 612 | headers: { "content-type": "application/json" }, | |
| 613 | body: JSON.stringify(args), | |
| 614 | }); | |
| 615 | if (!response.ok) { | |
| 616 | throw new Error(`${method} failed with status ${response.status}`); | |
| 617 | } | |
| 618 | return (await response.json()) as T; | |
| 619 | } | |
| 620 | ||
| 621 | export function chatClient(service: ServiceBinding): ChatApi { | |
| 622 | const call = <T>(method: string, args: object) => rpc<T>(service, method, args); | |
| 623 | return { | |
| 624 | sidebar: (workspace, viewer) => call("sidebar", { workspace, viewer }), | |
| 625 | channel: (workspace, channelId, viewer) => call("channel", { workspace, channel_id: channelId, viewer }), | |
| 626 | channelByName: (workspace, name, viewer) => call("channel_by_name", { workspace, name, viewer }), | |
| Chat controls, public profiles, shadcn selects, and no Docs tab in a project | 627 | browse: (workspace, viewer, options) => call("browse", { workspace, viewer, archived: options?.archived ?? false }), |
| Chat and workspace agents: channels, DMs and named agents you talk to | 628 | createChannel: (workspace, viewer, input) => call("create_channel", { workspace, viewer, input }), |
| Chat controls, public profiles, shadcn selects, and no Docs tab in a project | 629 | updateChannel: (workspace, channelId, viewer, change) => call("update_channel", { workspace, channel_id: channelId, viewer, change }), |
| 630 | chatSettings: (workspace, viewer) => call("chat_settings", { workspace, viewer }), | |
| 631 | setChatSettings: (workspace, viewer, change) => call("set_chat_settings", { workspace, viewer, change }), | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 632 | openDm: (workspace, viewer, members) => call("open_dm", { workspace, viewer, members }), |
| 633 | join: (workspace, channelId, viewer) => call("join", { workspace, channel_id: channelId, viewer }), | |
| 634 | leave: (workspace, channelId, viewer) => call("leave", { workspace, channel_id: channelId, viewer }), | |
| 635 | invite: (workspace, channelId, viewer, member) => | |
| 636 | call("invite", { workspace, channel_id: channelId, viewer, member }), | |
| 637 | messages: (workspace, channelId, viewer, page) => | |
| 638 | call("messages", { | |
| 639 | workspace, | |
| 640 | channel_id: channelId, | |
| 641 | viewer, | |
| 642 | before: page?.before ?? null, | |
| 643 | after: page?.after ?? null, | |
| 644 | limit: page?.limit ?? null, | |
| 645 | thread_root: page?.thread_root ?? null, | |
| 646 | }), | |
| 647 | post: (workspace, channelId, viewer, message) => call("post", { workspace, channel_id: channelId, viewer, message }), | |
| 648 | edit: (workspace, channelId, viewer, id, body) => call("edit", { workspace, channel_id: channelId, viewer, id, body }), | |
| 649 | remove: (workspace, channelId, viewer, id) => call("remove", { workspace, channel_id: channelId, viewer, id }), | |
| 650 | markRead: (workspace, channelId, viewer, id) => call("mark_read", { workspace, channel_id: channelId, viewer, id }), | |
| 651 | setPreferences: (workspace, channelId, viewer, prefs) => | |
| 652 | call("set_preferences", { workspace, channel_id: channelId, viewer, prefs }), | |
| 653 | postAsAgent: (workspace, channelId, agentId, message) => | |
| 654 | call("post_as_agent", { workspace, channel_id: channelId, agent_id: agentId, message }), | |
| Cards you act on in chat; agents comment and review as themselves; names shown cleanly; commits on the calendar | 655 | cardAction: (workspace, channelId, viewer, messageId, actionId, input) => |
| 656 | call("card_action", { workspace, channel_id: channelId, viewer, message_id: messageId, action_id: actionId, input: input ?? null }), | |
| Chat controls, public profiles, shadcn selects, and no Docs tab in a project | 657 | updateAsAgent: (workspace, channelId, agentId, id, change) => |
| 658 | call("update_as_agent", { workspace, channel_id: channelId, agent_id: agentId, id, change }), | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 659 | agentTyping: (workspace, channelId, agentId) => |
| 660 | call("agent_typing", { workspace, channel_id: channelId, agent_id: agentId }), | |
| Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002) | 661 | audience: (workspace, channelId) => call("audience", { workspace, channel_id: channelId }), |
| Merge branch 'worktree-agent-a1398e81ad1a64c5f' | 662 | conversationForAgent: (workspace, channelId, agentId, askedBy) => |
| 663 | call("conversation_for_agent", { workspace, channel_id: channelId, agent_id: agentId, asked_by: askedBy ?? null }), | |
| 664 | handOffAsAgent: (workspace, channelId, agentId, handOff) => | |
| 665 | call("hand_off_as_agent", { workspace, channel_id: channelId, agent_id: agentId, hand_off: handOff }), | |
| Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002) | 666 | searchForAgent: (workspace, channelId, query, limit) => |
| 667 | call("search_for_agent", { workspace, channel_id: channelId, query, limit: limit ?? null }), | |
| 668 | threadForAgent: (workspace, channelId, targetChannelId, id) => | |
| 669 | call("thread_for_agent", { workspace, channel_id: channelId, target_channel_id: targetChannelId, id }), | |
| 670 | react: (workspace, channelId, viewer, messageId, emoji) => | |
| 671 | call("react", { workspace, channel_id: channelId, viewer, message_id: messageId, emoji }), | |
| 672 | unreact: (workspace, channelId, viewer, messageId, emoji) => | |
| 673 | call("unreact", { workspace, channel_id: channelId, viewer, message_id: messageId, emoji }), | |
| 674 | reactAsAgent: (workspace, channelId, agentId, messageId, emoji, remove) => | |
| 675 | call("react_as_agent", { workspace, channel_id: channelId, agent_id: agentId, message_id: messageId, emoji, remove: remove ?? false }), | |
| 676 | listEmoji: (workspace, viewer) => call("list_emoji", { workspace, viewer }), | |
| 677 | addEmoji: (workspace, viewer, name, file) => call("add_emoji", { workspace, viewer, name, file }), | |
| 678 | aliasEmoji: (workspace, viewer, name, target) => call("alias_emoji", { workspace, viewer, name, target }), | |
| 679 | removeEmoji: (workspace, viewer, name) => call("remove_emoji", { workspace, viewer, name }), | |
| 680 | setEmojiUpload: (workspace, viewer, value) => call("set_emoji_upload", { workspace, viewer, value }), | |
| Chat and workspace agents: channels, DMs and named agents you talk to | 681 | historyForAgent: (workspace, channelId, agentId, page) => |
| 682 | call("history_for_agent", { | |
| 683 | workspace, | |
| 684 | channel_id: channelId, | |
| 685 | agent_id: agentId, | |
| 686 | thread_root: page?.thread_root ?? null, | |
| 687 | limit: page?.limit ?? null, | |
| 688 | }), | |
| 689 | }; | |
| 690 | } |
This file's history is long; its oldest lines are credited to the oldest commit read.