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.

Stop losing the first message of a new channel, and say what the transcript is doing (#161)

Vaibhav Zopefcb437b9a8b7
diff --git a/app/src/components/channels/channel-chat.tsx b/app/src/components/channels/channel-chat.tsx
index 1a127211..89148a5a 100644
--- a/app/src/components/channels/channel-chat.tsx
+++ b/app/src/components/channels/channel-chat.tsx
@@ -19,15 +19,24 @@ import { recordChannelActivityMutationOptions } from "@/lib/channels/mutations";
import type { AgentChannel } from "@/lib/channels/queries";
import { useActiveBot } from "@/lib/copilot/active-bot";
import { ConversationProvider } from "@/lib/copilot/conversation";
+import { afterMs, joinWithin } from "@/lib/copilot/join-thread";
import { repairUnansweredToolCalls } from "@/lib/copilot/repair-history";
import { stoppedReason } from "@/lib/copilot/stopped-turn";
import { useSkillCommands } from "@/lib/plugins/skill-commands";
import { newId } from "../../lib/new-id";
/**
- * Backstop for the first message of a new channel; a stalled join must not lose the message.
+ * How long a stalled thread join is worth waiting for before it is ended.
+ *
+ * Ended, not outrun. See `lib/copilot/join-thread.ts` for what a connect left in flight does to the
+ * next message sent.
+ */
+const JOIN_DEADLINE_MS = 1500;
+
+/**
+ * Backstop for a message typed before the runtime agent exists; it must not be discarded.
*/
-const SEND_WITHOUT_JOIN_AFTER_MS = 1500;
+const SEND_WITHOUT_RUNTIME_AFTER_MS = 1500;
/**
* One channel's conversation with one coworker.
@@ -90,6 +99,22 @@ export function ChannelChat({
const readyGatePromise = readyGate.current;
const isReadyRef = useRef(isReady);
isReadyRef.current = isReady;
+
+ /*
+ * THE AGENT IS READ WHEN IT IS USED, NEVER CAPTURED BEFORE A WAIT. `useAgent` hands back a
+ * provisional agent until the proxied one is registered, and a different object afterwards. The
+ * stale one still runs and still reaches the thread, so the answer is stored and shows up on the
+ * next reload while the rendered agent sits empty. `say` waits, so it spans that swap.
+ */
+ const agentRef = useRef(agent);
+ agentRef.current = agent;
+
+ /**
+ * History has been asked for and has not arrived. True for a channel opened from the roster, where
+ * an empty transcript is also a real answer; false for one started from the compose screen, which
+ * already has the message that started it.
+ */
+ const [restoring, setRestoring] = useState(seed === null);
useEffect(() => {
if (isReady) openReadyGate.current();
}, [isReady]);
@@ -100,11 +125,12 @@ export function ChannelChat({
let current = true;
void (async () => {
- try {
- await copilotkit.connectAgent({ agent });
- } catch {
- // Reported by the run-failure subscriber below; history is still worth restoring.
- }
+ // Bounded, and finished when it returns; `join-thread.ts` has why that matters.
+ await joinWithin({
+ connect: copilotkit.connectAgent({ agent }),
+ deadline: afterMs(JOIN_DEADLINE_MS),
+ detach: () => agent.detachActiveRun(),
+ });
try {
const stored = await readThreadMessages(
@@ -116,6 +142,9 @@ export function ChannelChat({
agent.setMessages(stored);
}
} finally {
+ // Cleared on failure too: placeholders over an empty transcript promise messages that are
+ // never coming.
+ if (current) setRestoring(false);
// Release even on join/restore failure; the gate orders messages, not withholds them.
openJoinGate.current();
}
@@ -188,12 +217,24 @@ export function ChannelChat({
if (!isReadyRef.current) {
await Promise.race([
readyGatePromise,
- new Promise((resolve) =>
- setTimeout(resolve, SEND_WITHOUT_JOIN_AFTER_MS),
- ),
+ afterMs(SEND_WITHOUT_RUNTIME_AFTER_MS),
]);
}
+ /*
+ * EVERY TURN WAITS FOR THE JOIN, not just the first of a new channel: a message added while the
+ * connect is in flight is erased by it either way. Unbounded only in appearance — the join
+ * effect bounds itself and opens this gate from a `finally`. If that effect never ran there is
+ * no runtime agent, and no connect in flight to wait on.
+ */
+ if (isReadyRef.current) {
+ await joinGatePromise;
+ }
+
+ // Every wait is behind us, so this is the agent the screen is actually rendering. Read once and
+ // used throughout, so the message, the repair and the run cannot land on two different agents.
+ const target = agentRef.current;
+
setRunError(null);
awaitingReply.current = true;
@@ -210,14 +251,14 @@ export function ChannelChat({
* chip is what says a skill was used, and it stays visible in the message they sent.
*/
for (const instruction of skillInstructions) {
- agent.addMessage({
+ target.addMessage({
content: instruction,
id: newId(),
role: "system",
});
}
- agent.addMessage({
+ target.addMessage({
content: trimmed,
id: newId(),
role: "user",
@@ -225,14 +266,14 @@ export function ChannelChat({
report(trimmed, null);
// Providers reject later turns if prior tool calls have no result; repair before sending.
- const repaired = repairUnansweredToolCalls(agent.messages);
- if (repaired !== agent.messages) {
- agent.setMessages(repaired as typeof agent.messages);
+ const repaired = repairUnansweredToolCalls(target.messages);
+ if (repaired !== target.messages) {
+ target.setMessages(repaired as typeof target.messages);
}
setRunsInFlight((count) => count + 1);
try {
- await copilotkit.runAgent({ agent });
+ await copilotkit.runAgent({ agent: target });
} finally {
setRunsInFlight((count) => count - 1);
}
@@ -296,33 +337,31 @@ export function ChannelChat({
}, []);
/**
- * Send the create-channel seed once, after the join gate opens or the backstop expires.
+ * Send the create-channel seed once. No waiting of its own: `say` owns that for every turn, and a
+ * second copy of the ordering here was the one that could disagree with it.
*/
useEffect(() => {
const pending = seedRef.current;
if (!pending) return;
seedRef.current = null;
- void (async () => {
- await Promise.race([
- joinGatePromise,
- new Promise((resolve) =>
- setTimeout(resolve, SEND_WITHOUT_JOIN_AFTER_MS),
- ),
- ]);
- await sayRef.current(
- typeof pending.content === "string" ? pending.content : "",
- );
- })();
+ void sayRef.current(
+ typeof pending.content === "string" ? pending.content : "",
+ );
- // Keep `seed` in state; transcriptMessages hides it as soon as agent messages exist.
- }, [joinGatePromise]);
+ // Keep `seed` in state; transcriptMessages gives it up once the agent holds a user turn.
+ }, []);
return (
<ConversationProvider ask={askFromComponent}>
<ConversationView
agents={toAgentOptions(agentProfiles, channel.agentIds)}
- busy={agent.isRunning}
+ /*
+ * THE TURN, not the run. `say` waits for the runtime agent and the join before a run starts,
+ * and `agent.isRunning` alone leaves that gap unmarked — which is the one moment the
+ * "Thinking" line exists for. Same value as `pending`, deliberately.
+ */
+ busy={agent.isRunning || turnsInFlight > 0}
// The `/` menu exposes only skills granted to this Bot.
commands={skillCommands}
// Readiness is handled by `say`; deletion is the only disabled-chat state.
@@ -378,6 +417,7 @@ export function ChannelChat({
* above.
*/
queueWhileBusy
+ restoring={restoring}
/*
* The run, not the turn. Stop reaches a run through the core's abort controller, and that
* controller does not exist until `say` has finished waiting for the runtime agent — so
diff --git a/app/src/components/channels/chat-transcript.tsx b/app/src/components/channels/chat-transcript.tsx
index baeb23d2..84edf602 100644
--- a/app/src/components/channels/chat-transcript.tsx
+++ b/app/src/components/channels/chat-transcript.tsx
@@ -12,6 +12,7 @@ import {
MessageFooter,
Message as MessageRow,
} from "@/components/ui/message";
+import { Skeleton } from "@/components/ui/skeleton";
import {
MessageScroller,
MessageScrollerButton,
@@ -40,6 +41,8 @@ type ChatTranscriptProps = {
queued?: readonly QueuedMessage[];
/** Take one back before it runs. Without it a queued line is shown but cannot be undone. */
onRemoveQueued?: (id: string) => void;
+ /** History has been asked for and has not arrived. Drawn only when there is nothing else to draw. */
+ restoring?: boolean;
/**
* Why the last turn ended without an answer, if it did.
*
@@ -77,6 +80,40 @@ function splitSkillChip(
return { chip: match[1], rest: text.slice(match[0].length) };
}
+/**
+ * The shape of a conversation, while it is still being fetched. Shaped like what is coming rather
+ * than like a loading widget, on the same line pitch so the column does not jump when words land.
+ */
+const RESTORING_ANSWER_LINES = [
+ { id: "line-1", width: "w-full" },
+ { id: "line-2", width: "w-11/12" },
+ { id: "line-3", width: "w-full" },
+ { id: "line-4", width: "w-10/12" },
+ { id: "line-5", width: "w-11/12" },
+ { id: "line-6", width: "w-full" },
+ { id: "line-7", width: "w-11/12" },
+ { id: "line-8", width: "w-2/3" },
+] as const;
+
+function RestoringTranscript() {
+ return (
+ // One announcement, with every bar hidden from it: nine empty shapes read aloud is worse.
+ <div aria-label="Loading this conversation" role="status">
+ <div aria-hidden="true" className="flex justify-end pb-7">
+ <Skeleton className="h-10 w-64 rounded-xl bg-muted/40 motion-reduce:animate-none" />
+ </div>
+ <div aria-hidden="true" className="flex flex-col gap-3">
+ {RESTORING_ANSWER_LINES.map((line) => (
+ <Skeleton
+ className={`h-4 bg-muted/40 motion-reduce:animate-none ${line.width}`}
+ key={line.id}
+ />
+ ))}
+ </div>
+ </div>
+ );
+}
+
/**
* The Bot has the turn and has produced nothing yet.
*
@@ -529,6 +566,7 @@ export function ChatTranscript({
messages,
onRemoveQueued,
queued = EMPTY_QUEUE,
+ restoring = false,
stopped,
}: ChatTranscriptProps) {
/*
@@ -593,6 +631,8 @@ export function ChatTranscript({
* memoising it would achieve nothing. Its child is what costs — markdown parsing and
* chart SVGs — and that is what is skipped.
*/}
+ {/* Instead of the rows, never alongside them: one real message and this is a lie. */}
+ {items.length === 0 && restoring ? <RestoringTranscript /> : null}
{items.map((item, index) =>
item.kind === "tool" ? (
<MessageScrollerItem key={item.id} messageId={item.id}>
diff --git a/app/src/components/channels/conversation-view.tsx b/app/src/components/channels/conversation-view.tsx
index ff7406dc..420e33ca 100644
--- a/app/src/components/channels/conversation-view.tsx
+++ b/app/src/components/channels/conversation-view.tsx
@@ -29,6 +29,7 @@ export function ConversationView({
stopped,
stoppable,
queueWhileBusy = false,
+ restoring = false,
onSubmit,
onStop,
}: {
@@ -73,6 +74,8 @@ export function ConversationView({
* 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;
@@ -213,6 +216,7 @@ export function ConversationView({
apply({ id, type: "remove" });
}}
queued={queued}
+ restoring={restoring}
{...(stopped ? { stopped } : {})}
/>
</div>
diff --git a/app/src/components/channels/transcript-messages.ts b/app/src/components/channels/transcript-messages.ts
index 25737ed1..2b1110ee 100644
--- a/app/src/components/channels/transcript-messages.ts
+++ b/app/src/components/channels/transcript-messages.ts
@@ -3,17 +3,21 @@ import type { Message } from "@ag-ui/core";
/**
* What a transcript shows while a brand-new channel is still joining.
*
- * Channel join replaces the agent's local messages with restored thread history. The first message
- * is held here as a seed until restored messages arrive, then ignored to avoid duplicate rendering.
+ * NOT DECIDED ON `messages.length`: the runtime replaces its messages wholesale, so the seed would
+ * be dropped on the first assistant token with the person's own turn already gone. A role rather
+ * than an id, because the agent's copy and the restored copy each mint their own.
*/
export function transcriptMessages(
messages: readonly Message[],
seed: Message | null,
): readonly Message[] {
- if (messages.length > 0 || seed === null) {
+ if (seed === null) {
return messages;
}
- return [seed];
+ if (messages.some((message) => message.role === "user")) {
+ return messages;
+ }
+ return [seed, ...messages];
}
/** The person's message, in the shape the transcript and the agent both take. */
diff --git a/app/src/lib/copilot/join-thread.ts b/app/src/lib/copilot/join-thread.ts
new file mode 100644
index 00000000..f717cd12
--- /dev/null
+++ b/app/src/lib/copilot/join-thread.ts
@@ -0,0 +1,48 @@
+/**
+ * Joining a channel's durable thread, bounded, and OVER when it says it is over.
+ *
+ * THE DEADLINE ENDS THE CONNECT RATHER THAN OUTRUNNING IT: one left in flight is torn down by the
+ * next run, and ends by replacing the agent's messages — losing anything added in between.
+ */
+
+/** Resolves once `connect` has finished, ending it early if `deadline` comes first. */
+export async function joinWithin({
+ connect,
+ deadline,
+ detach,
+}: {
+ /** The join already in progress. Its rejection is an outcome, not a failure of this function. */
+ connect: Promise<unknown>;
+ /** How long the join is worth waiting for. Resolving means "stop waiting", not "stop". */
+ deadline: Promise<void>;
+ /** End the in-flight connect. Asked for once, and only when the deadline came first. */
+ detach: () => Promise<unknown>;
+}): Promise<void> {
+ // Settled either way: a connect that failed is a join that is over, and the caller restores
+ // history separately. Kept as one promise so it can be awaited twice without a second rejection.
+ const finished = connect.then(
+ () => undefined,
+ () => undefined,
+ );
+
+ const outcome = await Promise.race([
+ finished.then(() => "connected" as const),
+ deadline.then(() => "deadline" as const),
+ ]);
+ if (outcome === "connected") {
+ return;
+ }
+
+ try {
+ await detach();
+ } catch {
+ // A detach with nothing to detach is not a problem worth reporting, and the wait below is what
+ // this function actually promises. Swallowing it here keeps that promise on both paths.
+ }
+ await finished;
+}
+
+/** A deadline, as a promise. Separate so a test can supply one it controls. */
+export function afterMs(milliseconds: number): Promise<void> {
+ return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
diff --git a/app/src/styles.css b/app/src/styles.css
index b01abbcb..6ca61791 100644
--- a/app/src/styles.css
+++ b/app/src/styles.css
@@ -210,7 +210,13 @@ body {
background-position: 100% 0;
background-clip: text;
-webkit-background-clip: text;
- color: transparent;
+ /*
+ * THE GLYPH FILL, NOT `color`. This was `color: transparent`, which blanked the gradient too —
+ * `currentColor` resolves against this element's own `color` — so nothing was ever drawn. This
+ * rule is unlayered and beats the `text-*` utility it is given, so the reduced-motion branch
+ * below, which puts `color` back, was the only place the text was readable.
+ */
+ -webkit-text-fill-color: transparent;
animation: tool-line-sweep 1.6s linear infinite;
}
diff --git a/app/tests/join-thread.test.ts b/app/tests/join-thread.test.ts
new file mode 100644
index 00000000..32ed69c4
--- /dev/null
+++ b/app/tests/join-thread.test.ts
@@ -0,0 +1,123 @@
+import { describe, expect, test } from "bun:test";
+import { joinWithin } from "../src/lib/copilot/join-thread";
+
+/** Joining must be FINISHED when it resolves, not merely given up on. */
+
+/** A promise with its settle functions, for driving an await from the test. */
+function deferred<T = void>() {
+ let resolve!: (value: T) => void;
+ let reject!: (reason: unknown) => void;
+ const promise = new Promise<T>((settle, fail) => {
+ resolve = settle;
+ reject = fail;
+ });
+ return { promise, resolve, reject };
+}
+
+/** Let every already-settled microtask run, so "has it resolved yet" is a fair question. */
+const settleMicrotasks = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe("joinWithin", () => {
+ test("leaves the connect alone when it lands inside the deadline", async () => {
+ const connect = deferred();
+ let detached = 0;
+
+ const joined = joinWithin({
+ connect: connect.promise,
+ deadline: new Promise<void>(() => {}),
+ detach: async () => {
+ detached += 1;
+ },
+ });
+
+ connect.resolve();
+ await joined;
+
+ expect(detached).toBe(0);
+ });
+
+ test("ends the connect when the deadline passes first", async () => {
+ const connect = deferred();
+ const deadline = deferred();
+ let detached = 0;
+
+ const joined = joinWithin({
+ connect: connect.promise,
+ deadline: deadline.promise,
+ detach: async () => {
+ detached += 1;
+ connect.resolve();
+ },
+ });
+
+ deadline.resolve();
+ await joined;
+
+ expect(detached).toBe(1);
+ });
+
+ test("waits for the ended connect to finish before saying the join is over", async () => {
+ const connect = deferred();
+ const deadline = deferred();
+ let done = false;
+
+ const joined = joinWithin({
+ connect: connect.promise,
+ deadline: deadline.promise,
+ detach: async () => {},
+ }).then(() => {
+ done = true;
+ });
+
+ deadline.resolve();
+ await settleMicrotasks();
+ // Detach asked for, connect not back yet. Returning here is what loses the next message.
+ expect(done).toBe(false);
+
+ connect.resolve();
+ await joined;
+ expect(done).toBe(true);
+ });
+
+ test("is over, not thrown, when the connect fails", async () => {
+ const connect = deferred();
+ let detached = 0;
+
+ const joined = joinWithin({
+ connect: connect.promise,
+ deadline: new Promise<void>(() => {}),
+ detach: async () => {
+ detached += 1;
+ },
+ });
+
+ connect.reject(new Error("socket refused"));
+
+ expect(await joined.then(() => "resolved")).toBe("resolved");
+ expect(detached).toBe(0);
+ });
+
+ test("still waits out the connect when the detach itself fails", async () => {
+ const connect = deferred();
+ const deadline = deferred();
+ let done = false;
+
+ const joined = joinWithin({
+ connect: connect.promise,
+ deadline: deadline.promise,
+ detach: async () => {
+ throw new Error("nothing to detach");
+ },
+ }).then(() => {
+ done = true;
+ });
+
+ deadline.resolve();
+ await settleMicrotasks();
+ expect(done).toBe(false);
+
+ connect.reject(new Error("aborted"));
+ await joined;
+ expect(done).toBe(true);
+ });
+});
diff --git a/app/tests/transcript-messages.test.ts b/app/tests/transcript-messages.test.ts
index 2d2f55c6..3e7fe695 100644
--- a/app/tests/transcript-messages.test.ts
+++ b/app/tests/transcript-messages.test.ts
@@ -1,3 +1,4 @@
+import type { Message } from "@ag-ui/core";
import { describe, expect, test } from "bun:test";
import {
seedMessage,
@@ -12,6 +13,11 @@ import {
const SEED = seedMessage("what is our refund policy?", "seed-1");
const STORED = seedMessage("what is our refund policy?", "stored-1");
+const REPLY: Message = {
+ id: "reply-1",
+ role: "assistant",
+ content: "Thirty days, and we pay return shipping.",
+};
describe("transcriptMessages", () => {
test("shows the seed while the agent has nothing", () => {
@@ -22,6 +28,16 @@ describe("transcriptMessages", () => {
expect(transcriptMessages([STORED], SEED)).toEqual([STORED]);
});
+ // A reply with no user turn in front of it means the seed is the only copy left, not that it
+ // has been superseded.
+ test("keeps the seed when the agent holds only a reply", () => {
+ expect(transcriptMessages([REPLY], SEED)).toEqual([SEED, REPLY]);
+ });
+
+ test("drops the seed once a user turn stands alongside the reply", () => {
+ expect(transcriptMessages([STORED, REPLY], SEED)).toEqual([STORED, REPLY]);
+ });
+
test("shows nothing for an empty channel with no seed", () => {
expect(transcriptMessages([], null)).toEqual([]);
});