Skip to content
305 linesCodeBlameRaw

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.

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)1/**
2 * Notifications: the notify service (`services/notify`) keeps one feed per
3 * person, a Durable Object holding their open tabs' sockets, their latest
4 * notifications, live unread counts and their browser push subscriptions.
5 *
6 * Chat tells it about every message a person should count or hear of, the
7 * events service about every inbox item, and the site forwards each tab's
8 * `/-/live` socket to it. Wire shapes are snake_case end to end.
9 */
Agents have faces, and are never mistaken for people. Every agent wears a little bot face drawn from a look it owns, shape, colour, eyes, mouth, antenna, accessory and pattern, chosen in its builder and on its Profile tab with a live preview, Shuffle and a way back to the face its seed gives it; the face blinks on its own time, breathes, narrows its eyes while the agent works, shuts them asleep and bounces when it finishes, all of it still for anyone who asked for less motion. Wherever an agent shows, in chat, in a list, on a mention, on a review or a commit, its avatar carries an agent marker, and the people reading it are told so. In Chat, direct messages are two lists: People, and Agents, which also holds the agents you haven't talked to yet; a conversation with both a person and an agent in it is marked in the list, named in the conversation's header, spelled out by the composer and explained once the first time it opens. Agents keep their look in the agents service, which every service passes along. The chat and agents guides say so, and CONTRIBUTING makes the shared avatar the only way to draw an agent.10import type { AgentLook } from "./agent-look";
Write a thread up in Docs from chat; cards' buttons in notifications; a session's card stays at the top of its thread11import type { CardAction } from "./chat";
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)12import type { ServiceBinding } from "./clients";
13import type { User } from "./identity";
14
15/** What a notification is about; the preferences decide which ones toast and push. */
16export type NotificationKind = "dm" | "mention" | "thread_reply" | "inbox" | "agent_waiting" | "approval";
17
18export const NOTIFICATION_KINDS: readonly NotificationKind[] = ["dm", "mention", "thread_reply", "inbox", "agent_waiting", "approval"];
19
20/** Who it is from: a person, an agent, or g1t itself. */
21export type NotificationActor = {
22 kind: "user" | "agent" | "system";
23 id: string;
24 /** How they show: a display name. */
25 name: string;
26 /** A person's uploaded avatar hash, or null for the letter avatar. */
27 avatar?: string | null;
Agents have faces, and are never mistaken for people. Every agent wears a little bot face drawn from a look it owns, shape, colour, eyes, mouth, antenna, accessory and pattern, chosen in its builder and on its Profile tab with a live preview, Shuffle and a way back to the face its seed gives it; the face blinks on its own time, breathes, narrows its eyes while the agent works, shuts them asleep and bounces when it finishes, all of it still for anyone who asked for less motion. Wherever an agent shows, in chat, in a list, on a mention, on a review or a commit, its avatar carries an agent marker, and the people reading it are told so. In Chat, direct messages are two lists: People, and Agents, which also holds the agents you haven't talked to yet; a conversation with both a person and an agent in it is marked in the list, named in the conversation's header, spelled out by the composer and explained once the first time it opens. Agents keep their look in the agents service, which every service passes along. The chat and agents guides say so, and CONTRIBUTING makes the shared avatar the only way to draw an agent.28 /** What an agent's face is drawn from when it chose none. */
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)29 avatar_seed?: string | null;
Agents have faces, and are never mistaken for people. Every agent wears a little bot face drawn from a look it owns, shape, colour, eyes, mouth, antenna, accessory and pattern, chosen in its builder and on its Profile tab with a live preview, Shuffle and a way back to the face its seed gives it; the face blinks on its own time, breathes, narrows its eyes while the agent works, shuts them asleep and bounces when it finishes, all of it still for anyone who asked for less motion. Wherever an agent shows, in chat, in a list, on a mention, on a review or a commit, its avatar carries an agent marker, and the people reading it are told so. In Chat, direct messages are two lists: People, and Agents, which also holds the agents you haven't talked to yet; a conversation with both a person and an agent in it is marked in the list, named in the conversation's header, spelled out by the composer and explained once the first time it opens. Agents keep their look in the agents service, which every service passes along. The chat and agents guides say so, and CONTRIBUTING makes the shared avatar the only way to draw an agent.30 /** An agent's chosen face (./agent-look.ts). */
31 look?: AgentLook | 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)32};
33
34export type FeedNotification = {
35 /** Unique per notification: the same id twice is told once. */
36 id: string;
37 kind: NotificationKind;
38 /** The workspace's slug. */
39 workspace: string;
40 title: string;
41 /** A short preview, a line or two. */
42 body: string;
43 /** Where clicking it goes, relative to the site. */
44 href: string;
45 actor: NotificationActor;
46 /** The conversation it is in, for a chat notification: toasts for the open one are skipped, and pushes collapse by it. */
47 channel_id?: string | null;
48 /** The thread it is in, for a reply: quick replies go there. */
49 thread_root?: string | null;
Write a thread up in Docs from chat; cards' buttons in notifications; a session's card stays at the top of its thread50 /**
51 * The chat card it is about, when that card has something to press: a
52 * session at its cap (Approve more, Stop, Open), a draft issue (File
53 * issue, Discard). The toast and the notifications panel show these
54 * actions, and pressing one goes to the site's `card_action`, exactly as
The docs folder is gone, and what it held lives where people read it: how a self-hosted g1t runs and how to deploy g1t to Cloudflare are pages on docs.g1t.sh under Run g1t yourself, and speed, rate limits and operating g1t.sh are sections of CONTRIBUTING.md; code that cited a file in docs/ now points to the page or section that covers it, or says what it means itself, and applied migrations and the runner images are left as they were.55 * on the card itself.
Write a thread up in Docs from chat; cards' buttons in notifications; a session's card stays at the top of its thread56 */
57 card?: NotificationCard | 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)58 created_at: string;
59};
60
Write a thread up in Docs from chat; cards' buttons in notifications; a session's card stays at the top of its thread61/** A card's place and its main actions, carried on a notification about it. */
62export type NotificationCard = {
63 /** The conversation the card is in. */
64 channel_id: string;
65 /** The message that is the card. */
66 message_id: string;
67 /** The card's actions as it offers them: ids, labels, inputs and links, the same as on the card. */
68 actions: CardAction[];
69};
70
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)71/** How much a person hears of. Counts always move; this governs toasts and pushes. */
72export type NotifyLevel = "all" | "dms_mentions" | "none";
73
74export const NOTIFY_LEVELS: readonly NotifyLevel[] = ["all", "dms_mentions", "none"];
75
76export type NotifyPreferences = {
77 level: NotifyLevel;
78 /** A different level for a workspace, by slug. */
79 workspaces: Record<string, NotifyLevel>;
80};
81
82/** A change to them: a workspace set to null goes back to the general level. */
83export type NotifyPreferencesChange = { level?: NotifyLevel; workspaces?: Record<string, NotifyLevel | null> };
84
85export const DEFAULT_NOTIFY_PREFERENCES: NotifyPreferences = { level: "dms_mentions", workspaces: {} };
86
87/** A browser's push subscription, as `PushSubscription.toJSON()` gives it. */
88export type PushSubscriptionJson = {
89 endpoint: string;
90 expiration_time?: number | null;
91 keys: { p256dh: string; auth: string };
92};
93
94/** A conversation's unread counts for one person. */
95export type ChannelCounts = { channel_id: string; unread: number; mentions: number; muted: boolean };
96
97/**
98 * What a person has unread in a workspace. `chat_unread` leaves out muted
99 * conversations, as the rail's badge does; mentions count everywhere.
100 * `inbox_unread` is the person's whole inbox, which is not per workspace.
101 * `complete` says `per_channel` was read from chat itself (on connect), so
102 * a conversation left out of it has nothing unread.
103 */
104export type FeedCounts = {
105 workspace: string;
106 chat_unread: number;
107 chat_mentions: number;
108 inbox_unread: number;
109 per_channel: Omit<ChannelCounts, "muted">[];
110 complete: boolean;
111};
112
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers113// ── Presence and status ──────────────────────────────────────────────────
114//
115// Presence is worked out live by the person's feed from their open tabs:
116// `active` while a tab has been used in the last few minutes, `away` when
117// every tab has sat idle (or they set themselves away), `offline` once no
118// tab is open. Status is what they say about themselves: an emoji and a
119// few words, cleared at a time they chose. Do Not Disturb silences toasts
120// and pushes until a time; counts still move.
121//
122// Both are kept by the notify service (the feed, one per person) and told
123// to everyone who shares a workspace with them, over the same socket,
124// through one presence room per workspace. Nothing polls.
125
126export type Presence = "active" | "away" | "offline";
127
128/**
129 * Who set a status: the person, or something acting for them. Calendars
130 * and other integrations set `calendar` or `integration` (with their own
131 * `clear_at`); a status the person set by hand is never replaced by one.
132 */
133export type StatusSource = "manual" | "calendar" | "integration";
134
135export const STATUS_SOURCES: readonly StatusSource[] = ["manual", "calendar", "integration"];
136
137export type PersonStatus = {
138 /** One emoji, or a custom emoji's `:name:`; null for none. */
139 emoji: string | null;
140 /** A few words: "In a meeting". At most 100 characters. */
141 text: string;
142 /** When it clears itself (RFC 3339); null keeps it until changed. */
143 clear_at: string | null;
144 source: StatusSource;
145 /** When it was set (RFC 3339). */
146 set_at: string;
147};
148
149/** How a person shows to the people who share a workspace with them. */
150export type PresenceEntry = {
151 user_id: string;
152 username: string;
153 presence: Presence;
154 /** Do Not Disturb, until then (RFC 3339); null when off. */
155 dnd_until: string | null;
156 status: PersonStatus | null;
157 /** When this last changed, in ms: a later word wins. */
158 at: number;
159};
160
161/** The signed-in person's own: what everyone sees, and whether they set themselves away. */
162export type OwnPresence = PresenceEntry & { away_manual: boolean };
163
164/**
165 * A change to your own. `status: null` clears it; `away` sets (or ends)
166 * being away by hand; `dnd_until: null` resumes notifications.
167 */
168export type PresenceChange = {
169 status?: { emoji?: string | null; text: string; clear_at?: string | null; source?: StatusSource } | null;
170 away?: boolean;
171 dnd_until?: string | null;
172};
173
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)174/** What the feed socket sends a tab. */
175export type FeedEvent =
176 | { type: "hello"; notifications: FeedNotification[]; vapid_public_key: string | null; preferences: NotifyPreferences }
177 | { type: "notification"; notification: FeedNotification; toast: boolean }
178 | ({ type: "counts" } & FeedCounts)
179 | { type: "preferences"; preferences: NotifyPreferences }
180 /** The person's inbox count as it now is, after items arrive or are marked anywhere. */
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers181 | { type: "inbox"; unread: number }
182 /**
183 * People in a workspace: everyone known on connect (`full`), then each
184 * one as they change.
185 */
186 | { type: "presence"; workspace: string; people: PresenceEntry[]; full: boolean }
187 /** Your own presence, status and Do Not Disturb, on connect and after every change. */
188 | { type: "me"; me: OwnPresence };
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)189
190/**
191 * What a tab sends over the feed socket: plain `ping` every 25 s (answered
192 * without waking the feed), and a state frame whenever it gains or loses
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers193 * focus, moves to another page, or goes idle (no input for a while) or
194 * back, and the inbox count the page last read.
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)195 */
196export type FeedClientFrame =
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers197 | { type: "state"; focused: boolean; path: string; idle?: boolean }
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)198 | { type: "inbox"; unread: number };
199
200/**
201 * One delivery from chat: counts to move for one person in one
202 * conversation, and maybe a notification. `set` replaces the counts (after
203 * reading, or writing); otherwise they are added.
204 */
205export type FeedDelivery = {
206 user_id: string;
207 workspace: string;
208 counts?: {
209 channel_id: string;
210 unread: number;
211 mentions: number;
212 muted?: boolean | null;
213 set?: boolean;
214 } | null;
215 notification?: FeedNotification | null;
216};
217
218/** What the site hands the feed with a socket: who, and the counts read from chat and the inbox just now. */
219export type FeedSeed = {
220 workspace: string | null;
221 per_channel: ChannelCounts[] | null;
222 inbox_unread: number | null;
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers223 /** Every workspace the person belongs to, by slug: whose rooms hear of their presence. */
224 workspaces?: 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)225};
226
227/** Headers the site sets on a forwarded feed socket. */
228export const NOTIFY_VIEWER_HEADER = "x-g1t-notify-viewer";
229export const NOTIFY_SEED_HEADER = "x-g1t-notify-seed";
230
231export type NotifyStatus = {
232 preferences: NotifyPreferences;
233 /** How many browsers get pushes. */
234 subscriptions: number;
235 /** Whether this browser's endpoint is one of them, when it was asked about. */
236 subscribed: boolean;
237 /** The public key a browser subscribes with; null when push is not set up. */
238 vapid_public_key: string | null;
239};
240
241export type NotifyApi = {
242 /** Tells a person: their open tabs at once, and a push when none is in front of them. */
243 notify(target: { user_id?: string; username?: string }, notification: FeedNotification): Promise<{ ok: boolean }>;
244 /** Many at once, as chat sends them for a message. */
245 deliver(items: FeedDelivery[]): Promise<{ ok: boolean }>;
246 subscribe(user: User, subscription: PushSubscriptionJson, userAgent?: string | null): Promise<{ ok: boolean }>;
247 unsubscribe(user: User, endpoint: string): Promise<{ ok: boolean }>;
248 status(user: User, endpoint?: string | null): Promise<NotifyStatus>;
249 setPreferences(user: User, preferences: NotifyPreferencesChange): Promise<NotifyPreferences>;
250 /** Sends the person a test notification, toasted and pushed whatever their focus. */
251 test(user: User): Promise<{ ok: boolean; pushed: number }>;
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers252 /** Your own presence, status and Do Not Disturb. */
253 presence(user: User): Promise<OwnPresence>;
254 /**
255 * Changes your own, and tells everyone who shares a workspace with you.
256 * Integrations set a status for someone the same way, with their own
257 * `source`; one the person set by hand is kept over theirs.
258 */
259 setPresence(user: Pick<User, "id" | "username">, change: PresenceChange): Promise<OwnPresence>;
People and teams are front and centre: one directory of people and agents with presence, local time, titles, teams and what each owns; profiles with manager and reports and the agents they work with; an org chart with each team's agents beside the person who leads it; and teams of any mix, with a lead, a channel, a budget agents keep to and the agents on them. Every agent is told its teams each turn (who leads, who owns what, who's around and who to page), and the team page shows exactly what. Member management is Members and invites; the people and teams guide says how.260 /**
261 * For services: how a workspace's people show now (`userIds` narrows it).
262 * Someone the room has never heard from is not listed: they are offline.
263 */
264 workspacePresence(workspace: string, userIds?: string[] | null): Promise<PresenceEntry[]>;
The front page is Home: where you're needed comes first, however long ago it started, with what's at stake and how long it has waited; then what happened since you were last here, in words, with the agent work that settled, what landed, what deployed, what was decided and what was spent, switchable to the last 24 hours or 7 days; then what's running now. Your last visit is kept with your account, so it's the same on every device; Today's old address leads here. The home guide says how.265 /**
266 * When the person was last on the workspace's Home page (RFC 3339), or
267 * null when they never were. Kept with them, so it is the same on every
268 * device.
269 */
270 lastVisit(user: Pick<User, "id">, workspace: string): Promise<{ seen_at: string | null }>;
271 /**
272 * Marks that visit at `at` (RFC 3339): Home sends the time the page
273 * loaded, once the person has looked at it. It only moves forward, never
274 * past now nor more than a day behind it.
275 */
276 markVisit(user: Pick<User, "id">, workspace: string, at: string): Promise<{ seen_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)277};
278
279async function rpc<T>(service: ServiceBinding, method: string, args: object): Promise<T> {
280 const response = await service.fetch(`https://service/rpc/${method}`, {
281 method: "POST",
282 headers: { "content-type": "application/json" },
283 body: JSON.stringify(args),
284 });
285 if (!response.ok) throw new Error(`${method} failed with status ${response.status}`);
286 return (await response.json()) as T;
287}
288
289export function notifyClient(service: ServiceBinding): NotifyApi {
290 const call = <T>(method: string, args: object) => rpc<T>(service, method, args);
291 return {
292 notify: (target, notification) => call("notify", { user_id: target.user_id ?? null, username: target.username ?? null, notification }),
293 deliver: (items) => call("deliver", { items }),
294 subscribe: (user, subscription, userAgent) => call("subscribe", { user_id: user.id, subscription, user_agent: userAgent ?? null }),
295 unsubscribe: (user, endpoint) => call("unsubscribe", { user_id: user.id, endpoint }),
296 status: (user, endpoint) => call("status", { user_id: user.id, endpoint: endpoint ?? null }),
297 setPreferences: (user, preferences) => call("set_preferences", { user_id: user.id, preferences }),
298 test: (user) => call("test", { user_id: user.id, username: user.username }),
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers299 presence: (user) => call("presence", { user_id: user.id, username: user.username }),
300 setPresence: (user, change) => call("set_presence", { user_id: user.id, username: user.username, change }),
People and teams are front and centre: one directory of people and agents with presence, local time, titles, teams and what each owns; profiles with manager and reports and the agents they work with; an org chart with each team's agents beside the person who leads it; and teams of any mix, with a lead, a channel, a budget agents keep to and the agents on them. Every agent is told its teams each turn (who leads, who owns what, who's around and who to page), and the team page shows exactly what. Member management is Members and invites; the people and teams guide says how.301 workspacePresence: (workspace, userIds) => call("workspace_presence", { workspace, user_ids: userIds ?? null }),
The front page is Home: where you're needed comes first, however long ago it started, with what's at stake and how long it has waited; then what happened since you were last here, in words, with the agent work that settled, what landed, what deployed, what was decided and what was spent, switchable to the last 24 hours or 7 days; then what's running now. Your last visit is kept with your account, so it's the same on every device; Today's old address leads here. The home guide says how.302 lastVisit: (user, workspace) => call("last_visit", { user_id: user.id, workspace }),
303 markVisit: (user, workspace, at) => call("mark_visit", { user_id: user.id, workspace, at }),
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)304 };
305}

This file's history is long; its oldest lines are credited to the oldest commit read.