canopy-ui 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopy-ui",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "repository": {
     "type": "git",

package/src/chat/ChatPanel.pending.test.tsx

@@ -15,7 +15,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { cleanup, render, screen } from "@testing-library/react";
 
 import { ChatPanel } from "./ChatPanel";
-import type { Message, SessionState } from "./protocol";
+import type { Message, SessionState, TurnStatus } from "./protocol";
 
 afterEach(cleanup);
 
@@ -134,3 +134,81 @@ describe("the pending-reply row", () => {
     expect(screen.queryByText("no messages yet")).toBeNull();
   });
 });
+
+function status(over: Partial<TurnStatus> = {}): TurnStatus {
+  return {
+    state: "working",
+    agent_slug: "hal",
+    runners: ["jj-mbp"],
+    claimed_by: "jj-mbp",
+    pinned: false,
+    cloud_runner: null,
+    cloud_runner_id: null,
+    last_seen_at: null,
+    menu_pending: false,
+    settled: false,
+    stuck: false,
+    ...over,
+  };
+}
+
+describe("the server's turn status", () => {
+  it("replaces the spinner with a reason when nothing will pick the turn up", () => {
+    // The regression the whole projection exists for. A client cannot know
+    // this: it pressed send, and from here an offline runner and a slow one
+    // are identical.
+    panel({
+      state: state({
+        turn_status: status({ state: "waiting_runner", stuck: true, claimed_by: null }),
+      }),
+      awaitingReply: true,
+    });
+    expect(screen.queryByTestId("pending-reply")).toBeNull();
+    expect(screen.getByRole("status").textContent).toContain("jj-mbp is offline");
+  });
+
+  it("reads differently when waiting cannot possibly help", () => {
+    panel({
+      state: state({
+        turn_status: status({ state: "unrouted", stuck: true, runners: [], claimed_by: null }),
+      }),
+      awaitingReply: true,
+    });
+    expect(screen.getByRole("status").textContent).toContain("no runner is set up to run hal");
+  });
+
+  it("names the box in the spinner once a runner really has it", () => {
+    panel({ state: state({ turn_status: status({ state: "working" }) }) });
+    expect(screen.getByText("Thinking on jj-mbp…")).not.toBeNull();
+  });
+
+  it("clears a stuck spinner even if the stream frame that ends it never arrived", () => {
+    // `awaitingReply` only clears on a stream frame; a dropped socket used to
+    // leave it spinning forever. The server's settled flag is the backstop.
+    panel({
+      state: state({ turn_status: status({ state: "done", settled: true }) }),
+      awaitingReply: true,
+    });
+    expect(screen.queryByTestId("pending-reply")).toBeNull();
+  });
+
+  it("stays silent when the host has its own, richer banner for the same fact", () => {
+    // canopy's chat page raises <PlacementBanner> here, with buttons to wait
+    // or continue elsewhere. Our sentence underneath would restate it as a
+    // dead end directly below the thing you can actually press.
+    panel({
+      state: state({
+        turn_status: status({ state: "waiting_runner", stuck: true, claimed_by: null }),
+      }),
+      banner: <div>continue on another runner?</div>,
+    });
+    expect(screen.queryByRole("status")).toBeNull();
+    expect(screen.getByText("continue on another runner?")).not.toBeNull();
+  });
+
+  it("leaves a blocked agent entirely to the menu", () => {
+    panel({ state: state({ turn_status: status({ state: "blocked", stuck: true }) }) });
+    expect(screen.queryByRole("status")).toBeNull();
+    expect(screen.queryByTestId("pending-reply")).toBeNull();
+  });
+});

package/src/chat/ChatPanel.tsx

@@ -7,6 +7,7 @@ import { MessageList } from "./MessageList";
 import { PresenceChips } from "./PresenceChips";
 import { SendBox, type PendingAttachment } from "./SendBox";
 import { isDraftIdle, msUntilDraftIdle, type DraftStorage } from "./drafts";
+import { agentHasFloor as computeAgentHasFloor, pendingLabel as computePendingLabel, turnNotice } from "./turnStatus";
 import { useStickyBottom } from "./useStickyBottom";
 
 export interface ChatPanelProps {
@@ -119,19 +120,31 @@ export function ChatPanel({
   // the real runner path, and the only signal was a 12px chip in the header,
   // which on a phone is the far corner of the screen from your thumb.
   //
-  // Two sources, deliberately: `awaitingReply` is client-side and answers
-  // INSTANTLY with no round trip (nothing server-side can — the turn has to be
-  // enqueued, claimed and driven into the agent before anything could report),
-  // and `activity === "working"` keeps it up for the rest of the turn, across
-  // the gaps between the assistant's separate text blocks. `blocked` withdraws
-  // it: an agent waiting on YOU must never render as an agent working.
-  const agentHasFloor =
-    state.activity !== "blocked" &&
-    (awaitingReply || state.activity === "working");
+  // Three sources now, in `turnStatus.ts` — see `agentHasFloor` there for the
+  // order of authority. The server's `turn_status` wins when present because
+  // it is the only one that can say a turn is queued behind an offline box or
+  // routed nowhere at all; `awaitingReply` still covers the instant between
+  // pressing send and the first frame, which nothing server-side can.
+  const status = state.turn_status ?? null;
+  const agentHasFloor = computeAgentHasFloor({
+    status,
+    activity: state.activity,
+    awaitingReply,
+  });
   const showPendingReply = inFlightMessage == null && agentHasFloor;
-  // "Queued" until something reports the agent actually started — the useful
-  // distinction is where the delay is, not that there is one.
-  const pendingLabel = state.activity === "working" ? "Thinking…" : "Queued…";
+  const pendingLabel = computePendingLabel({ status, activity: state.activity });
+  // The sentence for an ask that is going NOWHERE. Rendered instead of the
+  // bubble, never beside it: a spinner over a turn nothing will pick up is the
+  // precise lie this projection exists to remove.
+  //
+  // Suppressed entirely when the host supplies its own `banner`. A host banner
+  // IS this host's richer answer for the same situation — canopy's chat page
+  // raises <PlacementBanner> for an offline runner, with buttons to wait or
+  // continue elsewhere, and <MenuPrompt> for a dialog. Rendering our sentence
+  // underneath would state the same fact twice and put a dead-end restatement
+  // directly below the thing you can actually press. The fallback is for hosts
+  // with no banner of their own, which is exactly the embedded widget.
+  const notice = banner ? null : turnNotice(status);
 
   // Sticky-bottom scroll: dep changes on (a) new message arrival and (b)
   // streaming text growth on the last message. length-only (cheap) instead
@@ -188,7 +201,23 @@ export function ChatPanel({
         onStop={onStop}
         stopState={state.stopState}
         onTakeOver={onTakeOver}
-        banner={banner}
+        banner={
+          notice ? (
+            <p
+              role="status"
+              className={
+                notice.tone === "error"
+                  ? "text-[12px] text-destructive"
+                  : "text-[12px] text-warning"
+              }
+            >
+              {notice.text}
+              {notice.offer ? ` A runner admin can send it to ${notice.offer.name}.` : ""}
+            </p>
+          ) : (
+            banner
+          )
+        }
         disabledReason={disabledReason}
         attachments={attachments}
         onAttach={onAttach}

package/src/chat/agui.fixture.json

@@ -9,12 +9,12 @@
     },
     "agui": [
       {
+        "type": "TEXT_MESSAGE_START",
         "metadata": {
           "canopy": {
             "turn_index": 4
           }
         },
-        "type": "TEXT_MESSAGE_START",
         "messageId": "m1",
         "role": "assistant"
       }
@@ -46,12 +46,12 @@
     },
     "agui": [
       {
+        "type": "TEXT_MESSAGE_END",
         "metadata": {
           "canopy": {
             "plaintext": "hello"
           }
         },
-        "type": "TEXT_MESSAGE_END",
         "messageId": "m1"
       }
     ]
@@ -67,12 +67,12 @@
     },
     "agui": [
       {
+        "type": "TEXT_MESSAGE_CHUNK",
         "metadata": {
           "canopy": {
             "turn_index": 3
           }
         },
-        "type": "TEXT_MESSAGE_CHUNK",
         "messageId": "u1",
         "role": "user",
         "delta": "hi there"
@@ -96,6 +96,7 @@
     },
     "agui": [
       {
+        "type": "TOOL_CALL_START",
         "metadata": {
           "canopy": {
             "turn_index": 5,
@@ -107,7 +108,6 @@
             }
           }
         },
-        "type": "TOOL_CALL_START",
         "toolCallId": "t9",
         "toolCallName": "list_insights",
         "parentMessageId": "m1"
@@ -139,6 +139,7 @@
     },
     "agui": [
       {
+        "type": "TOOL_CALL_RESULT",
         "metadata": {
           "canopy": {
             "turn_index": 6,
@@ -150,7 +151,6 @@
             }
           }
         },
-        "type": "TOOL_CALL_RESULT",
         "messageId": "t9",
         "toolCallId": "t9",
         "content": "[]"
@@ -273,11 +273,27 @@
           7
         ],
         "current_user_id": 7,
-        "menu": null
+        "menu": null,
+        "turn_status": {
+          "state": "working",
+          "agent_slug": "hal",
+          "runners": [
+            "jj-mbp"
+          ],
+          "claimed_by": "jj-mbp",
+          "pinned": false,
+          "cloud_runner": null,
+          "cloud_runner_id": null,
+          "last_seen_at": null,
+          "menu_pending": false,
+          "settled": false,
+          "stuck": false
+        }
       }
     },
     "agui": [
       {
+        "type": "MESSAGES_SNAPSHOT",
         "metadata": {
           "canopy": {
             "frame": {
@@ -320,12 +336,26 @@
                   7
                 ],
                 "current_user_id": 7,
-                "menu": null
+                "menu": null,
+                "turn_status": {
+                  "state": "working",
+                  "agent_slug": "hal",
+                  "runners": [
+                    "jj-mbp"
+                  ],
+                  "claimed_by": "jj-mbp",
+                  "pinned": false,
+                  "cloud_runner": null,
+                  "cloud_runner_id": null,
+                  "last_seen_at": null,
+                  "menu_pending": false,
+                  "settled": false,
+                  "stuck": false
+                }
               }
             }
           }
         },
-        "type": "MESSAGES_SNAPSHOT",
         "messages": [
           {
             "id": "41",
@@ -366,6 +396,51 @@
       }
     ]
   },
+  {
+    "canopy": {
+      "event": "session.turn_status",
+      "data": {
+        "status": {
+          "state": "waiting_runner",
+          "agent_slug": "hal",
+          "runners": [
+            "jj-mbp"
+          ],
+          "claimed_by": null,
+          "pinned": false,
+          "cloud_runner": "cloud-1",
+          "cloud_runner_id": "8f2e",
+          "last_seen_at": null,
+          "menu_pending": false,
+          "settled": false,
+          "stuck": true
+        }
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.session.turn_status",
+        "value": {
+          "status": {
+            "state": "waiting_runner",
+            "agent_slug": "hal",
+            "runners": [
+              "jj-mbp"
+            ],
+            "claimed_by": null,
+            "pinned": false,
+            "cloud_runner": "cloud-1",
+            "cloud_runner_id": "8f2e",
+            "last_seen_at": null,
+            "menu_pending": false,
+            "settled": false,
+            "stuck": true
+          }
+        }
+      }
+    ]
+  },
   {
     "canopy": {
       "event": "session.stop",
@@ -486,6 +561,7 @@
     },
     "agui": [
       {
+        "type": "RUN_ERROR",
         "metadata": {
           "canopy": {
             "frame": {
@@ -497,7 +573,6 @@
             }
           }
         },
-        "type": "RUN_ERROR",
         "message": "runner went away",
         "code": "stream_error"
       }

package/src/chat/index.ts

@@ -13,6 +13,7 @@ export type {
   Participant,
   SessionMenu,
   SessionState,
+  TurnStatus,
   WsAction,
   WsEvent,
 } from "./protocol";
@@ -33,6 +34,17 @@ export {
 } from "./useSessionSocket";
 export { useStickyBottom } from "./useStickyBottom";
 
+// Where the ask stands — the kit's voice for the server-side turn status that
+// Slack, this panel and the embedded widget all render from. Exported because
+// a host may want the same wording outside the panel (a session list, a
+// placement banner) rather than inventing a second vocabulary for it.
+export {
+  agentHasFloor,
+  pendingLabel,
+  turnNotice,
+  type TurnNotice,
+} from "./turnStatus";
+
 // Draft idle helpers
 export { IDLE_THRESHOLD_MS, isDraftIdle, msUntilDraftIdle } from "./drafts";
 

package/src/chat/protocol.ts

@@ -120,6 +120,51 @@ export interface SessionMenu {
   observed_at?: number;
 }
 
+/**
+ * Where the ask this session is waiting on currently stands.
+ *
+ * Computed on the SERVER (`apps/harness/turn_status.py`) and rendered
+ * identically by every channel — a Slack thread, this chat kit, the embedded
+ * widget. It exists because three of its states cannot be derived by a client
+ * at all: its runner is offline, nothing is routed that could run it, the box
+ * it was on died mid-turn. canopy's chat page used to guess at the first by
+ * fetching the whole fleet and matching the runner BY NAME, which failed open
+ * whenever a retired runner was omitted from that list; the widget never had
+ * any of it and simply showed an empty panel.
+ */
+export interface TurnStatus {
+  /** `picking_up` | `waiting_runner` | `unrouted` | `working` | `blocked`
+   *  | `paused` | `done` | `cancelled` | `missed` | `failed` | `lost`.
+   *
+   *  Deliberately a string rather than a union: an older client meeting a
+   *  state a newer server added should fall back to its generic wording, not
+   *  fail to type-check. `settled`/`stuck` are what code should branch on. */
+  state: string;
+  agent_slug: string | null;
+  /** The runners this state is ABOUT — the ones that would pick it up while it
+   *  is queued, or the one holding it. */
+  runners: string[];
+  claimed_by: string | null;
+  /** Directed at this runner rather than offered to the cascade. */
+  pinned: boolean;
+  /** A runner it could be moved to right now, when moving it would help. Only
+   *  ever an offer; acting on it re-checks everything server-side. */
+  cloud_runner: string | null;
+  cloud_runner_id: string | null;
+  /** When the holding runner was last heard from. Only meaningful for
+   *  `paused`, where it is what tells you whether to keep waiting. */
+  last_seen_at: string | null;
+  /** The agent is sitting on a dialog. A separate axis from `state`: a turn
+   *  blocked on a question is still RUNNING as far as the turn is concerned. */
+  menu_pending: boolean;
+  /** Nothing more will happen without someone asking for it. */
+  settled: boolean;
+  /** Nothing is moving and only a person can change that. The one question a
+   *  "waiting on you" surface actually asks — derived once on the server so
+   *  four clients cannot disagree about it. */
+  stuck: boolean;
+}
+
 export interface SessionState {
   messages: Message[];
   /** Live agent activity, from the runner's turn-boundary hooks. Undefined when
@@ -146,6 +191,12 @@ export interface SessionState {
    *  only if it was already connected when the agent blocked — which is exactly
    *  the case that fails, because you go and look BECAUSE it stopped. */
   menu?: SessionMenu;
+  /** Where the ask stands. In the CONNECT SNAPSHOT as well as in live frames,
+   *  for the same reason `menu` is: you open the page BECAUSE it went quiet, so
+   *  the client that most needs this is the one that was not connected when it
+   *  changed. Null/undefined when nothing has been asked on this session yet —
+   *  which is distinct from "finished", and must stay distinct. */
+  turn_status?: TurnStatus | null;
   active_draft: Draft | null;
   participants: Participant[];
   presence_user_ids: number[];
@@ -179,6 +230,13 @@ export type WsEvent =
   // to carry a menu would report an agent as idle or blocked on the wrong one.
   // `menu: null` is the retraction — somebody answered at the keyboard.
   | { event: "session.menu"; data: { menu: SessionMenu | null } }
+  // Where the ask stands, re-derived server-side on every transition. Its own
+  // frame rather than a field on `session.activity`: activity is the runner's
+  // fast hook clock reporting whether the agent is PRODUCING, while this is the
+  // turn's placement in the fleet — they change on different clocks and for
+  // different reasons, and the states that matter most here (queued behind an
+  // offline box, unroutable) are ones activity has no way to spell.
+  | { event: "session.turn_status"; data: { status: TurnStatus | null } }
   // A human typed into emdash rather than into this page. No client echoed it,
   // so this is the only way it reaches the browser before a reload.
   | { event: "chat.user_message"; data: { message_id: string; turn_index: number; plaintext: string } }

package/src/chat/sessionReducer.ts

@@ -105,6 +105,18 @@ export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState
       // retraction, and has to be honoured — somebody answered at the keyboard.
       return { ...prev, menu: frame.data.menu ?? undefined };
 
+    case "session.turn_status":
+      // Wholesale, never merged. The server re-derives the whole status from
+      // the turn on every transition, so a partial update could only ever
+      // describe a state the server does not believe in — and a client that
+      // just connected has no correct prior to merge INTO. Same argument as
+      // the ACP rule in reverse: `tool_call_update` is a patch because it is
+      // specified as one; this is not.
+      //
+      // A null status is a real answer ("nothing has been asked here"), not a
+      // gap to preserve, so it is stored as such.
+      return { ...prev, turn_status: frame.data.status ?? null };
+
     case "chat.user_message": {
       // Someone typed into emdash, OR into this page. Both reach here, and that
       // is why matching on turn_index alone is not enough: a web send writes its

package/src/chat/turnStatus.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest";
+
+import type { TurnStatus } from "./protocol";
+import { agentHasFloor, pendingLabel, turnNotice } from "./turnStatus";
+
+/** A status in the shape the server actually sends (`TurnStatus.as_dict`). */
+function status(over: Partial<TurnStatus> = {}): TurnStatus {
+  return {
+    state: "working",
+    agent_slug: "hal",
+    runners: ["jj-mbp"],
+    claimed_by: "jj-mbp",
+    pinned: false,
+    cloud_runner: null,
+    cloud_runner_id: null,
+    last_seen_at: null,
+    menu_pending: false,
+    settled: false,
+    stuck: false,
+    ...over,
+  };
+}
+
+describe("agentHasFloor", () => {
+  it("shows the bubble the instant you press send, before any frame comes back", () => {
+    // Nothing server-side can answer here yet — the turn is not enqueued.
+    expect(agentHasFloor({ awaitingReply: true })).toBe(true);
+  });
+
+  it("keeps it up across the gaps between an assistant's text blocks", () => {
+    expect(agentHasFloor({ activity: "working", awaitingReply: false })).toBe(true);
+  });
+
+  it("never shows it for an agent waiting on YOU", () => {
+    expect(agentHasFloor({ activity: "blocked", awaitingReply: true })).toBe(false);
+  });
+
+  it("withdraws it once the server says nothing will pick the turn up", () => {
+    // The regression this whole projection exists for: a spinner over an ask
+    // queued behind a closed laptop, which used to spin until the tab closed.
+    const s = status({ state: "waiting_runner", stuck: true, claimed_by: null });
+    expect(agentHasFloor({ status: s, awaitingReply: true })).toBe(false);
+  });
+
+  it("withdraws it for an unroutable turn even while the client still thinks it is waiting", () => {
+    const s = status({ state: "unrouted", stuck: true, runners: [], claimed_by: null });
+    expect(agentHasFloor({ status: s, awaitingReply: true })).toBe(false);
+  });
+
+  it("withdraws it once the turn is settled, even if a stream frame was missed", () => {
+    // `awaitingReply` only clears on a stream frame. A dropped socket used to
+    // leave it true forever; the server's settled flag is the backstop.
+    const s = status({ state: "done", settled: true });
+    expect(agentHasFloor({ status: s, awaitingReply: true })).toBe(false);
+  });
+
+  it("shows it for a queued turn a live runner is taking", () => {
+    expect(agentHasFloor({ status: status({ state: "picking_up" }) })).toBe(true);
+  });
+
+  it("lets the server override a stale client belief that nothing is happening", () => {
+    // Someone else sent on this session from another device.
+    expect(agentHasFloor({ status: status({ state: "working" }), awaitingReply: false })).toBe(true);
+  });
+});
+
+describe("pendingLabel", () => {
+  it("says where the delay IS, not merely that there is one", () => {
+    expect(pendingLabel({ status: status({ state: "picking_up" }) })).toBe(
+      "Picking this up on jj-mbp…",
+    );
+    expect(pendingLabel({ status: status({ state: "working" }) })).toBe("Thinking on jj-mbp…");
+  });
+
+  it("names a pinned runner as a decision, not a queue position", () => {
+    const s = status({ state: "picking_up", pinned: true, runners: ["cloud-1"] });
+    expect(pendingLabel({ status: s })).toBe("Sent to cloud-1…");
+  });
+
+  it("falls back to the coarse wording with no status in hand", () => {
+    expect(pendingLabel({ activity: "working" })).toBe("Thinking…");
+    expect(pendingLabel({})).toBe("Queued…");
+  });
+});
+
+describe("turnNotice", () => {
+  it("says nothing when there is nothing a person needs to do", () => {
+    expect(turnNotice(null)).toBeNull();
+    expect(turnNotice(status({ state: "working" }))).toBeNull();
+    expect(turnNotice(status({ state: "picking_up" }))).toBeNull();
+    expect(turnNotice(status({ state: "done", settled: true }))).toBeNull();
+  });
+
+  it("leaves a blocked agent to the menu, which has buttons", () => {
+    // A sentence beside the dialog would say the same thing twice and compete
+    // with the thing you can actually press.
+    expect(turnNotice(status({ state: "blocked", stuck: true }))).toBeNull();
+  });
+
+  it("names the offline box, because the fix is to go and open it", () => {
+    const n = turnNotice(status({ state: "waiting_runner", stuck: true, claimed_by: null }));
+    expect(n?.tone).toBe("warn");
+    expect(n?.text).toContain("jj-mbp is offline");
+  });
+
+  it("reads differently for the state waiting cannot fix", () => {
+    const n = turnNotice(status({ state: "unrouted", stuck: true, runners: [], claimed_by: null }));
+    // Not a warning you can wait out — an error somebody has to go and fix.
+    expect(n?.tone).toBe("error");
+    expect(n?.text).toContain("no runner is set up to run hal");
+  });
+
+  it("carries the rescue offer when moving it would help", () => {
+    const n = turnNotice(
+      status({
+        state: "waiting_runner",
+        stuck: true,
+        cloud_runner: "cloud-1",
+        cloud_runner_id: "8f2e",
+      }),
+    );
+    expect(n?.offer).toEqual({ name: "cloud-1", id: "8f2e" });
+  });
+
+  it("offers nothing when the server named no runner to move it to", () => {
+    const n = turnNotice(status({ state: "waiting_runner", stuck: true }));
+    expect(n?.offer).toBeNull();
+  });
+
+  it("reports a box that died mid-turn, which the turn itself still calls running", () => {
+    const n = turnNotice(status({ state: "paused", stuck: true }));
+    expect(n?.text).toContain("jj-mbp went offline mid-turn");
+  });
+
+  it("degrades to no notice for a state it has never heard of", () => {
+    // An older client meeting a newer server must fall silent, not crash.
+    expect(turnNotice(status({ state: "some_future_state" }))).toBeNull();
+  });
+});

package/src/chat/turnStatus.ts

@@ -0,0 +1,148 @@
+import type { TurnStatus } from "./protocol";
+
+/**
+ * The chat kit's VOICE for `harness.turn_status` — the counterpart of
+ * `apps/slack/status.py::render`, which says the same eleven states in Slack's
+ * words. The states are computed once on the server; only the wording is here.
+ *
+ * Pure functions, no React, so both the wording and the spinner-vs-statement
+ * decision are unit-testable without mounting a panel.
+ */
+
+/**
+ * Does the agent have the floor — i.e. should a "working on it" bubble show?
+ *
+ * Three sources, in order of authority:
+ *
+ *  1. `status` is the server's answer and wins whenever it exists. It is the
+ *     only one that knows a turn is queued behind an offline box, and the only
+ *     one that survives a reload.
+ *  2. `awaitingReply` is client-side and answers INSTANTLY, with no round trip.
+ *     Nothing server-side can: the turn has to be enqueued before anything
+ *     could report on it. It covers the gap between pressing send and the
+ *     first frame coming back.
+ *  3. `activity` is the runner's hook clock, which keeps the bubble up across
+ *     the gaps between an assistant's separate text blocks.
+ *
+ * A `blocked` agent never has the floor: one waiting on YOU must not render as
+ * one working. Neither does a stuck or settled turn — a spinner over an ask
+ * nothing is going to pick up is the exact lie this whole projection exists to
+ * stop.
+ */
+export function agentHasFloor({
+  status,
+  activity,
+  awaitingReply,
+}: {
+  status?: TurnStatus | null;
+  activity?: "working" | "idle" | "blocked";
+  awaitingReply?: boolean;
+}): boolean {
+  if (activity === "blocked") return false;
+  if (status) {
+    if (status.settled || status.stuck) return false;
+    // `picking_up` and `working` are the two live states, and both mean a
+    // reply is genuinely coming.
+    return true;
+  }
+  return Boolean(awaitingReply) || activity === "working";
+}
+
+/**
+ * The label inside the pending bubble.
+ *
+ * "Queued" vs "Thinking" is the useful distinction — where the delay IS, not
+ * that there is one — and with a status in hand it can name the box, which
+ * turns a spinner into something you can act on when it lasts too long.
+ */
+export function pendingLabel({
+  status,
+  activity,
+}: {
+  status?: TurnStatus | null;
+  activity?: "working" | "idle" | "blocked";
+}): string {
+  if (status?.state === "working") {
+    return status.claimed_by ? `Thinking on ${status.claimed_by}…` : "Thinking…";
+  }
+  if (status?.state === "picking_up") {
+    const [first] = status.runners;
+    if (status.pinned && first) return `Sent to ${first}…`;
+    return first ? `Picking this up on ${first}…` : "Queued…";
+  }
+  return activity === "working" ? "Thinking…" : "Queued…";
+}
+
+export interface TurnNotice {
+  /** `warn` — nothing is moving but waiting may still resolve it.
+   *  `error`  — waiting will never resolve it; something has to change. */
+  tone: "warn" | "error";
+  text: string;
+  /** The runner this could be moved to, when moving it would help. The kit
+   *  only reports the offer; acting on it belongs to the host, which knows
+   *  whether this user may place a turn. */
+  offer: { name: string; id: string } | null;
+}
+
+/**
+ * The sentence for a turn that is going nowhere, or null when there is nothing
+ * a person needs to know.
+ *
+ * Only the states a spinner would MISREPRESENT get one. `picking_up` and
+ * `working` are covered by the bubble; the terminal states are covered by the
+ * reply (or its absence) already being on screen.
+ *
+ * `blocked` deliberately returns null: the dialog itself is the notice, and
+ * the host renders it as a menu with buttons. A sentence beside it would say
+ * the same thing twice and compete with the thing you can actually press.
+ */
+export function turnNotice(status?: TurnStatus | null): TurnNotice | null {
+  if (!status) return null;
+  const offer = status.cloud_runner && status.cloud_runner_id
+    ? { name: status.cloud_runner, id: status.cloud_runner_id }
+    : null;
+  const runners = status.runners.join(", ");
+  switch (status.state) {
+    case "waiting_runner":
+      return {
+        tone: "warn",
+        // Names the box, because the fix is physical: go and open it.
+        text: runners
+          ? `Queued — ${runners} is offline, so nothing is working on this yet. It runs when the runner is back.`
+          : "Queued — its runner is offline, so nothing is working on this yet.",
+        offer,
+      };
+    case "unrouted":
+      return {
+        tone: "error",
+        // The one state waiting cannot fix, and it has to READ differently
+        // from the one waiting can.
+        text: status.agent_slug
+          ? `Queued, but no runner is set up to run ${status.agent_slug} — nothing will pick this up until its routing is fixed.`
+          : "Queued, but no runner is set up to run this — nothing will pick it up until its routing is fixed.",
+        offer,
+      };
+    case "paused":
+      return {
+        tone: "warn",
+        text: status.claimed_by
+          ? `Paused — ${status.claimed_by} went offline mid-turn. It carries on if the runner comes back.`
+          : "Paused — the runner went offline mid-turn.",
+        offer,
+      };
+    case "lost":
+      return {
+        tone: "error",
+        text: status.claimed_by
+          ? `Could not finish — ${status.claimed_by} went away before it was done.`
+          : "Could not finish — the runner went away before it was done.",
+        offer,
+      };
+    case "failed":
+      return { tone: "error", text: "Could not finish.", offer: null };
+    case "missed":
+      return { tone: "warn", text: "Missed — nothing picked it up in time.", offer: null };
+    default:
+      return null;
+  }
+}

package/src/chat/useSessionSocket.ts

@@ -93,6 +93,21 @@ export interface UseSessionSocketResult {
   takeOverDraft: () => void;
   discardDraft: () => void;
   prependMessages: (older: Message[]) => void;
+  /** A message was sent for this session over HTTP rather than through this
+   *  socket — show it, and start waiting for a reply.
+   *
+   *  Two callers need it and both are REST sends: the embedded widget's FIRST
+   *  message (the session does not exist until it is sent, so there is no
+   *  socket to send it on) and every message from a CONTACT (whose socket
+   *  listens only — presence and the co-edited draft are keyed on a user id
+   *  they do not have).
+   *
+   *  Without it those sends changed nothing on screen: `awaitingReply` is set
+   *  by `sendChat` alone, and the user's own line is not a server row until
+   *  the agent's transcript ships it back. So you typed, pressed send, and got
+   *  an empty panel — for as long as the reply took, and forever if its runner
+   *  was offline. */
+  noteLocalSend: (text: string) => void;
   lastError: string | null;
 }
 
@@ -427,6 +442,29 @@ export function useSessionSocket({
     });
   }, []);
 
+  const noteLocalSend = useCallback((text: string) => {
+    setAwaitingReply(true);
+    const body = text.trim();
+    if (!body) return;
+    // Routed through the ordinary `chat.user_message` case rather than a new
+    // one, so the optimistic row goes in with the SAME dedupe the transcript
+    // echo already relies on: when the agent reads the message and the runner
+    // ships it back at its durable composite ordinal, the reducer matches on
+    // recent identical text and merges instead of rendering it twice.
+    setState((prev) =>
+      sessionReducer(prev, {
+        event: "chat.user_message",
+        data: {
+          // Local, and replaced by the server's id the moment the real row
+          // arrives. Namespaced so it can never collide with one.
+          message_id: `local:${Date.now()}`,
+          turn_index: prev.messages.reduce((acc, m) => Math.max(acc, m.turn_index), 0) + 1,
+          plaintext: body,
+        },
+      }),
+    );
+  }, []);
+
   return {
     state,
     connected,
@@ -437,6 +475,7 @@ export function useSessionSocket({
     takeOverDraft,
     discardDraft,
     prependMessages,
+    noteLocalSend,
     lastError,
   };
 }