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.

25.7 KB
Raw Blame
import type { Attachment } from "@copilotkit/react-core/v2";
import { MAX_ATTACHMENTS_PER_MESSAGE } from "@/lib/channels/attachments";
import type { ComposerDraft } from "./draft";

/**
 * What happens to a message typed while the Bot already has the turn.
 *
 * The composer used to refuse it. Enter did nothing, the words stayed in the box, and a person
 * watching their coworker head off in the wrong direction had two options: stop the turn and start
 * again, losing whatever it had already done, or wait for it to finish being wrong. Neither is the
 * thing they wanted, which was to say "no, the other one" while it was working and have that land.
 *
 * So a message typed mid-turn is parked rather than dropped, and everything parked runs as ONE
 * follow-up turn when the current one settles. One turn and not one per message, because three
 * quick corrections are usually one correction typed in three breaths: replaying them separately
 * makes the Bot answer the first, act on it, and only then read the sentence saying not to.
 *
 * Settling is not the same as succeeding. The drain is keyed on the turn ENDING and never asks how
 * it ended, which is what makes Stop a way of steering rather than a way of giving up: park a
 * correction, press Stop, and the correction is what runs next. Nothing here special-cases the stop
 * button, and that is the point — a path with its own branch is a path that can be forgotten.
 *
 * THE QUEUE IS MEMORY IN ONE MOUNT AND NOTHING HERE PRETENDS OTHERWISE. The turn is driven from the
 * browser, so the browser is the only place that knows one is in flight, and this state lives and
 * dies with the component holding it. A reload loses the intent to run these words later, and so
 * does walking to another channel: the channel view is keyed on the channel, so switching unmounts
 * the conversation and takes anything parked in it with it, after the person has watched their
 * words land on screen. Neither is worth a persistence layer for words that only mean anything
 * inside a turn that is already over by the time you come back, but both are worth saying out loud.
 * The words are the person's own and sit on screen for as long as they wait, so nothing is being
 * kept from anybody; but a queue is not an outbox and must not be read as one. It is drawn only
 * while a turn is in flight, so a reload finds no queue and shows none, which is better than a list
 * of messages quietly promising to run and never running.
 *
 * A DRAIN THAT DOES NOT LAND PUTS EVERYTHING BACK. Settling is keyed on the turn ending, not on the
 * turn succeeding, and the same is true one level down: the send the drain starts can fail, and for
 * a while what that cost was the whole queue. The messages were gone — emptied to build the draft —
 * and the files under them were deleted outright, while the transcript went on showing the message
 * the failed run had already added to it. So a run built out of this queue that never becomes a
 * message hands its messages back, whole, through `restoreIfRunFails`; they are parked again, they
 * go out with the next turn, and the only thing that deletes their rows is somebody removing one.
 * The retry waits for a turn somebody asks for rather than going again on its own — see
 * `conversation-view.tsx` — because a queue that re-sent itself would spin against a server that is
 * refusing every request.
 *
 * THE FILES UNDER THOSE WORDS ARE NOT COVERED BY THAT PARAGRAPH, and reading them into it was a
 * leak. Words a person watched land on screen can be retyped; a staged attachment is a row on the
 * server that the parked entry holds the only reference to, and letting it die with the mount left
 * it sitting with `attachedAt IS NULL` until the next day's sweep. So the mount going away releases
 * them — see `conversation-view.tsx`'s teardown, which walks the queue on the way out for exactly
 * this. A tab CLOSING is still the sweeper's, and honestly so: nothing in a page that is going can
 * be relied on to finish a request.
 */

/** One message waiting for the Bot to finish, in the words the person typed. */
export type QueuedMessage = {
  /**
   * Minted by the caller, because taking one back needs a handle that survives the list changing
   * around it and the text will not do: two identical corrections are two entries.
   */
  id: string;
  text: string;
  /**
   * The `/` chips that were in it, so a skill invoked mid-turn still applies when the message
   * eventually runs rather than being silently dropped on the way through the queue.
   */
  commandIds: string[];
  /**
   * Whatever was staged on the draft when it got parked, so a file somebody attached before the
   * Bot was ready still applies when the message eventually runs.
   */
  attachments: Attachment[];
};

export type QueueAction =
  /**
   * Somebody pressed send.
   *
   * `busy` is supplied rather than worked out here. The composer is the only thing holding both
   * halves of that answer — the parent's `pending` and its own send that has not resolved — and a
   * second opinion computed somewhere else would disagree with it exactly during the moment between
   * a send starting and the agent reporting itself as running, which is precisely when somebody
   * typing fast needs the answer to be right.
   */
  | { type: "submit"; id: string; draft: ComposerDraft; busy: boolean }
  /** The turn is over, however it ended: finished, failed, or stopped. */
  | { type: "settle" }
  /**
   * A RUN THIS QUEUE EMPTIED ITSELF TO BUILD NEVER BECAME A MESSAGE. Put its messages back.
   *
   * The caller supplies `restoreIfRunFails` from the transition that emptied the queue — see the
   * field for why that list, and not `run.attachments`, is the honest one. They go back at the
   * FRONT: they were typed before anything that has parked since, and the whole reason this queue
   * exists is that a correction must not be read after the sentence correcting it.
   *
   * It produces no run of its own. A failed send that immediately re-sent itself would spin against
   * a server that is down, so restoring is where this stops and the next turn is what carries them;
   * `conversation-view.tsx` holds the drain back until one starts.
   */
  | { type: "restore"; messages: readonly QueuedMessage[] }
  /** Second thoughts, before it has run. */
  | { type: "remove"; id: string };

export type QueueTransition = {
  /** The queue afterwards. The same array when nothing moved, so a render can be skipped. */
  queue: readonly QueuedMessage[];
  /** A turn to start now, or null when there is nothing to run. */
  run: ComposerDraft | null;
  /**
   * EVERYTHING THIS TRANSITION LET GO OF: rows that were staged server-side and that nothing on
   * any screen points at any more, in the order they were parked. Empty on a transition that let
   * go of nothing.
   *
   * Two ways in, and they are the same fact. The cap re-applied in `joinQueued` bumps the excess
   * off a drained turn; a `remove` takes back a whole parked message and everything it was
   * carrying with it. Either way the composer already dropped its own reference when the message
   * was parked, so this list is the last one, and losing it loses the rows.
   *
   * A file somebody attached and never saw again is the exact failure this feature exists to
   * avoid, so neither path can just slice the excess away and say nothing. And the cost of
   * staying quiet outlives the draft: the rows stay staged with `attachedAt IS NULL`, counting
   * against that person's per-channel limit until the 24-hour sweep, and surface as a confusing
   * 409 on their next upload with no way back to the files that caused it.
   *
   * THE CALLER IS WHAT ACTS ON IT. This is the transition naming them — so a caller can release
   * them through `DELETE /api/attachments/:id` and say so on screen — not doing either itself.
   * See `conversation-view.tsx`, which is the only caller that produces this from a real queue.
   */
  droppedAttachments: readonly Attachment[];
  /**
   * OF WHAT `run` IS CARRYING, THE PART NOTHING ELSE IS HOLDING — as the messages it came from, so
   * a caller whose run never becomes a message can put them back rather than having to decide what
   * to do with a bag of orphaned files. Empty when there is no run, and empty when everything on it
   * has somewhere to return to.
   *
   * IT USED TO BE THE ATTACHMENTS ALONE, AND THAT SHAPE ONLY ALLOWED ONE ANSWER. A list of files
   * with no words around them cannot be re-queued — nothing says which message each belonged to,
   * what was typed beside it, or which `/` skills it was invoked with — so the only thing a caller
   * could do with it was delete the rows, and that is what `conversation-view.tsx` did. Deleting
   * them is wrong for the reason the whole area keeps rediscovering: `channel-chat.tsx` adds the
   * user message to the transcript BEFORE the run, and nothing removes it when the run fails, so
   * the release destroyed the files behind a message that is still on screen. Handing back the
   * messages instead makes restoring possible, and restoring is what the caller now does.
   *
   * `droppedAttachments` is about files this transition REFUSED to carry; this is about what it DID
   * carry, named against the possibility that carrying it turns out to have been the last anybody
   * sees of it. The two never overlap: an attachment is either kept by the cap or bumped by it —
   * which is also why the messages here carry only the SURVIVORS. A restored message pointing at a
   * row the cap already gave back would be a retry of a file that no longer exists.
   *
   * WHY THE QUEUE HAS TO ANSWER THIS AND NOT THE CALLER. A drained turn is built out of messages
   * the composer let go of as they were parked, so nothing but this queue ever held them; a live
   * send joining a non-empty queue is built out of BOTH — the parked messages, held by nobody now
   * that the queue has emptied, and the draft in the box, which the composer puts back beside the
   * restored words when the send fails. Restoring the second kind would put a message back in the
   * queue whose words and chips are also sitting in the composer, and send it twice. Only the
   * transition knows which message came from where, so it is the transition that says.
   *
   * Which makes the answer per-case rather than "everything on the run":
   * - `settle` — every message in it, the whole run came out of the queue.
   * - `submit` joining a non-empty queue — the parked ones only; the live draft is the composer's
   *   to restore.
   * - `submit` with nothing waiting — none, the run IS the live draft.
   * - `remove`, a park, and a `restore` — none, there is no run.
   *
   * THE CALLER IS WHAT ACTS ON IT, and only on failure. See `conversation-view.tsx`, where both
   * paths that can produce a run answer this list from the same rule.
   */
  restoreIfRunFails: readonly QueuedMessage[];
};

/**
 * The whole rule, as one pure function, so the interesting cases can be checked without a browser
 * and a live model between the test and the behaviour.
 */
export function reduceQueue(
  queue: readonly QueuedMessage[],
  action: QueueAction,
): QueueTransition {
  switch (action.type) {
    case "submit": {
      /*
       * An idle send is not a queue of one. There is nothing to wait behind, so it goes straight
       * out exactly as it did before any of this existed.
       *
       * WITH SOMETHING ALREADY WAITING IT TAKES THAT WITH IT rather than going first. The two
       * disagreeing is not supposed to be reachable — the drain empties the queue on the same edge
       * that frees the composer — but "not supposed to be reachable" is an argument about two
       * components' timing, and this file is meant to hold the rule on its own. Jumping the line
       * would run a correction after the sentence correcting it, which is the exact reordering the
       * whole queue exists to prevent, so the safe reading of an impossible state is the one that
       * keeps what the person typed in the order they typed it.
       */
      if (!action.busy) {
        if (queue.length === 0) {
          // Nothing stranded: the run IS the draft in the box, and a send that fails hands its
          // words and its chips straight back to the composer they came from.
          return {
            queue,
            run: action.draft,
            droppedAttachments: [],
            restoreIfRunFails: [],
          };
        }
        /*
         * ADDRESSED TO WHOEVER THE LIVE DRAFT IS ADDRESSED TO. This send is going out now, from a
         * composer with a caret in it, so its `@mention` is a live routing decision and not a
         * leftover — and the branch directly above, the same send with nothing parked behind it,
         * honours it. Joining used to hardcode `null` here, which made `@Knowledge` mean one thing
         * or the other depending on whether anything happened to be waiting, a coincidence nobody
         * typing can see. The parked messages have no say: `QueuedMessage` carries no `agentId` at
         * all, for the reason `joinQueued` records.
         */
        const joined = joinQueued(
          [
            ...queue,
            {
              id: action.id,
              text: action.draft.text,
              commandIds: [...action.draft.commandIds],
              attachments: [...action.draft.attachments],
            },
          ],
          action.draft.agentId,
        );
        /*
         * THE PARKED HALF OF WHAT THIS RUN IS CARRYING, AND ONLY THAT HALF. The queue is emptied
         * here, so nothing holds the parked messages any more; the live draft's words, chips and
         * attachments are still the composer's, which puts them back beside each other when the
         * send fails. Restoring those as well would queue a second copy of a message somebody can
         * already see in their box.
         *
         * The messages that were waiting BEFORE this send joined them, rather than a slice of what
         * went out: the cap keeps the earliest, so the survivors happen to be the parked ones first
         * today, and a rule that read that off a slice would quietly go wrong the day the ordering
         * does. `carrying` filters by identity against what the join actually kept.
         */
        return {
          queue: [],
          run: joined.draft,
          droppedAttachments: joined.dropped,
          restoreIfRunFails: carrying(queue, joined.draft.attachments),
        };
      }
      /*
       * PARKED, WITH ITS FILES — AND THE FILES LEAVE ONE MORE PLACE THAN THE WORDS DO.
       *
       * The composer clears its own strip as this message is parked, which is what makes the words
       * look like they landed. It empties something else at the same time: the number the CLIENT'S
       * per-message cap is counted against. `stagedCount` in `composer.tsx` resyncs from the strip
       * on every commit, so after a park it reads zero. The SERVER'S cap counts a different set —
       * every row this person has staged in this composer's `uploadGroup` with `attachedAt IS NULL`
       * — and a parked row is exactly that until the drained turn is sent. The two therefore
       * disagree for the length of the turn: pick a ninth file behind eight parked ones and
       * `screenPickedFiles` accepts it, the upload goes out, and the server answers 409.
       *
       * WHICH IS NOT THE FAILURE `uploadGroup` WAS ADDED TO REMOVE, and the difference decides what
       * this is worth. That one was a 409 naming rows on NOBODY'S screen — a closed tab's, a
       * stopped run's — unreachable by the person holding them, with 24 hours of locked uploads in
       * that channel before the sweeper freed the count. These rows are on screen and are theirs to
       * act on: `chat-transcript.tsx` draws every parked attachment as a tile under its queued line,
       * taking the message back releases them (see `remove` below), and the drain stamps
       * `attachedAt` and frees the group. The server's sentence is true when it arrives — there
       * really are eight waiting to send. What is wrong is only WHO gets to say no, and how long it
       * takes: a refusal that should be instant and in the client's own words costs a round trip and
       * arrives in the server's.
       *
       * IT CANNOT BE CLOSED FROM THIS FILE, and the two ways it looks like it could are both worse.
       * Releasing the rows as the message parks would delete files somebody is still waiting to
       * send, which is the opposite of what every other release here is for. Re-applying the cap on
       * the way IN would bound the queue — it cannot exceed the cap anyway, because the server
       * refuses a ninth upload into one group — without changing the one number that decides
       * whether a pick is accepted, so the 409 would arrive exactly as before. That number is
       * `composer.tsx`'s, built from its own strip, and the queue is not something it can see; the
       * fix is one addend on that side, counting what is parked alongside what is staged.
       */
      return {
        queue: [
          ...queue,
          {
            id: action.id,
            text: action.draft.text,
            commandIds: [...action.draft.commandIds],
            attachments: [...action.draft.attachments],
          },
        ],
        run: null,
        droppedAttachments: [],
        restoreIfRunFails: [],
      };
    }

    case "restore": {
      if (action.messages.length === 0) {
        return {
          queue,
          run: null,
          droppedAttachments: [],
          restoreIfRunFails: [],
        };
      }
      return {
        // At the front: these were typed before anything that has parked while the failed run was
        // out, and the order somebody typed in is the order the Bot has to read.
        queue: [...action.messages, ...queue],
        run: null,
        droppedAttachments: [],
        restoreIfRunFails: [],
      };
    }

    case "settle": {
      if (queue.length === 0) {
        return {
          queue,
          run: null,
          droppedAttachments: [],
          restoreIfRunFails: [],
        };
      }
      /*
       * Nobody in particular. A drain has no live draft behind it — every message in it was parked
       * minutes ago into a conversation already pinned to one coworker — so there is no mention
       * here to honour and none is invented.
       */
      const joined = joinQueued(queue, null);
      return {
        queue: [],
        run: joined.draft,
        droppedAttachments: joined.dropped,
        /*
         * ALL OF THEM. Every message in this drain was parked, which means the composer let go of
         * its words and its attachments at the time, and the queue has just emptied itself to build
         * this. There is no box for a failed drain to put anything back into — so the queue is the
         * box, and a failure puts them back in it.
         */
        restoreIfRunFails: carrying(queue, joined.draft.attachments),
      };
    }

    case "remove": {
      const removed = queue.filter((message) => message.id === action.id);
      if (removed.length === 0) {
        // The same array, not an equal one: a removal that missed must not cost a re-render, and
        // it must not release anything either — nothing left the queue, so every row here still
        // belongs to a message sitting on screen waiting to run.
        return {
          queue,
          run: null,
          droppedAttachments: [],
          restoreIfRunFails: [],
        };
      }
      /*
       * WHATEVER IT WAS CARRYING GOES BACK, because this is the last reference to it. The composer
       * hands its staged attachments over as the message is parked and calls `removeAttachment`
       * on its own strip in the same breath, so from that moment the queue is the only thing
       * holding them. Dropping the entry without saying so left the rows staged server-side with
       * nothing on any screen pointing at them until the 24-hour sweep — counting against that
       * person's per-channel limit the whole time, and surfacing as a 409 naming files they have
       * no way back to. The composer's own strip already answers this exact gesture by releasing
       * the row behind a removed chip; this is the queue answering it the same way.
       */
      return {
        queue: queue.filter((message) => message.id !== action.id),
        run: null,
        droppedAttachments: removed.flatMap((message) => message.attachments),
        restoreIfRunFails: [],
      };
    }
  }
}

/**
 * The messages a run is carrying, carrying only the rows it actually took.
 *
 * ONE RULE FOR BOTH PATHS THAT CAN PRODUCE A RUN, which is the whole reason this is a function. A
 * drain and a live send joining a queue answer `restoreIfRunFails` from the same question — of the
 * messages the queue gave up, what is restorable — and two call sites each filtering for themselves
 * is two places for the cap's survivors and the cap's casualties to be confused with one another.
 *
 * BY IDENTITY AGAINST WHAT THE JOIN KEPT, not by count or by position. The cap keeps the earliest
 * files, so a restored message may have handed over three attachments and get one back; the other
 * two were bumped, reported through `droppedAttachments`, and released by the caller as the run was
 * built. Restoring those would put a message back pointing at rows that no longer exist.
 *
 * A MESSAGE LEFT WITH NOTHING AT ALL IS NOT RESTORED. A wordless, skill-less message whose only
 * attachments the cap bumped has nothing left to send and nothing to show: re-queueing it would
 * draw a blank row with a Remove button and no content, for a message that is genuinely gone.
 */
function carrying(
  queue: readonly QueuedMessage[],
  kept: readonly Attachment[],
): readonly QueuedMessage[] {
  const survivors = new Set(kept);
  return queue
    .map((message) => ({
      ...message,
      attachments: message.attachments.filter((attachment) =>
        survivors.has(attachment),
      ),
    }))
    .filter(
      (message) =>
        message.text.trim().length > 0 ||
        message.commandIds.length > 0 ||
        message.attachments.length > 0,
    );
}

/** The draft a drain produces, plus whatever the cap re-check would not let it keep. */
type Joined = {
  draft: ComposerDraft;
  dropped: Attachment[];
};

/**
 * Everything waiting, as the one turn it is about to become.
 *
 * Newlines rather than spaces. What the person typed were separate messages, and running them
 * together into a paragraph invents a sentence nobody wrote; keeping the line breaks keeps them as
 * lines of a single instruction, which is how a burst of corrections reads out loud anyway.
 *
 * WORDLESS MESSAGES CONTRIBUTE NO LINE. A message here is not obliged to have any text: a pasted
 * screenshot with nothing typed beside it is the whole point of `canSendDraft` unlocking on
 * attachments alone, and one parked mid-turn arrives with `text: ""`. Joining that in the way the
 * rest are joined opens the drained turn with a blank line, or splits two corrections apart with
 * one, and a blank line is an instruction nobody wrote. The message still counts for everything
 * else it carries — its files and its skills go in exactly as they would have.
 *
 * Which means the joined text CAN be empty, and `isEmpty` has to be computed rather than asserted:
 * a drain of nothing but screenshots has no words in it, and a field that claims otherwise is a
 * field no reader can trust for the case it exists to answer.
 *
 * `agentId` IS THE CALLER'S TO SUPPLY, and it is the one field of the joined draft that nothing in
 * the queue can answer. A `QueuedMessage` does not carry one: a message parked mid-turn lands in a
 * conversation already pinned to one coworker for the life of its thread, so there is nothing an
 * `@` could change, and the text of the mention stays in the words, where it was typed and where
 * it still reads as addressed. A LIVE draft joining the queue on its way out is the other case
 * entirely — it is being sent this instant and its mention routes — so which answer applies is
 * decided at each call site rather than assumed to be `null` here.
 */
function joinQueued(
  queue: readonly QueuedMessage[],
  agentId: string | null,
): Joined {
  /*
   * A parked message carries whatever the sender had staged when they parked it, in queue
   * order. Dropping them here would lose a file somebody attached before the Bot was ready.
   *
   * THE CAP HAS TO BE RE-APPLIED ON THE WAY OUT. It is checked as files are staged, against one
   * draft at a time; joining three parked messages of eight files each would produce a single
   * draft of twenty-four, which is a message this deployment does not accept and no later check
   * would catch. The earliest files win, the same order-of-arrival rule `screenPickedFiles`
   * applies within one draft, so the survivors are the ones the person picked first. That split
   * is not free, though: the excess is still staged server-side and nothing that survives this
   * function points at it any more, so `dropped` is what lets a caller give the rows back and say
   * which files went — instead of the person finding out from a 409 on their next upload with no
   * way back to what caused it.
   */
  const flattened = queue.flatMap((message) => message.attachments);
  const attachments = flattened.slice(0, MAX_ATTACHMENTS_PER_MESSAGE);
  const dropped = flattened.slice(MAX_ATTACHMENTS_PER_MESSAGE);

  const text = queue
    .map((message) => message.text)
    .filter((line) => line.trim().length > 0)
    .join("\n");

  return {
    draft: {
      text,
      agentId,
      // The same skill queued twice is still one instruction. Sending it twice would put the
      // same paragraph in front of the Bot two times and say nothing new by doing it.
      commandIds: [...new Set(queue.flatMap((message) => message.commandIds))],
      isEmpty: text.length === 0,
      attachments,
    },
    dropped,
  };
}