Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
import postgres from "postgres";
import type { ChannelWorkWire } from "./working";
/**
* Live channel activity, from whoever ran an agent to everybody else in the channel.
*
* The person who ran it already has the reply and reports it over HTTP; this is the other direction,
* telling the channel's other members that something was said. It is an optimisation and never a
* source of truth: the roster query stays authoritative, and a client that misses events while
* disconnected recovers by refetching on reconnect. Nothing may be knowable only through the socket.
*
* Delivery goes through Postgres rather than an in-process list, because an in-process list is
* silently wrong the moment a second server instance exists: the writer is on one and the listener
* on the other, and the message is never delivered.
*
* A NOTIFY is never replayed, so an announcement made while this subscription is down is gone. The
* client's own "refetch on reconnect" does not cover it: the socket that dropped is this server's,
* not the browser's. `resyncAll` is the signal that closes that gap.
*/
export const CHANNEL_ACTIVITY_TOPIC = "channel_activity";
export type ChannelActivityEvent = {
channelId: string;
/** Who may receive it. Resolved by the writer, which already had to check membership. */
memberIds: string[];
lastMessage: string | null;
lastMessageAt: string | null;
lastMessageAgentId: string | null;
/** Newly written summary, on its own event: the sweep runs seconds after the activity it follows. */
summary?: string;
/** The channel is hidden from every member's roster. Absent on an ordinary activity event. */
deleted?: true;
/**
* One member's pin, changed. Absent on an ordinary activity event.
*
* A pin lives on one membership row, so the writer names that member alone in `memberIds` and the
* hub's delivery rule does the rest: nobody else in the channel hears a pin they did not make.
*/
pinned?: boolean;
/**
* A turn started or ended in this channel. Absent on an ordinary activity event.
*
* Transient and message-less: it is never written to a table, only announced, so the roster can
* show a working indicator for a headless turn — a handoff hop, a relay — that no browser
* streams. A missed one costs at most a stuck-looking dot until the next real event, never data.
*/
busy?: boolean;
/**
* Everything this channel is waiting on right now: a Bot it asked, a routine firing into it.
* Absent on an ordinary activity event.
*
* The WHOLE list, never a change to it, so the newest event is the answer and a missed one is
* corrected by the next. Read from the queue and the run history at the moment of sending, which
* is also what the roster and the channel read return. See `working.ts`.
*/
work?: ChannelWorkWire[];
/**
* When `work` was read, by the database's clock: ISO-8601 in UTC to the microsecond, fixed width
* so two compare as strings. Present whenever `work` is. Events
* can arrive out of order across replicas, so a browser keeps the list with the latest stamp.
*/
workAt?: string;
};
/** "The roster you hold may be wrong." Carries no delta, because what was lost is not recoverable. */
export type ChannelResyncEvent = { resync: true };
const RESYNC_PAYLOAD = JSON.stringify({
resync: true,
} satisfies ChannelResyncEvent);
type Send = (payload: string) => void;
export type ChannelEventHub = {
/** Attach a connection for a person. Returns the detach. */
register(userId: string, send: Send): () => void;
/** Fan one event out to this instance's own connections. */
deliver(event: ChannelActivityEvent): void;
/** Tell every connection to refetch. Everybody, because the lost events named their own members. */
resyncAll(): void;
connectionCount(userId: string): number;
};
export function createChannelEventHub(): ChannelEventHub {
const connections = new Map<string, Set<Send>>();
return {
register(userId, send) {
const existing = connections.get(userId) ?? new Set<Send>();
existing.add(send);
connections.set(userId, existing);
return () => {
const remaining = connections.get(userId);
if (!remaining) return;
remaining.delete(send);
// Dropped entirely rather than left empty, so a long-lived process does not accumulate a
// set per person who ever connected.
if (remaining.size === 0) connections.delete(userId);
};
},
deliver(event) {
for (const userId of event.memberIds) {
for (const send of connections.get(userId) ?? []) {
try {
send(JSON.stringify(event));
} catch {
// A connection that cannot be written to is one that is closing. Its own close handler
// detaches it; failing here would deny the event to everybody after it in the set.
}
}
}
},
resyncAll() {
for (const sends of connections.values()) {
for (const send of sends) {
try {
send(RESYNC_PAYLOAD);
} catch {
// Closing, and detached by its own close handler. See `deliver`.
}
}
}
},
connectionCount(userId) {
return connections.get(userId)?.size ?? 0;
},
};
}
export type ChannelActivityListener = { stop: () => Promise<void> };
/**
* Listen for activity announced by any instance, including this one.
*
* On its own connection, because `LISTEN` holds one for the life of the subscription: taken from the
* pool, it would be a connection the rest of the server never gets back.
*/
export async function startChannelActivityListener(
databaseUrl: string,
hub: ChannelEventHub,
): Promise<ChannelActivityListener> {
const connection = postgres(databaseUrl, { max: 1 });
/*
* `onlisten` fires on every establish, reconnects included — the same hook `policy-listener.ts`
* uses to re-read its row. There is no row to re-read here, so the browsers are told to refetch
* instead.
*
* The first establish is skipped so the message means one thing. It has no earlier subscription
* behind it, so nothing can have been missed, and a resync there would say "possibly a gap" — not
* something a client can act on differently.
*/
let subscribed = false;
const resync = () => {
if (!subscribed) {
subscribed = true;
return;
}
hub.resyncAll();
};
await connection.listen(
CHANNEL_ACTIVITY_TOPIC,
(payload) => {
try {
hub.deliver(JSON.parse(payload) as ChannelActivityEvent);
} catch {
// A payload we cannot read is not a reason to tear down the subscription: the roster query
// is still correct, and the next refetch shows whatever this event would have.
}
},
resync,
);
return {
stop: async () => {
await connection.end();
},
};
}