Skip to content

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.

53.6 KB
Raw Blame
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;
}