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 type { Message } from "@ag-ui/core";
import type { Attachment } from "@copilotkit/react-core/v2";
import {
type ReactNode,
useCallback,
useEffect,
useRef,
useState,
} from "react";
import { ChatTranscript } from "@/components/channels/chat-transcript";
import {
type AgentOption,
type CommandOption,
Composer,
type ComposerDraft,
type DroppedAttachments,
type QueueAction,
type QueuedMessage,
reduceQueue,
} from "@/components/channels/composer";
import { attachmentUrl } from "@/lib/channels/attachments";
import { newId } from "../../lib/new-id";
export function ConversationView({
messages,
busy = false,
notice,
agents = [],
commands,
channelId,
disabled = false,
pending = false,
autoFocus = false,
stopped,
working,
stoppable,
queueWhileBusy = false,
restoring = false,
onSubmit,
onStop,
voiceCall,
}: {
messages: readonly Message[];
busy?: boolean;
/** Shown above the composer. An error, or why this conversation is read-only. */
notice?: ReactNode;
agents?: readonly AgentOption[];
/**
* The `/` menu for this Bot's granted skills, supplied by the route that owns grant loading.
*/
commands?: readonly CommandOption[];
/**
* The channel this conversation belongs to, forwarded to the composer so it can upload
* attachments to it. Omitted by a caller with no channel yet — `/channel/new` creates one on
* first send — which leaves the composer exactly as it behaved before attachments existed.
*/
channelId?: string;
disabled?: boolean;
/**
* A turn is in flight: the Bot has been asked something and has not come back yet.
*
* It has to mean the TURN and not the run underneath it. A turn that uses the browser is several
* runs in a row with the agent reporting itself idle between them, and a caller that passes its
* agent's run status straight through will tell this component the conversation is free in the
* middle of an answer. `queueWhileBusy` is the part that cannot survive that, because the queue
* drains on this falling.
*/
pending?: boolean;
/** Focus the composer the moment it can take a caret; forwarded to the composer. */
autoFocus?: boolean;
/** Why the last turn ended without an answer. Drawn at the end of the transcript, not here. */
stopped?: string;
/** Work the conversation waits on that is not this tab's run. Drawn at the end of the transcript. */
working?: ReactNode;
/**
* There is a run for Stop to abort, which is a narrower fact than `pending` and is the honest one
* to draw a Stop button from. Defaults to `pending` for a caller with no gap between the two.
*/
stoppable?: boolean;
/**
* Let somebody type at a Bot that is already working, and run what they typed when it finishes.
*
* Off by default, and asked for rather than assumed, because it is only true of a conversation
* that will still be here when the turn ends. The compose screen creates the channel on send and
* navigates away; a message parked there would go down with the unmount, and a message that
* silently disappears is a worse answer than a send button that will not go.
*
* The other place somebody talks to a Bot, the direct `/bot` chat, does not get this either, and
* not by a decision made here: that screen draws CopilotKit's own chat rather than this composer,
* so there is nothing on it for this flag to reach. Giving it the same affordance means either
* moving it onto this composer or asking for it upstream, and neither is a queue.
*/
queueWhileBusy?: boolean;
/** History has been asked for and has not arrived. Drawn as placeholder rows; see `ChatTranscript`. */
restoring?: boolean;
onSubmit: (draft: ComposerDraft) => void | Promise<void>;
/** Stop the Bot mid-answer; forwarded to turn the send button into a stop button. */
onStop?: () => void;
voiceCall?: { active: boolean; supported: boolean; onStart(): void };
}) {
/*
* THE QUEUE LIVES HERE BECAUSE BOTH HALVES OF IT DO.
*
* The composer is what knows a turn is in flight and is where a message is typed; the transcript
* is where the person has to be able to see that it landed. This is the nearest thing that owns
* them both, and putting the list in either one would mean handing it straight back out again.
*
* See `composer/queue.ts` for what this state is worth: it is memory in one tab, it does not
* survive a reload, and it is not an outbox.
*/
const [queued, setQueued] = useState<readonly QueuedMessage[]>([]);
const queuedRef = useRef<readonly QueuedMessage[]>(queued);
/**
* Files the queue left behind AND the reason it did, forwarded to the composer so it can say so
* rather than leaving somebody to notice on their own that a file they attached is not going to
* be sent. See `reduceQueue`'s `droppedAttachments` for the two ways a row gets here.
*
* Saying so is only half of it, and `releaseStagedAttachment` below is the other half: these rows
* are still staged server-side, and telling somebody about them without giving them back is a
* warning shipped alongside its own cause.
*
* The cause travels with them because `reduceQueue` cannot supply it — it reports the same
* `Attachment[]` whether the files were bumped off a merged draft by the cap or carried out of the
* queue by a message somebody removed, and the composer's sentence for one is false about the
* other.
*
* Only ever set, never appended to: each transition is its own event, and the composer is what
* turns a new object here into new rejection lines, one batch per event, rather than this file
* accumulating a list nobody here has any other use for.
*/
const [droppedAttachments, setDroppedAttachments] =
useState<DroppedAttachments>();
/**
* A turn this screen started and has not seen finish.
*
* It is a backstop under `pending` rather than the thing that makes `pending` usable. A caller
* that reports the turn honestly already covers the gap between `onSubmit` being called and the
* turn showing up in its own state; one that does not leaves a gap in which a person typing
* quickly would have their second message read as the start of a second turn, two runs at once on
* one thread racing each other's history.
*
* It cannot be the whole answer, and it was a mistake to let it look like one. This only knows
* about turns that came in through the composer. A channel starts turns by other routes — the
* first message of a new channel, a button inside a rendered component — and for those the only
* thing standing between a parked correction and a mid-answer drain is what the caller passes as
* `pending`.
*
* The composer tracks the same await for its own send button. Two trackers of one promise, which
* is duplication, and they cannot drift: they rise in the same tick and fall on the same resolve.
* The alternative is a callback out of the composer announcing an edge, which is a larger surface
* for the same fact.
*/
const [running, setRunning] = useState(false);
const inFlight = pending || running;
/**
* Every change to the queue goes through here, so the ref and the state can never disagree.
*
* The ref is what the decisions read. React state is a render behind, and both callers below have
* to know what is actually queued at the moment they are called rather than at the moment they
* were last rendered — one of them is an effect firing on the same commit that emptied the list.
*
* THE WHOLE TRANSITION COMES BACK, NOT JUST THE RUN. It used to hand back `next.run` alone, which
* was every caller's whole interest until a failed run became something either of them had to
* answer for: a run can only be put back if you know which of the messages in it the queue
* contributed, and that is on the transition beside it. Recomputing it out here would mean
* re-deriving from a queue this function has already emptied.
*/
const apply = useCallback((action: QueueAction) => {
const next = reduceQueue(queuedRef.current, action);
queuedRef.current = next.queue;
setQueued(next.queue);
// Only on an actual drop, so a settle or a remove that let go of nothing does not hand the
// composer a fresh empty array it has no reason to react to.
if (next.droppedAttachments.length > 0) {
/*
* THE ACTION IS WHAT SAYS WHICH OF THE TWO CAUSES THIS WAS, and this is the only place that
* has both halves. `reduceQueue` reports the same `Attachment[]` whether the files were
* bumped off a merged draft by the cap or carried out of the queue by a message somebody
* removed, so the cause cannot be recovered downstream — and the composer's sentence for one
* of them is false about the other.
*/
for (const attachment of next.droppedAttachments) {
releaseStagedAttachment(attachment);
}
setDroppedAttachments({
attachments: next.droppedAttachments,
cause:
action.type === "remove"
? "queued-message-removed"
: "merged-over-cap",
});
}
return next;
}, []);
/**
* WALKING AWAY WITH SOMETHING STILL PARKED IS THE THIRD WAY A ROW LOSES ITS LAST REFERENCE, and
* until this it was the one way that said nothing and gave nothing back.
*
* IT USED TO BE THE FOURTH, and the one that went was a way a row should never have lost its last
* reference at all: a drained turn whose send failed used to release everything it was carrying.
* That one is now a restore — the messages go back in the queue, still holding their rows — so
* the ways out are the two in `apply` above, a removal and the cap's excess, and this.
*
* The other two go through `apply` above. This one goes through React:
* `queue.ts` is candid that the queue "lives and dies with the component holding it" and that
* switching channels "takes anything parked in it with it" — but that paragraph is about the
* person's WORDS, which they watched land on screen and can retype. It was never a statement
* about the staged rows underneath them, and `releaseStagedAttachment` is explicit that a parked
* entry holds the only reference anything has to those.
*
* WHAT IT COSTS TO SKIP, stated because it is smaller than the other two and the fix should be
* priced honestly: the upload cap is scoped by `uploadGroup`, minted per composer mount, so this
* orphan does not refuse anybody's next pick the way a removal's would — the composer that staged
* it is gone and its group with it. It is storage held for up to a day by
* `cull-staged-attachments.ts`, not a 409. Worth releasing anyway, because the row is bytes in a
* table nobody will ever ask for again and the release is two lines.
*
* BEST-EFFORT IN THE STRICTEST SENSE. This runs during teardown, so the requests go out into a
* component that is already gone and nothing here could act on an answer even in principle —
* which is exactly what `releaseStagedAttachment` already is. A tab CLOSING is not this path at
* all and is not chased: the page is going, `fetch` on the way out is not reliable, and the
* sweeper is the honest answer for that one.
*
* The ref rather than the state, for the reason `apply` records: on an unmount that follows a
* transition in the same commit, the state is a render behind and the ref is not. Empty on
* StrictMode's development double-mount, which makes that pass a no-op.
*/
useEffect(
() => () => {
for (const message of queuedRef.current) {
for (const attachment of message.attachments) {
releaseStagedAttachment(attachment);
}
}
},
[],
);
/**
* A RUN BUILT OUT OF THIS QUEUE FAILED, SO THE DRAIN WAITS FOR A TURN BEFORE TRYING AGAIN.
*
* Without it the restore below is a spin. The drain effect reads `queuedRef` rather than the
* state, so the restored messages are visible to it the instant `apply` writes them — and the
* commit that clears `running` schedules that effect with no ordering guarantee against the
* rejection that restores. The two land in either order, so on a server that is refusing every
* request the queue could be re-sent immediately, fail, restore, and be re-sent again, as fast as
* the round trip allows. A retry the person did not ask for is not a retry, it is a loop.
*
* A REF AND NOT STATE, for the reason `queuedRef` is one: the effect that reads this runs on the
* commit that clears `running`, and a state update made in the rejection is a render behind. It
* also must not itself cause a render — nothing on screen changes when a queue is held back; the
* entries are drawn as parked either way.
*/
const heldBack = useRef(false);
/**
* PUT A FAILED RUN'S MESSAGES BACK WHERE THEY CAME FROM, and hold the drain until somebody asks.
*
* The one answer to a failed send, used by both paths that can produce a run. See the drain's
* `catch` for why restoring rather than releasing, and `heldBack` for why the hold.
*/
const restoreFailedRun = useCallback(
(messages: readonly QueuedMessage[]) => {
if (messages.length === 0) {
return;
}
// Before the restore, not after: the effect reads both off refs, and the guard has to be
// true by the moment the queue is non-empty again rather than one statement later.
heldBack.current = true;
apply({ messages, type: "restore" });
},
[apply],
);
const start = async (draft: ComposerDraft) => {
setRunning(true);
try {
await onSubmit(draft);
} finally {
setRunning(false);
}
};
/** Read through a ref so an inline `onSubmit` from the route does not re-run the drain effect. */
const startRef = useRef(start);
startRef.current = start;
/**
* Send now, or park it. Which one is the composer's call: it holds the only accurate view of
* whether a turn is in flight, and `reduceQueue` holds what follows from the answer.
*/
const submit = useCallback(
(draft: ComposerDraft, whileBusy: boolean) => {
const next = apply({
busy: whileBusy,
draft,
id: newId(),
type: "submit",
});
if (!next.run) {
return undefined;
}
const started = startRef.current(next.run);
/*
* A SEND THAT TOOK THE QUEUE WITH IT AND THEN FAILED LEAVES THE PARKED HALF HELD BY NOBODY,
* which is the same shape the drain effect below answers, and with the same line.
*
* The ordinary send is not this. Its run IS the draft in the box, and the composer's `catch`
* puts those words and those chips straight back — so `restoreIfRunFails` is empty for it and
* this branch never runs. It is only the join, where `reduceQueue` empties the queue into an
* outgoing draft, that produces a run carrying messages the composer never had.
*
* WHICH MESSAGES IS THE QUEUE'S ANSWER AND NOT ONE COMPUTED HERE. By the time this rejects,
* the queue that knew where each message came from is empty; `restoreIfRunFails` was decided
* on the transition that emptied it. Restoring the composer's own as well would queue a
* second copy of the words that are back in somebody's box.
*
* `started` IS WHAT GOES BACK TO THE COMPOSER, not the promise this `catch` derives from it.
* The composer needs the rejection to restore the words, so the failure must still be its to
* handle; the derived promise exists only to hang the restore off, is settled by the `catch`
* itself, and is deliberately dropped.
*/
if (next.restoreIfRunFails.length > 0) {
const carried = next.restoreIfRunFails;
void started.catch(() => {
restoreFailedRun(carried);
});
}
return started;
},
[apply, restoreFailedRun],
);
/**
* The turn ended. Whatever was waiting for it goes now, as one message.
*
* KEYED ON THE TURN BEING OVER AND NOT ON HOW IT ENDED, which is what makes Stop useful rather
* than final: a person who parks a correction and then presses Stop has said "not that, this",
* and this is the line that hears the second half of it. A finished run, a failed one and a
* stopped one all arrive here the same way, so there is no stop path to forget.
*
* The one edge it watches is `inFlight` falling, and it does not watch the queue. Nothing can be
* parked while the conversation is idle: the composer only parks when it believes a turn is in
* flight, and it believes that from the same value this effect reads. A queue that grew here
* without a turn to wait for would be a queue that never drains, so if that ever becomes possible
* this dependency list is where it will show up.
*
* IT REFUSES WHILE THE CONVERSATION IS DISABLED, which is the one thing "however it ended" must
* not be read to cover. A coworker deleted mid-turn takes the channel with it: the composer stops
* accepting messages and the notice under it says the conversation can no longer reply, and a
* queue that drained anyway would post one more user turn into a channel the screen has already
* said is finished. The cost is that anything parked when that happens stays on screen unrun,
* under a notice that explains why, which is the honest half of the trade.
*
* AND IT REFUSES ONCE A DRAIN HAS FAILED, until a turn starts. See `heldBack`.
*/
useEffect(() => {
if (inFlight) {
/*
* A TURN STARTING IS WHAT LETS A HELD-BACK QUEUE GO AGAIN, and it is the only thing that
* does. Every way a turn starts is somebody asking for one — a send, a parked message joined
* to it, a button inside a rendered card — so the retry is always something a person did,
* never this effect trying again on its own.
*/
heldBack.current = false;
return;
}
if (disabled || heldBack.current || queuedRef.current.length === 0) {
return;
}
const next = apply({ type: "settle" });
if (!next.run) {
return;
}
const carried = next.restoreIfRunFails;
void startRef.current(next.run).catch(() => {
/*
* Swallowed on purpose, and only here. A failed send from the composer throws so the composer
* can put the words back in the box; the box for these is the queue they came out of, and the
* screen already reports the failed turn through its own notice.
*
* IT USED TO DELETE THE STAGED ROWS INSTEAD, AND THAT WAS DATA LOSS. The reasoning was that
* the queue had emptied to build this draft and nothing retried it, so the rows behind
* `run.attachments` were referenced by nothing and might as well be given back rather than
* waiting for the sweep. The second half of that sentence was never true: `channel-chat.tsx`
* adds the user message to the transcript BEFORE the run and leaves it there when the run
* fails, so the files were referenced by a message the person is looking at. Releasing them
* emptied the tiles under a message that stayed on screen, with nothing said and no way back.
*
* SO THE MESSAGES GO BACK IN THE QUEUE, WHOLE. Their words, their `/` chips and the rows the
* run actually carried return as parked entries — visible in the transcript, carried by the
* next turn, and released only if somebody takes one back by hand. Deleting on an explicit
* removal is the one gesture that has ever justified it; a run that failed is not that.
*
* `restoreIfRunFails` RATHER THAN THE QUEUE THIS DRAINED, WHICH FOR A DRAIN IS NEARLY THE
* SAME LIST AND IS NOT THE SAME CLAIM. The cap may have bumped attachments off the joined
* draft on the way out, and `apply` released those as the run was built; restoring the
* original entries would re-queue messages pointing at rows that are gone. Spelling it as the
* queue's own answer is also what lets `submit` — where the two are further apart still — use
* the identical line.
*
* NOT INSIDE `start`, AND THAT IS LOAD-BEARING. `start` is also called from `submit`, where
* the promise goes back to the composer and the composer restores its own draft. Restoring
* everything a run carries from inside `start` would queue a second copy of the words that
* are back in the box, so the decision belongs to the call sites — this one, and the join in
* `submit`, which answers the same question from the same list.
*/
restoreFailedRun(carried);
});
}, [apply, disabled, inFlight, restoreFailedRun]);
return (
<div className="flex flex-col flex-1 min-h-0">
<div className="flex flex-1 min-h-0">
{/*
* The command NAMES, joined, rather than the option objects.
*
* The transcript needs them only to tell a real skill chip from a message that happens to
* begin with a slash, and its message rows are memoised on primitives — handing them an
* array would give every message a new prop identity on each refetch and re-render the whole
* conversation to change nothing.
*/}
<ChatTranscript
busy={busy}
commandNames={(commands ?? [])
.map((command) => command.name)
.join(",")}
messages={messages}
onRemoveQueued={(id) => {
apply({ id, type: "remove" });
}}
queued={queued}
restoring={restoring}
{...(stopped ? { stopped } : {})}
working={working}
/>
</div>
<div
className="max-w-2xl mx-auto w-full px-0 pb-4 shrink-0"
data-slot="composer-column"
>
{notice}
<Composer
agents={agents}
autoFocus={autoFocus}
{...(channelId ? { channelId } : {})}
{...(commands ? { commands } : {})}
className="w-full mt-auto"
compact
voiceCall={voiceCall}
disabled={disabled}
droppedAttachments={droppedAttachments}
onQueue={
queueWhileBusy
? (draft) => {
submit(draft, true);
}
: undefined
}
onStop={onStop}
onSubmit={(draft) => submit(draft, false)}
/*
* `inFlight` rather than the `pending` this was given. A drained turn is started from the
* effect above rather than from the composer, so the composer's own send tracking knows
* nothing about it — told only `pending`, it would believe the conversation was idle for
* as long as the drained run took to start, and the next thing typed would open a third
* turn instead of joining the queue.
*/
pending={inFlight}
/*
* THE HALF OF THE PER-MESSAGE CAP THE COMPOSER CANNOT SEE.
*
* The composer counts what is on its own strip, and parking a message empties it. The
* server counts every row this person has staged in that composer's `uploadGroup` that
* has not been sent, and parking a message changes nothing about those: `attachedAt` is
* written when the message really goes. So without this the two disagree by exactly the
* size of the queue, and a ninth pick behind eight parked files is accepted here and
* refused on arrival — a 409 the person was given no chance to avoid, phrased as a count
* against a strip they can see is empty.
*
* READ OFF THE QUEUE ON EVERY RENDER RATHER THAN ACCUMULATED, which is what makes it fall
* as well as rise. A running total would be right until somebody took a parked message
* back, and then it would hold slots that nothing occupies — the same refusal, now issued
* by their own client with no round trip to blame it on.
*
* `queued` and not `queuedRef`: this is a render, so the state is the value React is
* drawing from, and the ref exists for the callbacks that cannot wait a render. They
* agree here anyway — `apply` writes both on the same line.
*/
queuedAttachmentCount={queued.reduce(
(total, message) => total + message.attachments.length,
0,
)}
/*
* The caller's answer, not `inFlight`. `running` is true from the instant `start` is
* entered, which is before `onSubmit` has done anything at all, so a Stop drawn from
* `inFlight` appears while there is still nothing to stop — the press is swallowed and the
* message goes anyway.
*/
stoppable={stoppable ?? pending}
/>
</div>
</div>
);
}
/**
* GIVE BACK THE STAGED ROW BEHIND AN ATTACHMENT THE QUEUE HAS LET GO OF.
*
* The composer hands its staged attachments to the queue as a message is parked and clears its own
* strip in the same breath, so a parked entry holds the only reference anything has to those rows.
* When `reduceQueue` reports one in `droppedAttachments` — a message taken back before it ran, or
* the excess the cap re-check bumped off a drained turn — this is the last chance to release it.
*
* WHAT NOT DOING THIS COSTS. The row stays with `attachedAt IS NULL` until `cull-staged-
* attachments.ts` sweeps it a day later. Until then the upload handler counts it against this
* person's per-channel limit and refuses their ninth pick by naming files that are on nobody's
* screen, with no way back to them. For the cap case that is the exact 409 the on-screen notice
* exists to pre-empt, so leaving the row behind shipped the warning together with its cause.
*
* ONLY A ROW THAT EXISTS. `metadata.attachmentId` is written by `attachmentsConfigFor` from the
* upload response, so an attachment that never finished uploading carries none and there is
* nothing to delete — the same test `composer.tsx` applies before its own DELETE.
*
* BEST-EFFORT, AND DELIBERATELY UNINSPECTED, for the reason `composer.tsx` records against the
* same request: the person did not ask for this, so neither of the two answers it can fail with —
* 404 for a non-uploader, 409 for an attachment already sent — is anything they could act on.
*
* THE SECOND CALLER OF THIS ENDPOINT, and deliberately not shared with the first. `composer.tsx`
* owns the identical two lines for its own strip; a common helper is the right end state and is a
* change to a file this one does not own, so the duplication is written down here rather than
* reached across for.
*/
function releaseStagedAttachment(attachment: Attachment): void {
const metadata = attachment.metadata as
| { attachmentId?: unknown }
| undefined;
if (typeof metadata?.attachmentId !== "string") {
return;
}
void fetch(attachmentUrl(metadata.attachmentId), {
method: "DELETE",
credentials: "include",
}).catch(() => undefined);
}