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 {
and,
asc,
desc,
eq,
exists,
inArray,
isNull,
lt,
ne,
or,
sql,
} from "drizzle-orm";
import type { Context, MiddlewareHandler } from "hono";
import { Hono } from "hono";
import {
AgentNotFoundError,
type AgentProfileStore,
} from "../agents/profile-store";
import type { AgentActor, AgentProfile } from "../agents/profile-types";
import { type AuditStore, recordAuditEvent } from "../audit";
import type { AppVariables } from "../auth/guards";
import type { Database } from "../db/client";
import {
agentProfiles,
channelAgents,
channelMemberships,
channels,
intelligenceChannelMappings,
} from "../db/schema";
import { parsePageLimit } from "../paging";
import {
CHANNEL_ACTIVITY_TOPIC,
type ChannelActivityEvent,
type ChannelEventHub,
} from "./events";
import { upgradeWebSocket } from "./socket";
import { oneLine } from "./text";
import type { ThreadIdentity } from "./thread-identity";
import { type ChannelWork, channelWorkDto, workIn } from "./working";
export type AgentChannel = {
id: string;
name: string;
agentIds: string[];
threadId: string;
active: boolean;
/**
* When something was last said here, or null for a conversation nobody has used.
*
* On the channel itself rather than only on the roster summary, because the conversation screen
* needs it: a thread the history store does not know about is an empty NEW conversation when this
* is null and a conversation whose history is unreachable when it is set, and those are different
* things to put on the screen. See the note in `channel-chat.tsx`.
*/
lastMessageAt: Date | null;
};
/** A channel plus the last thing said in it, which is what a roster renders. */
export type ChannelSummary = AgentChannel & {
/** A few words about the conversation, or null. Readers fall back to the channel's name. */
summary: string | null;
lastMessage: string | null;
lastMessageAgentId: string | null;
createdAt: Date;
/** Whether the caller pinned this channel. A pin is per-member, so this is the caller's, only. */
pinned: boolean;
/** When the caller last had this channel open, or null for never. The caller's, only. */
lastReadAt: Date | null;
};
/** What a client that ran an agent reports back about the message it just saw. */
export type ChannelActivity = {
text: string;
/** The agent that said it, or null when a person did. */
agentId: string | null;
at: Date;
};
/** One page of somebody's channels, newest activity first. */
export type ChannelPage = {
channels: ChannelSummary[];
/** Where the next page starts, or null at the end. */
nextCursor: string | null;
};
export type ChannelQuery = { cursor?: string; limit?: number };
/**
* How many channels one page holds.
*
* The sidebar asked for all of them on every render, one row per channel-agent pair, and nothing
* removes a channel: somebody who talks to their Bot daily accumulates thousands, so a query that is
* instant in a demo returns thousands of rows on every page load for every employee, and grows
* monotonically. A page is what a sidebar can show anyway.
*/
const DEFAULT_CHANNEL_PAGE = 50;
/** The most a caller may ask for, so the endpoint cannot be talked back into reading everything. */
const MAX_CHANNEL_PAGE = 200;
/**
* Where a page stopped: every part of the sort, in sort order.
*
* `pinned` leads, because the ordering does: a keyset cursor has to name the whole sort key or the
* next page is selected by a different rule than the page it follows, which serves some channels
* twice and others never. `recency` and `id` are both here for the same reason — two channels can
* share a timestamp.
*/
type ChannelCursor = { pinned: boolean; recency: string; id: string };
/** The shape the encoder writes: UTC, to the millisecond (older cursors) or the microsecond. */
const CURSOR_RECENCY = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?Z$/;
export function encodeChannelCursor(cursor: ChannelCursor): string {
return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
}
/**
* A malformed cursor reads as the first page, which is the honest answer to a stale link.
*
* A cursor minted before `pinned` existed is malformed by this definition, and deliberately: it
* describes a position in an ordering this query no longer has.
*
* `recency` has to be the timestamp the encoder writes, not merely a string: it is cast with
* `::timestamptz` in the page query, so any other string used to reach PostgreSQL and answer 500.
*/
export function decodeChannelCursor(
value: string | undefined,
): ChannelCursor | undefined {
if (!value) return undefined;
try {
const parsed = JSON.parse(
Buffer.from(value, "base64url").toString("utf8"),
) as ChannelCursor;
return typeof parsed?.id === "string" &&
typeof parsed?.recency === "string" &&
CURSOR_RECENCY.test(parsed.recency) &&
!Number.isNaN(Date.parse(parsed.recency)) &&
typeof parsed?.pinned === "boolean"
? parsed
: undefined;
} catch {
return undefined;
}
}
/**
* The roster's sort key, as SQL, in the order it sorts.
*
* Every part descends, which is what lets the cursor be one row comparison rather than a nest of
* ORs: a pin is 1 and no pin is 0, so `desc` puts pinned channels first, and both remaining parts
* already wanted `desc`. Starting a conversation counts as activity — a channel somebody just made
* has nothing said in it yet and is the one they are about to type in, so ordering on the message
* alone would bury it under every channel that has one.
*
* The browser repeats the recency half when the socket patches a row, and lifts pinned rows at
* render; both must agree with this, or the list reorders itself on the next event. See `byRecency`
* in use-channel-events.ts and `pinnedFirst` in app-sidebar.tsx.
*/
const PINNED_RANK = sql`case when ${channelMemberships.pinnedAt} is not null then 1 else 0 end`;
const RECENCY = sql`coalesce(${channels.lastMessageAt}, ${channels.createdAt})`;
const ROSTER_ORDER = [
sql`${PINNED_RANK} desc`,
sql`${RECENCY} desc`,
desc(channels.id),
];
/** The transaction `create` and `direct` share, as the driver hands it to a callback. */
type ChannelTransaction = Parameters<Parameters<Database["transaction"]>[0]>[0];
export type ChannelStore = {
create(actor: AgentActor, agentIds: string[]): Promise<AgentChannel>;
/**
* The one conversation this person has with this Bot alone, made if they have not had one yet.
*
* FOUND BEFORE IT IS MADE, because the callers that want it are called more than once for the
* same pair. A hop delivered to a Bot is retried when the delivery fails, and creating here would
* leave a fresh empty conversation behind for every attempt: the person would open the roster to
* five Knowledge channels, four of them empty, and no way to tell which one holds the answer.
*
* The one it finds is the one the person already talks to that Bot in, which is also where they
* would look for the answer.
*/
direct(actor: AgentActor, agentId: string): Promise<AgentChannel>;
get(actor: AgentActor, channelId: string): Promise<AgentChannel | null>;
list(actor: AgentActor, query?: ChannelQuery): Promise<ChannelPage>;
/** Pin or unpin the caller's own membership. Throws ChannelNotFoundError for a non-member. */
setPinned(
actor: AgentActor,
channelId: string,
pinned: boolean,
): Promise<void>;
/** Stamp the caller's own membership as read now. Throws ChannelNotFoundError for a non-member. */
markRead(actor: AgentActor, channelId: string): Promise<void>;
/**
* Hide the channel for every member. Soft: the row and the thread survive, every read filters.
* Throws ChannelNotFoundError for a non-member and ChannelPackageOwnedError for a channel the
* tenant package defines, which configuration owns rather than any member.
*/
/**
* True when this call deleted the channel; false when it was already deleted. A repeat is a
* no-op, so it announces nothing and its route records nothing.
*/
softDelete(actor: AgentActor, channelId: string): Promise<boolean>;
recordActivity(
actor: AgentActor,
channelId: string,
activity: ChannelActivity,
source?: {
id: string;
/** Enrich this source's preview at the same timestamp only while this text still matches. */
enrichFrom?: string;
},
): Promise<void>;
/**
* Tell a channel's members that a turn started or ended in it, by the thread it runs in.
*
* Keyed by thread because that is all a headless turn knows. A thread that maps to no channel —
* the scratch thread a handoff answers in — resolves to nothing and signals nowhere, which is
* the point of a scratch thread. Announced, never written: `busy` is a moment, not a fact about
* the channel, and a missed one costs a dot until the next real event rather than any data.
*/
signalBusy(threadId: string, busy: boolean): Promise<void>;
/**
* The same signal, from a person's own run, by the channel they are in.
*
* A browser knows exactly when its run starts and stops and which channel it is in, which the
* server cannot see: the runtime does not tell this deployment when a person's turn begins. So
* the browser reports it, and this checks the caller belongs to the channel before announcing —
* the membership check `signalBusy` does not need, because that one is only ever called by the
* server about work it started itself.
*/
signalChannelBusy(
actor: AgentActor,
channelId: string,
busy: boolean,
): Promise<void>;
/**
* Tell a channel's members what it is waiting on now, without saying a turn started or ended.
*
* For the moments the queue moves and no turn does: a hop finished, released for another try, or
* turned into a relay. Every busy signal carries the same list, so this is only for those.
*/
signalWork(threadId: string): Promise<void>;
/**
* What each of these channels is waiting on, for this person: their own thread's hops and their
* own routines. See `workIn` in working.ts.
*/
workIn(
actor: AgentActor,
channels: readonly { id: string; threadId: string }[],
): Promise<Map<string, ChannelWork[]>>;
};
const PRIVATE_AGENT_CHANNEL_DESCRIPTION = "Private agent channel.";
const MAX_CHANNEL_NAME_CODE_POINTS = 120;
const MAX_ACTIVITY_GRAPHEMES = 200;
/** Reduce a message to the one line a roster draws. See `oneLine` for why it is shared. */
function previewOf(text: string) {
return oneLine(text, MAX_ACTIVITY_GRAPHEMES);
}
function channelName(names: string[]) {
const joined = names.join(", ");
const codePoints = Array.from(joined);
if (codePoints.length <= MAX_CHANNEL_NAME_CODE_POINTS) return joined;
return `${codePoints.slice(0, MAX_CHANNEL_NAME_CODE_POINTS - 1).join("")}…`;
}
export function createChannelStore(
database: Database,
profileStore: AgentProfileStore,
threadIdentity: ThreadIdentity,
): ChannelStore {
/**
* Making a channel, on a transaction the caller already holds.
*
* Extracted so `direct` can find-or-create inside ONE transaction. Two of those arriving together
* for the same person and Bot each found nothing and each made a conversation, so that person had
* two Knowledge channels holding two threads, with their answers split between them. Reproduced
* against a real PostgreSQL: it needs no cluster, only two hops delivered at once, which is what a
* Bot asking for several things in one turn produces.
*/
const makeChannel = async (
transaction: ChannelTransaction,
actor: AgentActor,
agentIds: string[],
): Promise<AgentChannel> => {
// Validated on this transaction, not through `profileStore.get`: the read has to share
// the connection this transaction already holds, and has to hold the profile so an agent
// cannot be deleted between passing the check and being linked to the new channel.
//
// Locks are taken in agent-ID order. Two channels selecting the same pair of agents in
// opposite orders would otherwise be able to deadlock against each other.
const profilesById = new Map<string, AgentProfile>();
for (const agentId of [...agentIds].sort()) {
const profile = await profileStore.getWithin(transaction, actor, agentId);
if (!profile) throw new AgentNotFoundError(agentId);
profilesById.set(agentId, profile);
}
const id = `channel_${crypto.randomUUID()}`;
// Minted rather than a bare random id, so the thread says which deployment it belongs to
// in a project that may hold more than one. See thread-identity.ts.
const threadId = threadIdentity.mint();
// Named from the caller's ordering, which is the order the channel presents its agents in.
const name = channelName(
agentIds.map((agentId) => {
const profile = profilesById.get(agentId);
if (!profile) throw new AgentNotFoundError(agentId);
return profile.name;
}),
);
await transaction.insert(channels).values({
id,
name,
description: PRIVATE_AGENT_CHANNEL_DESCRIPTION,
});
await transaction.insert(channelMemberships).values({
channelId: id,
userId: actor.id,
});
await transaction
.insert(channelAgents)
.values(agentIds.map((agentId) => ({ channelId: id, agentId })));
await transaction.insert(intelligenceChannelMappings).values({
userId: actor.id,
channelId: id,
threadId,
});
return { id, name, agentIds, threadId, active: true, lastMessageAt: null };
};
/**
* Tell a channel's members what it is waiting on, and whether a turn just started or ended.
*
* No table write: busy is a moment, and the rows the work list is read from stay the source of
* truth. Just the announcement, carrying the members the same way recordActivity does. The list
* rides on every one of these so a client never merges a delta into what it holds: the newest
* event is the whole answer, and the same answer a reload gets.
*
* THE LIST GOES ONLY TO THE PERSON WHOSE THREAD IT IS. Each member has a thread of their own in
* a channel, and what that thread waits on names the Bots its owner asked. The other members
* hear that a turn started or ended, as they always have, and nothing about whom it asked.
*
* `workAt` is the database's clock just before the list was read. Two announcements for one
* channel can be read on two replicas and delivered in either order, so the browser keeps the
* list with the latest `workAt` rather than the one that happened to arrive last.
*/
const announceWork = async (
channelId: string,
thread: { threadId: string; userId: string } | null,
busy?: boolean,
): Promise<void> => {
const members = await database
.select({ userId: channelMemberships.userId })
.from(channelMemberships)
.where(eq(channelMemberships.channelId, channelId));
if (members.length === 0) return;
const notify = (event: ChannelActivityEvent) =>
database.execute(
sql`select pg_notify(${CHANNEL_ACTIVITY_TOPIC}, ${JSON.stringify(event)})`,
);
const base = {
channelId,
lastMessage: null,
lastMessageAt: null,
lastMessageAgentId: null,
...(busy === undefined ? {} : { busy }),
};
const owner =
thread && members.some((member) => member.userId === thread.userId)
? thread
: null;
const others = members
.map((member) => member.userId)
.filter((userId) => userId !== owner?.userId);
if (owner) {
// Fixed-width UTC to the microsecond, so two stamps compare as strings.
const [stamp] = await database.execute<{ at: string }>(
sql`select to_char(clock_timestamp() at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') as at`,
);
const work =
(
await workIn(database, [
{ id: channelId, threadId: owner.threadId, userId: owner.userId },
])
).get(channelId) ?? [];
await notify({
...base,
memberIds: [owner.userId],
work: work.map(channelWorkDto),
...(stamp ? { workAt: stamp.at } : {}),
});
}
// A settle with no turn moving has nothing to tell anybody but the thread's owner.
if (busy !== undefined && others.length > 0)
await notify({ ...base, memberIds: others });
};
const store: ChannelStore = {
create(actor, agentIds) {
return database.transaction(
async (transaction) => makeChannel(transaction, actor, agentIds),
{ isolationLevel: "read committed" },
);
},
async direct(actor, agentId) {
const found = await database.transaction(
async (transaction) => {
/*
* ONE AT A TIME PER PERSON AND BOT, across every replica.
*
* Looking and then making is not find-or-create: two hops delivered at the same moment
* each saw nothing and each made a conversation, and that person ended up with two
* Knowledge channels holding two threads, with the answers split between them. A Bot
* asking for several things in one turn produces exactly that, so it needs no cluster and
* no unusual timing.
*
* An advisory lock rather than a unique constraint, because what has to be unique is not a
* column: it is "this person's channel whose whole roster is this one Bot", which is a
* count over another table. The lock is held for the transaction and taken on the pair, so
* nothing else on the channel table waits behind it.
*/
await transaction.execute(
sql`select pg_advisory_xact_lock(hashtext(${`channel:direct:${actor.id}:${agentId}`}))`,
);
const [existing] = await transaction
.select({ id: channels.id })
.from(channels)
.innerJoin(
channelMemberships,
and(
eq(channelMemberships.channelId, channels.id),
eq(channelMemberships.userId, actor.id),
),
)
.innerJoin(
channelAgents,
and(
eq(channelAgents.channelId, channels.id),
eq(channelAgents.agentId, agentId),
),
)
/*
* A channel of this person's whose whole roster is this one Bot. The count is what makes
* it "alone": a channel holding this Bot and another one would match an agent test on
* its own, and delivering into it would put the answer in front of a Bot nobody asked.
*/
.where(
and(
isNull(channels.deletedAt),
sql`(select count(*) from ${channelAgents} where ${channelAgents.channelId} = ${channels.id}) = 1`,
),
)
.orderBy(...ROSTER_ORDER)
.limit(1);
return existing
? existing.id
: await makeChannel(transaction, actor, [agentId]);
},
{ isolationLevel: "read committed" },
);
if (typeof found !== "string") return found;
const channel = await store.get(actor, found);
// Null only if it was deleted between the two reads, which is a reason to make a new one
// rather than to fail: the caller asked for a conversation, not for that row.
return channel ?? store.create(actor, [agentId]);
},
async get(actor, channelId) {
const rows = await database
.select({
id: channels.id,
name: channels.name,
agentId: channelAgents.agentId,
threadId: intelligenceChannelMappings.threadId,
lastMessageAt: channels.lastMessageAt,
deletedAt: agentProfiles.deletedAt,
})
.from(channels)
.innerJoin(
channelMemberships,
and(
eq(channelMemberships.channelId, channels.id),
eq(channelMemberships.userId, actor.id),
),
)
.innerJoin(
intelligenceChannelMappings,
and(
eq(intelligenceChannelMappings.channelId, channels.id),
eq(intelligenceChannelMappings.userId, actor.id),
),
)
.innerJoin(channelAgents, eq(channelAgents.channelId, channels.id))
.innerJoin(
agentProfiles,
eq(agentProfiles.agentId, channelAgents.agentId),
)
.where(and(eq(channels.id, channelId), isNull(channels.deletedAt)))
.orderBy(asc(channelAgents.agentId));
const first = rows[0];
if (!first) return null;
return {
id: first.id,
name: first.name,
agentIds: rows.map((row) => row.agentId),
threadId: first.threadId,
active: rows.every((row) => row.deletedAt === null),
lastMessageAt: first.lastMessageAt,
};
},
async list(actor, query = {}) {
const limit = Math.min(
Math.max(query.limit ?? DEFAULT_CHANNEL_PAGE, 1),
MAX_CHANNEL_PAGE,
);
const cursor = decodeChannelCursor(query.cursor);
/*
* The page of channels is chosen first, and the agents are joined to that page.
*
* The row set below is one row per channel-agent pair, so a limit on rows would cut a channel
* in half: its second Bot would arrive on the next page as a separate entry with the same id.
* Limiting the channels and then joining keeps a channel whole whatever it holds.
*/
const page = await database
.select({
id: channels.id,
/*
* To the microsecond, as text, for the cursor only: the audit reader's fix, for the same
* fault. The column keeps microseconds and a `Date` keeps milliseconds, so a cursor made
* from a `Date` named a moment just before its own row, and any channel later in that
* millisecond compared as newer than the cursor and was on no page at all.
*/
recency: sql<string>`to_char(${RECENCY} at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`,
pinned: sql<boolean>`${channelMemberships.pinnedAt} is not null`,
})
.from(channels)
.innerJoin(
channelMemberships,
and(
eq(channelMemberships.channelId, channels.id),
eq(channelMemberships.userId, actor.id),
),
)
.where(
and(
isNull(channels.deletedAt),
// One row comparison over the whole sort key, which only reads as "everything after the
// cursor" because every part of that key descends. See ROSTER_ORDER.
cursor
? sql`(${PINNED_RANK}, ${RECENCY}, ${channels.id}) < (${cursor.pinned ? 1 : 0}::int, ${cursor.recency}::timestamptz, ${cursor.id})`
: undefined,
),
)
.orderBy(...ROSTER_ORDER)
// One more than asked for, so "is there another page" needs no second count query.
.limit(limit + 1);
const wanted = page.slice(0, limit);
const last = wanted.at(-1);
const nextCursor =
page.length > limit && last
? encodeChannelCursor({
pinned: last.pinned,
recency: last.recency,
id: last.id,
})
: null;
if (wanted.length === 0) return { channels: [], nextCursor: null };
const rows = await database
.select({
id: channels.id,
name: channels.name,
agentId: channelAgents.agentId,
threadId: intelligenceChannelMappings.threadId,
deletedAt: agentProfiles.deletedAt,
channelSummary: channels.summary,
lastMessage: channels.lastMessage,
lastMessageAt: channels.lastMessageAt,
lastMessageAgentId: channels.lastMessageAgentId,
createdAt: channels.createdAt,
pinnedAt: channelMemberships.pinnedAt,
lastReadAt: channelMemberships.lastReadAt,
})
.from(channels)
.innerJoin(
channelMemberships,
and(
eq(channelMemberships.channelId, channels.id),
eq(channelMemberships.userId, actor.id),
),
)
.innerJoin(
intelligenceChannelMappings,
and(
eq(intelligenceChannelMappings.channelId, channels.id),
eq(intelligenceChannelMappings.userId, actor.id),
),
)
.innerJoin(channelAgents, eq(channelAgents.channelId, channels.id))
.innerJoin(
agentProfiles,
eq(agentProfiles.agentId, channelAgents.agentId),
)
.where(
and(
inArray(
channels.id,
wanted.map((row) => row.id),
),
// Repeated, not inherited from the query that chose the page: these are two statements
// on two snapshots, so a delete that commits between them would otherwise hand back a
// channel this person can no longer see.
isNull(channels.deletedAt),
),
)
// The same order the page was chosen in, since the rows below are read in order.
.orderBy(...ROSTER_ORDER, asc(channelAgents.agentId));
// One row per channel-agent pair; the ordering above keeps each channel's rows together and
// its agents in the same lexicographic order `get` returns.
const summaries = new Map<string, ChannelSummary>();
for (const row of rows) {
const summary = summaries.get(row.id);
if (summary) {
summary.agentIds.push(row.agentId);
summary.active &&= row.deletedAt === null;
continue;
}
summaries.set(row.id, {
id: row.id,
name: row.name,
agentIds: [row.agentId],
threadId: row.threadId,
active: row.deletedAt === null,
summary: row.channelSummary,
lastMessage: row.lastMessage,
lastMessageAt: row.lastMessageAt,
lastMessageAgentId: row.lastMessageAgentId,
createdAt: row.createdAt,
pinned: row.pinnedAt !== null,
lastReadAt: row.lastReadAt,
});
}
return { channels: [...summaries.values()], nextCursor };
},
async setPinned(actor, channelId, pinned) {
await database.transaction(
async (transaction) => {
const updated = await transaction
.update(channelMemberships)
.set({ pinnedAt: pinned ? new Date() : null })
.where(
and(
eq(channelMemberships.channelId, channelId),
eq(channelMemberships.userId, actor.id),
// A deleted channel is not there to pin. Without this, pinning one succeeds and
// announces, and the announcement sends this person's tabs to refetch a roster that
// cannot show the row. `get` and `list` filter the same way.
exists(
transaction
.select({ one: sql`1` })
.from(channels)
.where(
and(
eq(channels.id, channelId),
isNull(channels.deletedAt),
),
),
),
),
)
.returning({ channelId: channelMemberships.channelId });
// Not a member, no such channel, or a deleted one: the same answer every way, matching
// recordActivity and `get`.
if (updated.length === 0) throw new ChannelNotFoundError(channelId);
/*
* Announced to this member alone.
*
* A pin is a fact about one membership row, so `memberIds` holds the person who made it
* and nobody else. The hub delivers by that list, which is what carries the pin across
* this person's own tabs and replicas without putting it on anybody else's roster.
*/
const event: ChannelActivityEvent = {
channelId,
memberIds: [actor.id],
lastMessage: null,
lastMessageAt: null,
lastMessageAgentId: null,
pinned,
};
await transaction.execute(
sql`select pg_notify(${CHANNEL_ACTIVITY_TOPIC}, ${JSON.stringify(event)})`,
);
},
{ isolationLevel: "read committed" },
);
},
async markRead(actor, channelId) {
const updated = await database
.update(channelMemberships)
.set({
/*
* The later of this clock and the channel's own last-message stamp. last_message_at is
* written from the reporting browser's clock and is not bounded; a marker stamped
* plainly "now" by a server running behind it would leave the row reading as unseen for
* every member, re-lighting the dot on each refetch until wall clock catches up.
*/
lastReadAt: sql`greatest(now(), coalesce((select ${channels.lastMessageAt} from ${channels} where ${channels.id} = ${channelMemberships.channelId}), now()))`,
})
.where(
and(
eq(channelMemberships.channelId, channelId),
eq(channelMemberships.userId, actor.id),
// A deleted channel is not there to read. The same guard `setPinned` carries, for the
// same reason: the row is gone from every roster, so nothing about it is markable.
exists(
database
.select({ one: sql`1` })
.from(channels)
.where(
and(eq(channels.id, channelId), isNull(channels.deletedAt)),
),
),
),
)
.returning({ channelId: channelMemberships.channelId });
// Not a member, or no such channel: the same answer either way, matching setPinned.
if (updated.length === 0) throw new ChannelNotFoundError(channelId);
},
async softDelete(actor, channelId) {
return await database.transaction(
async (transaction) => {
const [row] = await transaction
.select({ packageId: channels.packageId })
.from(channels)
.innerJoin(
channelMemberships,
and(
eq(channelMemberships.channelId, channels.id),
eq(channelMemberships.userId, actor.id),
),
)
.where(eq(channels.id, channelId));
// Not a member, or no such channel: the same answer either way.
if (!row) throw new ChannelNotFoundError(channelId);
// Package channels are configuration; the sync that wrote them owns them.
if (row.packageId !== null) {
throw new ChannelPackageOwnedError(channelId);
}
// The guard on deletedAt is what makes a repeat call a no-op rather than a new stamp.
const stamped = await transaction
.update(channels)
.set({ deletedAt: new Date(), updatedAt: new Date() })
.where(and(eq(channels.id, channelId), isNull(channels.deletedAt)))
.returning({ id: channels.id });
/*
* And the rest of the no-op: a repeat changed nothing, so nothing is announced. Without
* this, every repeat told every member again, and the route wrote another
* `channel.deleted` row to an append-only trail for a deletion that had not happened.
*/
if (stamped.length === 0) return false;
// Read on this transaction, so the members told are the ones the channel had when it was
// hidden. Soft leaves the membership rows in place, so this reads the same list a repeat
// call would.
const members = await transaction
.select({ userId: channelMemberships.userId })
.from(channelMemberships)
.where(eq(channelMemberships.channelId, channelId));
/*
* Announced inside the transaction, so it is delivered on commit and a refused delete —
* a channel the package owns, or one the caller is not in — announces nothing at all.
*
* Every member is told, because the deletion hides the channel for all of them: without
* this, a second tab and a second replica keep rendering a row whose channel no longer
* resolves until something else makes them refetch.
*/
const event: ChannelActivityEvent = {
channelId,
memberIds: members.map((member) => member.userId),
lastMessage: null,
lastMessageAt: null,
lastMessageAgentId: null,
deleted: true,
};
await transaction.execute(
sql`select pg_notify(${CHANNEL_ACTIVITY_TOPIC}, ${JSON.stringify(event)})`,
);
return true;
},
{ isolationLevel: "read committed" },
);
},
recordActivity(actor, channelId, activity, source) {
return database.transaction(
async (transaction) => {
const [membership] = await transaction
.select({ channelId: channelMemberships.channelId })
.from(channelMemberships)
// Joined rather than checked on the membership alone, so a deleted channel is refused
// too. `get` and `list` filter on `deleted_at`, so without this a client holding a stale
// roster row can bump `last_message` on a channel nobody can see and announce it to
// every member, each of whom refetches their roster for an invisible row.
.innerJoin(
channels,
and(
eq(channels.id, channelMemberships.channelId),
isNull(channels.deletedAt),
),
)
.where(
and(
eq(channelMemberships.channelId, channelId),
eq(channelMemberships.userId, actor.id),
),
);
// Not a member, no such channel, or a deleted one: the same answer every way, so belonging
// to a channel is not something an outsider can probe for.
if (!membership) throw new ChannelNotFoundError(channelId);
if (activity.agentId !== null) {
const [linked] = await transaction
.select({ agentId: channelAgents.agentId })
.from(channelAgents)
.where(
and(
eq(channelAgents.channelId, channelId),
eq(channelAgents.agentId, activity.agentId),
),
);
if (!linked) throw new AgentNotFoundError(activity.agentId);
}
// A person's message and the agent's reply are reported separately, so they can arrive out
// of order. Only move forwards, except to enrich the same source's placeholder.
// The source, timestamp and text comparison is atomic across server replicas.
const lastMessage = previewOf(activity.text);
const applied = await transaction
.update(channels)
.set({
lastMessage,
lastMessageSourceId: source?.id ?? null,
lastMessageAt: activity.at,
lastMessageAgentId: activity.agentId,
updatedAt: new Date(),
})
.where(
and(
eq(channels.id, channelId),
or(
isNull(channels.lastMessageAt),
lt(channels.lastMessageAt, activity.at),
source?.enrichFrom !== undefined
? and(
eq(channels.lastMessageAt, activity.at),
eq(channels.lastMessageSourceId, source.id),
eq(channels.lastMessage, previewOf(source.enrichFrom)),
ne(channels.lastMessage, lastMessage),
activity.agentId === null
? isNull(channels.lastMessageAgentId)
: eq(channels.lastMessageAgentId, activity.agentId),
)
: undefined,
),
),
)
.returning({ id: channels.id });
// Nothing changed, so there is nothing to announce: a stale report is not news.
if (applied.length === 0) return;
const members = await transaction
.select({ userId: channelMemberships.userId })
.from(channelMemberships)
.where(eq(channelMemberships.channelId, channelId));
// Announced inside the transaction, so it is delivered on commit and a write that rolls
// back is never announced. The payload carries the members because the writer has already
// resolved them; NOTIFY caps at 8000 bytes, which a 200-character preview leaves room in.
const event: ChannelActivityEvent = {
channelId,
memberIds: members.map((member) => member.userId),
lastMessage,
lastMessageAt: activity.at.toISOString(),
lastMessageAgentId: activity.agentId,
};
await transaction.execute(
sql`select pg_notify(${CHANNEL_ACTIVITY_TOPIC}, ${JSON.stringify(event)})`,
);
},
{ isolationLevel: "read committed" },
);
},
async signalBusy(threadId, busy) {
// The channel this thread is shown in, if any. A scratch thread maps to nothing, so a hop
// running there signals nowhere and the branch below returns without announcing.
const [mapped] = await database
.select({
channelId: intelligenceChannelMappings.channelId,
userId: intelligenceChannelMappings.userId,
})
.from(intelligenceChannelMappings)
.where(eq(intelligenceChannelMappings.threadId, threadId))
.limit(1);
if (!mapped) return;
await announceWork(
mapped.channelId,
{ threadId, userId: mapped.userId },
busy,
);
},
async signalWork(threadId) {
const [mapped] = await database
.select({
channelId: intelligenceChannelMappings.channelId,
userId: intelligenceChannelMappings.userId,
})
.from(intelligenceChannelMappings)
.where(eq(intelligenceChannelMappings.threadId, threadId))
.limit(1);
if (!mapped) return;
await announceWork(mapped.channelId, { threadId, userId: mapped.userId });
},
async signalChannelBusy(actor, channelId, busy) {
const [membership] = await database
.select({
userId: channelMemberships.userId,
threadId: intelligenceChannelMappings.threadId,
})
.from(channelMemberships)
.innerJoin(
channels,
and(
eq(channels.id, channelMemberships.channelId),
isNull(channels.deletedAt),
),
)
// The caller's own thread for the channel, which is the one their hops are offered from.
.leftJoin(
intelligenceChannelMappings,
and(
eq(
intelligenceChannelMappings.channelId,
channelMemberships.channelId,
),
eq(intelligenceChannelMappings.userId, channelMemberships.userId),
),
)
.where(
and(
eq(channelMemberships.channelId, channelId),
eq(channelMemberships.userId, actor.id),
),
)
.limit(1);
// Not a member, no such channel, or a deleted one: the same refusal every way, so belonging
// to a channel is not something an outsider can probe for.
if (!membership) throw new ChannelNotFoundError(channelId);
await announceWork(
channelId,
membership.threadId
? { threadId: membership.threadId, userId: membership.userId }
: null,
busy,
);
},
workIn: (actor, list) =>
workIn(
database,
list.map((channel) => ({ ...channel, userId: actor.id })),
),
};
return store;
}
export class ChannelNotFoundError extends Error {
constructor(id: string) {
super(`Channel ${id} was not found.`);
this.name = "ChannelNotFoundError";
}
}
export class ChannelPackageOwnedError extends Error {
constructor(id: string) {
super(`Channel ${id} is defined by the deployment package.`);
this.name = "ChannelPackageOwnedError";
}
}
type ChannelInputParseResult =
| { ok: true; value: { agentIds: string[] } }
| { ok: false; error: string };
type ChannelInputObject = { agentIds?: unknown };
export function parseChannelInput(input: unknown): ChannelInputParseResult {
if (!isChannelInputObject(input)) {
return { ok: false, error: "Channel input must be a JSON object." };
}
if (!Array.isArray(input.agentIds) || input.agentIds.length === 0) {
return { ok: false, error: "Agent IDs must be a non-empty array." };
}
const agentIds: string[] = [];
for (const agentId of input.agentIds) {
if (typeof agentId !== "string" || agentId.trim().length === 0) {
return { ok: false, error: "Agent IDs must be non-empty strings." };
}
agentIds.push(agentId.trim());
}
if (new Set(agentIds).size !== agentIds.length) {
return { ok: false, error: "Agent IDs must be unique." };
}
return { ok: true, value: { agentIds: agentIds.sort() } };
}
function isChannelInputObject(input: unknown): input is ChannelInputObject {
return typeof input === "object" && input !== null && !Array.isArray(input);
}
type ActivityInputParseResult =
| { ok: true; value: ChannelActivity }
| { ok: false; error: string };
/**
* Parse a reported message.
*
* `at` comes from the client that saw the message, because only it knows when the message arrived,
* and it may say when, but not later than now. The store compares it against what is stored and
* only ever moves forwards, and that guard is shared with every other clock in the deployment:
* the routine runner's, a relayed handoff answer's, every other member's browser. A browser whose
* clock ran seven minutes ahead used to stamp the row seven minutes into the future, and it was
* not that report that got lost — every correct one for the next seven minutes was, silently: a
* routine's reply landed in the thread and never on the roster. Clamped rather than refused,
* because clocks are a little ahead all the time and a report a second early is still the report.
* A stamp in the past is kept as it is, so a person's message and the reply, reported separately
* by the same clock, still land in the order that clock saw them.
*/
export function parseActivityInput(
input: unknown,
/** The server's own clock, injectable so a test can be about a specific gap. */
now: Date = new Date(),
): ActivityInputParseResult {
if (!isChannelInputObject(input)) {
return { ok: false, error: "Activity must be a JSON object." };
}
const object = input as { text?: unknown; agentId?: unknown; at?: unknown };
if (typeof object.text !== "string" || object.text.trim().length === 0) {
return { ok: false, error: "Text is required." };
}
if (object.agentId !== null && typeof object.agentId !== "string") {
return { ok: false, error: "Agent ID must be a string or null." };
}
if (
typeof object.agentId === "string" &&
object.agentId.trim().length === 0
) {
return { ok: false, error: "Agent ID must be a string or null." };
}
if (typeof object.at !== "string") {
return { ok: false, error: "Timestamp is required." };
}
const reported = new Date(object.at);
if (Number.isNaN(reported.getTime())) {
return { ok: false, error: "Timestamp must be an ISO-8601 date." };
}
const at = reported.getTime() > now.getTime() ? now : reported;
return {
ok: true,
value: {
agentId:
typeof object.agentId === "string" ? object.agentId.trim() : null,
at,
text: object.text,
},
};
}
export function createChannelRoutes(
store: ChannelStore,
requireUser: MiddlewareHandler<{ Variables: AppVariables }>,
/** Absent in tests and wherever live updates are not wanted; the routes still work without it. */
events?: ChannelEventHub,
/** Where a channel's removal is written. Absent in tests that do not care about the trail. */
auditStore?: AuditStore,
) {
const routes = new Hono<{ Variables: AppVariables }>();
/**
* Write the one audit row this file ever writes, tolerantly.
*
* Mirrors `record` in agents/routes.ts: never fatal, because the channel is already hidden and the
* caller has already been told so by the time this runs. A trail that is briefly unavailable is
* not a reason to report a failure that did not happen.
*
* Reached only after `softDelete` resolves, so a refused delete — a channel the package owns, or
* one the caller is not in — writes nothing. The trail records acts, not attempts.
*/
const recordDeleted = async (
context: Context<{ Variables: AppVariables }>,
channelId: string,
): Promise<void> => {
if (!auditStore) return;
const actor = context.var.actor;
try {
await recordAuditEvent(auditStore, {
eventType: "channel.deleted",
targetType: "channel",
targetId: channelId,
/*
* Attributed, including in single-user mode.
*
* The other audited surfaces drop this id when the actor is the local development one, on
* the grounds that `audit_events.actor_user_id` has a foreign key into `users` that it would
* violate. It has no foreign key, and `initializeDevActorUser` writes that row at start-up
* anyway, so neither half of the reason holds. It matters here more than most: single-user
* is the mode `.env.example` ships switched on, so an unattributed row is what a fork sees
* by default, and "somebody deleted this conversation" is the whole point of the row.
*/
actorUserId: actor.id,
// Named rather than implied: the channel row and its thread are still there, and a later
// hard delete would be a different fact about the same channel.
payload: { mechanism: "soft" },
});
} catch (error) {
console.error(
JSON.stringify({
type: "channel-audit-write-failed",
eventType: "channel.deleted",
channelId,
error: String(error),
}),
);
}
};
// Before `/:channelId`, or "events" is read as a channel id.
if (events) {
routes.get(
"/events",
requireUser,
upgradeWebSocket((context) => {
// Resolved at upgrade, not per message: the connection belongs to whoever authenticated it,
// and nothing it later sends can change that.
const { id: userId } = context.var.actor;
let detach = () => {};
return {
onOpen: (_event, ws) => {
detach = events.register(userId, (payload) => ws.send(payload));
},
onClose: () => detach(),
onError: () => detach(),
};
}),
);
}
routes.post("/", requireUser, async (context) => {
const parsed = parseChannelInput(
await context.req.json().catch(() => null),
);
if (!parsed.ok) return context.json({ error: parsed.error }, 400);
try {
const channel = await store.create(
context.var.actor,
parsed.value.agentIds,
);
return context.json({ channel: channelDto(channel) }, 201);
} catch (error) {
return mapStoreError(context, error);
}
});
routes.get("/", requireUser, async (context) => {
try {
const url = new URL(context.req.url);
/*
* Parsed strictly, not coerced: `Number.parseInt` reads `"12abc"` as 12 and `"3.9"`
* as 3, so a typo silently returned the wrong page. A run of digits is clamped into
* range like the store already does; anything else is a 400 naming the parameter.
*/
const parsed = parsePageLimit(
url.searchParams.get("limit"),
MAX_CHANNEL_PAGE,
);
if (!parsed.ok) return context.json({ error: parsed.error }, 400);
const page = await store.list(context.var.actor, {
...(url.searchParams.get("cursor")
? { cursor: url.searchParams.get("cursor") as string }
: {}),
...(parsed.limit !== undefined ? { limit: parsed.limit } : {}),
});
/*
* What each row is waiting on, read with the page rather than left to the socket. A busy
* flag that only ever arrived as an event was gone on every reload, so a conversation a Bot
* was still answering in looked finished to anybody who refreshed.
*/
const work = await store.workIn(context.var.actor, page.channels);
return context.json({
channels: page.channels.map((channel) =>
channelSummaryDto(channel, work.get(channel.id) ?? []),
),
nextCursor: page.nextCursor,
});
} catch (error) {
return mapStoreError(context, error);
}
});
routes.post("/:channelId/activity", requireUser, async (context) => {
const parsed = parseActivityInput(
await context.req.json().catch(() => null),
);
if (!parsed.ok) return context.json({ error: parsed.error }, 400);
// A whitespace channel id would reach the store and answer 500 on some backends instead of
// a 400 for a malformed call.
const channelId = context.req.param("channelId");
if (!channelId.trim()) {
return context.json({ error: "A channel id is required." }, 400);
}
try {
await store.recordActivity(context.var.actor, channelId, parsed.value);
return context.body(null, 204);
} catch (error) {
return mapStoreError(context, error);
}
});
routes.post("/:channelId/busy", requireUser, async (context) => {
const body = (await context.req.json().catch(() => null)) as {
busy?: unknown;
} | null;
if (typeof body?.busy !== "boolean") {
return context.json({ error: "busy must be true or false" }, 400);
}
if (!context.req.param("channelId").trim()) {
return context.json({ error: "A channel id is required." }, 400);
}
try {
await store.signalChannelBusy(
context.var.actor,
context.req.param("channelId"),
body.busy,
);
return context.body(null, 204);
} catch (error) {
return mapStoreError(context, error);
}
});
routes.put("/:channelId/pin", requireUser, async (context) => {
const body = await context.req.json().catch(() => null);
if (!isChannelInputObject(body)) {
return context.json({ error: "Pin input must be a JSON object." }, 400);
}
const { pinned } = body as { pinned?: unknown };
if (typeof pinned !== "boolean") {
return context.json({ error: "Pinned must be true or false." }, 400);
}
try {
await store.setPinned(
context.var.actor,
context.req.param("channelId"),
pinned,
);
return context.json({ pinned });
} catch (error) {
return mapStoreError(context, error);
}
});
routes.put("/:channelId/read", requireUser, async (context) => {
try {
await store.markRead(context.var.actor, context.req.param("channelId"));
return context.body(null, 204);
} catch (error) {
return mapStoreError(context, error);
}
});
routes.delete("/:channelId", requireUser, async (context) => {
const channelId = context.req.param("channelId");
try {
const deleted = await store.softDelete(context.var.actor, channelId);
// A repeat is still 204, but it deleted nothing, and the trail records acts, not attempts.
if (deleted !== false) await recordDeleted(context, channelId);
return context.body(null, 204);
} catch (error) {
return mapStoreError(context, error);
}
});
routes.get("/:channelId", requireUser, async (context) => {
try {
const channel = await store.get(
context.var.actor,
context.req.param("channelId"),
);
if (!channel) {
return context.json({ error: "Couldn't find that conversation." }, 404);
}
const work = await store.workIn(context.var.actor, [channel]);
return context.json({
channel: {
...channelDto(channel),
work: (work.get(channel.id) ?? []).map(channelWorkDto),
},
});
} catch (error) {
return mapStoreError(context, error);
}
});
return routes;
}
/** A channel as it goes over the wire: the same shape, with the date serialised. */
type ChannelWire = Omit<AgentChannel, "lastMessageAt"> & {
lastMessageAt: string | null;
};
function channelDto(channel: AgentChannel): ChannelWire {
return {
id: channel.id,
name: channel.name,
agentIds: channel.agentIds,
threadId: channel.threadId,
active: channel.active,
// ISO-8601 so the browser gets a string it can compare, like the roster's copy.
lastMessageAt: channel.lastMessageAt?.toISOString() ?? null,
};
}
function channelSummaryDto(
channel: ChannelSummary,
work: readonly ChannelWork[],
) {
return {
...channelDto(channel),
summary: channel.summary,
lastMessage: channel.lastMessage,
lastMessageAgentId: channel.lastMessageAgentId,
createdAt: channel.createdAt.toISOString(),
pinned: channel.pinned,
// Serialised as ISO-8601 like lastMessageAt, so the browser can compare the two as strings.
lastReadAt: channel.lastReadAt?.toISOString() ?? null,
work: work.map(channelWorkDto),
/*
* Only ever true from here. A person's own run is not on any row this can read, so a roster
* that said false would put out the dot another tab's run had just lit.
*/
...(work.length > 0 ? { busy: true } : {}),
};
}
function mapStoreError(context: Context, error: unknown): Response {
if (error instanceof AgentNotFoundError) {
return context.json({ error: "Couldn't find that Bot." }, 404);
}
if (error instanceof ChannelNotFoundError) {
return context.json({ error: "Couldn't find that conversation." }, 404);
}
if (error instanceof ChannelPackageOwnedError) {
return context.json(
{
error: "This conversation is built in and can't be deleted.",
},
409,
);
}
throw error;
}