Relay handoff answers home, show working channels, and open the app to the keyboard (#290)

* Gate first sign-in behind a per-user onboarding wizard

Two columns on users say where somebody is in first-run onboarding and
when they finished; /api/me carries the status and one POST moves it.
The app redirects an unfinished user to /onboarding — an animated
three-step wizard — and an address the build does not know now goes
home through the same gate instead of a bare 404.

* Say work is offered aloud, so a sweep can start now instead of at its next poll

The handoff queue was swept every two seconds, and a person is waiting through
every hop, so each leg of a handoff cost up to a full interval doing nothing.
Offering work now fires pg_notify with the kind as payload, inside the offering
transaction where there is one so it fires on commit and never before, and any
replica can listen on a dedicated connection and kick its sweep immediately.

A notification is a latency optimisation, never a delivery mechanism: one lost
in transit costs up to one poll interval, not the work, and the queue's tables
stay the only truth.

* Let a channel tell its members a turn is running in it

A transient busy flag on the channel activity event, announced and never
written: busy is a moment, not a fact about the channel, and a missed signal
costs at most a stuck-looking dot until the next real event, never data.

Two ways in. The server signals by thread (signalBusy) for the runs it can see
— the runtime's lock acquire and release now carry an onRunBusy seam, so every
run the platform processes lights its channel, including one whose tab has
navigated away — and a scratch thread maps to no channel and signals nowhere,
which is the point of a scratch thread. The browser signals by channel
(POST /:channelId/busy) for the one thing the server cannot see, a person's own
turn beginning, with a membership check so belonging to a channel is not
something an outsider can probe for.

* Relay a handoff answer back into the conversation that asked

A forward hop used to answer in the addressed Bot's own channel with the
person: two conversations for one question, and the answer landed somewhere
they never asked anything. Now the hop runs in a scratch thread of the
addressed Bot's own — minted per hop, never mapped to a channel, never shown —
and what it said comes home through a second queued hop that has the asking
Bot relay the answer, attributed, in the conversation the person is watching.

The delivery gathers the Bot's words from the stream as it goes past, because
the runner publishes the turn to the platform and the events are the one
chance to hear it. The relay rides the same durable queue as the turn that
produced it, so a pod dying between the two loses the relay to a retry rather
than for ever; the answerIn marker that stops a failure notice recursing stops
a relay relaying. Answers are clipped at 12k characters so a Bot that comes
back with a book cannot swamp the relaying run's prompt, and a backwards hop
reads only the tail of the asking conversation so relaying never grows slower
with the channel.

Wired in index.ts: the scratch thread replaces the direct-channel answerIn,
the roster announcement resolves thread to channel and happens only when the
turn said something, the asking channel is lit while a forward hop runs, and
the queue's new offered-work notification kicks the sweep so a person is not
waiting out a poll interval per leg.

* Show a channel working on the roster while a turn runs in it

Three bouncing dots badged on the channel's avatar, driven by the busy flag on
the activity socket. Socket-only and transient on the summary type: the roster
query never returns it, so it is undefined until a busy event arrives and drops
whenever the roster refetches — the acceptable failure for a hint about a
moment. The event patcher flips only the busy field: the spread that serves
ordinary activity would carry the event's null message onto the row and wipe
the preview, and busy is not activity, so the row does not re-sort either.

The channel reports its own turns over the new busy endpoint, fire-and-forget,
and deliberately does not clear on unmount: a turn keeps running server-side
after the person leaves the channel, and the server clears it when the run's
lock is released.

* Keep an open channel current with turns nobody here streamed

A relayed handoff answer runs on the server and lands in the thread with no
browser attached; the transcript restored history once, on mount, and would
show the new turn only after leaving and coming back. The chat now watches the
roster's own channel-list cache — the sidebar updating and the transcript
refreshing are one signal and cannot drift apart — and when this channel's
lastMessageAt advances to a moment a Bot authored, the durable history is read
again and messages whose ids the transcript has never seen are appended.
Appended by id, not compared by length, because the stored read keeps only what
the platform can parse and can be shorter than the screen while still holding
the news. Retried briefly, since the roster is patched when the turn is on
record with the runner and the platform's read can be a beat behind.

The chat also reports its own turns to the busy endpoint, keyed on whether a
turn is in flight, so the roster's working dots cover the one run the server
cannot see begin.

* Start a new chat from anywhere with Shift+N

A small hotkey registry, one place on purpose: the binding a listener matches
against and the combo the settings page shows are the same record, so the list
under Preferences is what the keys actually do rather than what somebody
remembered they did — each key drawn as its own keycap, symbols on a Mac and
names elsewhere. Matching is exact rather than at-least, so Shift+N does not
fire on Cmd+Shift+N and shadow whatever the browser means by it, and a plain
Shift+letter combo is left alone while the focus is anywhere editable.

Bound in _authed rather than _app, so a person on settings or admin can start
a chat without first clicking back into the app frame. The new-channel
composer's recipient picker takes focus on arrival, so Shift+N then typing a
name is one motion.

* Format the onboarding route

The wizard shipped unformatted; biome's own output, no hand edits.

* Read the asking conversation before taking the run's lock

The history read is the one call in a delivery that throws on a platform
error, and it sat after the lock was acquired but before the try whose finally
gives the lock back: a 500 from the platform leaked the lock for its full TTL.
On a forward hop that lock is a scratch thread and the leak costs nothing; on
a relay it is the asking conversation itself, so the person could not type for
two minutes, the retry a minute later collided with the hop's own leftover
hold and spent an attempt on it, and a relay that ran out of attempts vanished
without a notice.

The read is of the conversation that asked, which the lock — taken on the
conversation being answered in — never protected. Hoisted above the acquire it
fails before anything is held, and the happy path holds the lock for less of
the turn too. Raised by kevin9327 on #290, who had the same reordering up as
#305 against main; a test now pins the ordering.

* Refetch the roster as well as the user when onboarding completes

Finishing the wizard navigates straight into the app, and the channel list —
cached from before the wizard, or from a fetch that ran while it held the
screen — could greet the person with an empty sidebar their reload then fixed.
Seen once on a real deployment during review of #290 and not cleanly
reproduced, so this is a hardening of the seam rather than a confirmed fix:
both invalidations use refetchType "all" for the same reason, nothing is
observing these queries while the wizard is up.

* Say which wizard agents are examples, and unstick its two classes

Two review findings on the wizard's roster step. The invented agents that top
up a sparse deployment rendered identically to real ones, so "Support Agent"
read as a Bot the deployment has; they are dimmed and labelled Example now.
And max-w-lg had run together with overflow-hidden into a class that applied
neither, which is why the roster cards drew wider than every other step.

Also stops the onboarding store's comment promising that step is where the
wizard resumes: it is stored and served but nothing resumes from it yet, and
the comment now says so instead of describing a behaviour that does not
exist.

* Say in the changelog what changed, including reversing 0.0.5's relay stance

Five user-visible changes were on this branch with no entry: the relay, the
working indicator, the transcript catch-up, the onboarding wizard, and
Shift+N. Worse, 0.0.5's notes promised the asking Bot does not relay text on
the addressed Bot's behalf, and this branch makes it do exactly that — so
somebody upgrading off those notes got the opposite of what they were told.
The Unreleased section now names the reversal outright, and the 0.0.5
paragraph carries a pointer forward rather than standing uncorrected.

* Give the queue's wake-up listener back on the way out, like its siblings

`startWorkOfferedListener` holds a Postgres connection for the life of the process and returns a
`stop()` for giving it back, and the return value was dropped on the floor. The shutdown beside it
stops the two listeners either side and says why in its own comment: "so a watch-mode restart does
not leave two behind on every reload". This one was the third, and it was the one not stopped, so
every reload of `bun run dev` on a deployment with handing work between Bots switched on left a
connection behind.

Held at module scope because the listener is started inside the gate that may never run, and the
shutdown is at the top level: undefined there means a deployment with the capability off, which
never started one.

Checked rather than assumed: `pg_stat_activity` goes from one row to two when the listener starts
and back to one after `stop()`.

* Say in the README that this is a template to clone, not a product

The framing existed only in a code comment ("OpenBot exists to be forked"), which is the wrong place
for the first thing somebody needs to know: that there is nothing to sign up for, nothing to install
as a dependency, and that the example tenant package is a worked example to replace rather than a
default to keep. Read without it, "Quick start" looks like the way you use OpenBot rather than the
way you try the starting point before making it yours.

Placed above the alpha and laptop callouts because it frames both.

* Add a setup prompt for somebody doing this with an AI, and link it from the README

Reported as hard to set up even with an assistant helping, and the reason is legible in
`.env.example`: it ships ten empty keys, and only three of them are a person's to fill. The start
script defaults two and generates the third, so an assistant reading the file alone will walk
somebody through seven values that fill themselves.

`prompt.txt` says which three, what each start-up refusal means in the words the server actually
prints, and what an assistant must not do on somebody's behalf: run the browser sign-in, echo their
keys back, or change the Intelligence URLs, which are correct as shipped and not self-serve to
replace.

Every claim in it was checked against this repository rather than written from memory: the pinned
Bun version, the port defaults, the five refusal messages quoted verbatim, and that
TENANT_PACKAGE_DIR is relative to `server/` rather than the root, which is why the default carries
a `../` that is easy to drop.

---------

Co-authored-by: David McKay <davidmckayv@users.noreply.github.com>

Author: guidovizoso

CHANGELOG.md

@@ -8,6 +8,34 @@ Newest first. `Unreleased` is what is on `main` and not yet tagged.
 
 ## Unreleased
 
+### A Bot's answer comes back to the conversation that asked
+
+**This reverses what 0.0.5 shipped.** The 0.0.5 notes below say the asking Bot does not relay text
+on the addressed Bot's behalf, and the answer lands in that Bot's own conversation. In practice
+that meant reading the answer somewhere you never asked anything, so it is now the other way
+around: the addressed Bot works in a scratch conversation nobody is shown, and the asking Bot
+relays what came back — attributed by name — into the conversation you are watching. What you read
+is the asking Bot's account of the answer rather than the answer verbatim; very long answers are
+clipped to keep the relay itself from failing.
+
+### Channels say when a Bot is working in them
+
+A channel whose Bot is mid-turn shows a working indicator on its roster avatar — including turns no
+browser started, such as a handoff running on the server or a routine. An open conversation also
+picks up turns that arrived while nobody here streamed them, so a relayed answer appears without
+leaving and coming back.
+
+### First sign-in gets an onboarding wizard
+
+A new person lands in a short welcome wizard before the app; everyone who signed in before this
+upgrade is stamped as already onboarded by the migration and sees nothing.
+
+### Shift+N starts a new chat from anywhere
+
+Bound across the signed-in app, shown under **Settings → Keyboard shortcuts**, and inert while you
+are typing in a field. Handoff work is also picked up the moment it is queued rather than at the
+next poll, so an answer's round trip no longer pays up to two seconds per leg.
+
 ### A Bot's shell can no longer reach the embedded database without a password
 
 In the all-in-one image the cluster was `trust`-auth on loopback, and the Bot's shell runs in the
@@ -113,9 +141,10 @@ separately in #287.
 A Bot asked something it is not the right Bot for can now put the question to one that is. The
 addressed Bot answers **as itself, in its own conversation**, with its own tools and its own
 knowledge. The asking Bot does not relay text on its behalf, so what you read is the answer that
-Bot actually gave rather than another Bot's summary of it. The asking conversation records that the
-question was put and to whom. A Bot that judges no other Bot will do can instead reach the person
-who asked it.
+Bot actually gave rather than another Bot's summary of it. *(Reversed since: see Unreleased — the
+answer is now relayed back into the conversation that asked.)* The asking conversation records
+that the question was put and to whom. A Bot that judges no other Bot will do can instead reach
+the person who asked it.
 
 **No Bot may address any other until an administrator says so.** Which Bot may reach which is an
 ordinary grant, made per Bot on that Bot's own screen under **Bots it may ask**, and a Bot with no

README.md

@@ -25,6 +25,8 @@ your own machine.
 
 </div>
 
+> **A template, not a product.** OpenBot is meant to be cloned and made your own. There is no hosted version to sign up for, and nothing here is published as a package to depend on: every workspace in this repository is private. You take the repository, replace the example tenant package under `examples/` with your own coworkers, channels and skills, and run it. Everything below describes a starting point, not a finished thing somebody operates for you.
+
 > **Alpha, and under active development.** OpenBot is early. Expect rough edges and bugs, and expect things to move. Issues and pull requests are welcome.
 
 > **Runs on your machine.** Everything below is written for a laptop. `.env.example` carries `OPENBOT_SINGLE_USER=true`, which admits every request as one administrator, so a fresh clone reaches the product without registering an OAuth client first. [Sign-in](#sign-in) turns that off, and is required before anybody else can reach the deployment.
@@ -57,6 +59,11 @@ A Bot is any endpoint speaking [AG-UI](https://github.com/ag-ui-protocol/ag-ui),
 
 ## Quick start
 
+> **Setting up with an AI assistant?** Paste [`prompt.txt`](prompt.txt) into it first. It carries the
+> same steps as below plus the things that are easy to get wrong: which of the ten blank keys in
+> `.env.example` are actually yours to fill (three), which the start script generates for you, and
+> what each start-up refusal means. Every claim in it is checked against this repository.
+
 1. Create `.env`:
 
    ```sh

app/package.json

@@ -21,6 +21,7 @@
     "@shadcn/react": "^0.3.0",
     "@tabler/icons-react": "^3.36.1",
     "@tanstack/react-form": "^1.33.5",
+    "@tanstack/react-hotkeys": "^0.10.0",
     "@tanstack/react-query": "^5.101.4",
     "@tanstack/react-router": "^1.170.27",
     "better-auth": "^1.6.27",
@@ -31,6 +32,7 @@
     "prompt-area": "^0.6.3",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
+    "react-use-measure": "^2.1.7",
     "shadcn": "^4.17.0",
     "streamdown": "^2.5.0",
     "tailwind-merge": "^3.6.0",

app/src/components/app-sidebar/app-sidebar.tsx

@@ -199,6 +199,7 @@ function ChannelRow({
         }
         pinned={channel.pinned}
         unread={unread}
+        busy={channel.busy ?? false}
       />
     </motion.div>
   );

app/src/components/app-sidebar/channel.tsx

@@ -43,6 +43,7 @@ export const Channel = memo(function Channel({
   lastMessageAt,
   pinned,
   unread,
+  busy,
 }: {
   channelId: string;
   participantIds: string[];
@@ -51,6 +52,7 @@ export const Channel = memo(function Channel({
   lastMessageAt?: string;
   pinned: boolean;
   unread: boolean;
+  busy: boolean;
 }) {
   const queryClient = useQueryClient();
   const navigate = useNavigate();
@@ -110,7 +112,11 @@ export const Channel = memo(function Channel({
             }}
           >
             <div className="">
-              <ChannelAvatar participantIds={participantIds} size={32} />
+              <ChannelAvatar
+                participantIds={participantIds}
+                size={32}
+                typing={busy}
+              />
             </div>
             <div className="flex-col min-w-0 flex-1">
               <div className="flex flex-row items-center justify-between gap-2">

app/src/components/channels/avatar.tsx

@@ -1,56 +1,81 @@
 import Avatar from "boring-avatars";
 import { memo } from "react";
+import { cn } from "@/lib/utils";
 
 /**
  * Memoized roster avatar. Row updates usually change preview/timestamp only, and
  * `use-channel-events` preserves participant id arrays for unchanged rows.
  *
  * `size-full` opts the generated SVG out of ancestor icon selectors such as
  * `[&_svg:not([class*='size-'])]:size-4`.
+ *
+ * `typing` overlays a working indicator at the bottom-right — three bouncing dots, so a channel
+ * whose agent is mid-turn reads as busy from the roster without moving the row's layout.
  */
 export const ChannelAvatar = memo(function ChannelAvatar({
   participantIds,
   size = 32,
+  typing = false,
 }: {
   participantIds: string[];
   size?: number;
+  typing?: boolean;
 }) {
   const channelSize = participantIds?.length;
 
-  if (channelSize === 1) {
-    return (
-      <div className="" style={{ height: size, width: size }}>
-        <Avatar className="size-full" name={participantIds[0]} size={size} />
-      </div>
-    );
-  }
-
-  const firstThree = participantIds.slice(0, 3);
-
-  return (
-    <div
-      className="flex flex-row items-center"
-      style={{ height: size, width: size }}
-    >
-      {firstThree.map((c, i) => {
-        return (
+  const avatar =
+    channelSize === 1 ? (
+      <Avatar className="size-full" name={participantIds[0]} size={size} />
+    ) : (
+      <div className="flex flex-row items-center size-full">
+        {participantIds.slice(0, 3).map((c, i, shown) => (
           <div
-            key={c}
             className="shrink-0 border-2 border-sidebar rounded-full flex items-center justify-center"
+            key={c}
             style={{
-              height: size / (firstThree.length / 2),
-              width: size / (firstThree.length / 2),
+              height: size / (shown.length / 2),
+              width: size / (shown.length / 2),
               transform: `translateX(${i * -75}%)`,
             }}
           >
             <Avatar
               className="size-full"
               name={c}
-              size={size / (firstThree.length / 2)}
+              size={size / (shown.length / 2)}
             />
           </div>
-        );
-      })}
+        ))}
+      </div>
+    );
+
+  return (
+    <div className="relative" style={{ height: size, width: size }}>
+      {avatar}
+      {typing ? <TypingBadge /> : null}
     </div>
   );
 });
+
+/**
+ * Three bouncing dots in a small badge, ringed in the sidebar's own colour so it sits on the
+ * avatar as a badge rather than floating over it. The staggered negative delays start each dot at
+ * a different point in the same bounce, which is what makes the three read as one wave.
+ */
+function TypingBadge() {
+  return (
+    <div className="absolute -bottom-0.5 -right-0.5 flex items-center gap-0.5 rounded-full bg-sidebar p-0.5 ring-2 ring-sidebar">
+      <span className="sr-only">Working…</span>
+      <Dot className="[animation-delay:-0.3s]" />
+      <Dot className="[animation-delay:-0.15s]" />
+      <Dot />
+    </div>
+  );
+}
+
+function Dot({ className }: { className?: string }) {
+  return (
+    <span
+      className={cn("size-1 rounded-full bg-primary animate-bounce", className)}
+    />
+  );
+}

app/src/components/channels/channel-chat.tsx

@@ -14,15 +14,23 @@ import {
   transcriptMessages,
 } from "@/components/channels/transcript-messages";
 import { agentListQueryOptions } from "@/lib/agents/queries";
-import { recordChannelActivityMutationOptions } from "@/lib/channels/mutations";
-import type { AgentChannel } from "@/lib/channels/queries";
+import {
+  recordChannelActivityMutationOptions,
+  setChannelBusyMutationOptions,
+} from "@/lib/channels/mutations";
+import {
+  type AgentChannel,
+  type ChannelSummary,
+  channelKeys,
+} 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 { readThreadMessages } from "@/lib/copilot/thread-messages";
 import { useSkillCommands } from "@/lib/plugins/skill-commands";
+import { queryClient } from "@/query-client";
 import { newId } from "../../lib/new-id";
 
 /**
@@ -182,6 +190,73 @@ export function ChannelChat({
     };
   }, [copilotkit, agent, isReady, channel.threadId, runtimeAgentId]);
 
+  /*
+   * A turn nobody here streamed, surfaced while the channel is open.
+   *
+   * A relayed handoff answer runs on the server and lands in this thread with no browser attached.
+   * The roster hears about it — the activity socket patches the channel-list cache — but this
+   * transcript restores history once, on mount, and would show the new turn only after leaving and
+   * coming back. So it watches that same cache: when this channel's `lastMessageAt` advances to a
+   * moment a Bot authored, the durable history is read again. Riding the roster's own cache rather
+   * than a second subscription means "the sidebar updated" and "the transcript refreshes" are the
+   * one signal, and cannot drift apart.
+   *
+   * APPENDED BY ID, NOT COMPARED BY LENGTH. The stored history is not the local transcript: it
+   * keeps only what `readableTurns` can parse, and the local side keeps tool lines the platform
+   * does not hand back — so after a headless turn the stored read can be shorter than the screen
+   * and still hold the news. What is new is exactly the messages whose ids this transcript has
+   * never seen; appending them leaves everything local intact, and this tab's own turns echo back
+   * with ids already on screen and append nothing.
+   *
+   * Retried briefly, because the roster is patched when the turn is on record with the runner and
+   * the platform's read of the thread can be a beat behind it.
+   */
+  useEffect(() => {
+    const authoredAt = () => {
+      const cache = queryClient.getQueryData<{
+        pages: { channels: ChannelSummary[] }[];
+      }>(channelKeys.list());
+      const summary = cache?.pages
+        .flatMap((page) => page.channels)
+        .find((row) => row.id === channel.id);
+      // Only a Bot's turn is news here; a person's own line arrives through the run that sent it.
+      if (!summary || summary.lastMessageAgentId === null) return null;
+      return summary.lastMessageAt;
+    };
+
+    let lastSeen = authoredAt();
+
+    const pull = () => {
+      void (async () => {
+        for (const delayMs of [0, 750, 1500]) {
+          if (delayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+          }
+          const stored = await readThreadMessages(
+            channel.threadId,
+            runtimeAgentId,
+          );
+          const current = agentRef.current;
+          const seen = new Set(current.messages.map((message) => message.id));
+          const fresh = stored.messages.filter(
+            (message) => !seen.has(message.id),
+          );
+          if (fresh.length === 0) continue;
+          current.setMessages([...current.messages, ...fresh]);
+          return;
+        }
+      })();
+    };
+
+    return queryClient.getQueryCache().subscribe(() => {
+      const at = authoredAt();
+      if (at && at !== lastSeen) {
+        lastSeen = at;
+        pull();
+      }
+    });
+  }, [channel.id, channel.threadId, runtimeAgentId]);
+
   // Tool calls from this conversation act on this coworker's own computer.
   useActiveBot(runtimeAgentId);
 
@@ -222,6 +297,24 @@ export function ChannelChat({
    * Tell the roster what was just said. Failures here must not block the conversation.
    */
   const recordActivity = useMutation(recordChannelActivityMutationOptions());
+
+  /*
+   * Show this channel as working on the roster while its own turn runs.
+   *
+   * The server cannot see a person's turn begin — the runtime does not tell it — so the browser
+   * reports it, keyed on whether a turn is in flight. The server broadcasts it to every member, so
+   * the row shows the dots even on a tab that has since navigated elsewhere; a run that outlives
+   * this tab clears itself when the roster next refetches, which is the acceptable failure for a
+   * transient hint. Not cleared on unmount on purpose: a turn keeps running server-side after the
+   * person leaves the channel, and clearing here would drop the indicator while the work goes on.
+   */
+  const setBusy = useMutation(setChannelBusyMutationOptions());
+  const busy = turnsInFlight > 0;
+  // Keyed on the busy transition alone; `setBusy.mutate` is a stable handle, not a dependency.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: firing on the busy transition only.
+  useEffect(() => {
+    setBusy.mutate({ channelId: channel.id, busy });
+  }, [busy, channel.id]);
   const report = (text: string, agentId: string | null) => {
     const trimmed = text.trim();
     if (!trimmed) return;