canopy-ui 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopy-ui",
-  "version": "0.8.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": "[]"
@@ -231,5 +231,425 @@
         }
       }
     ]
+  },
+  {
+    "canopy": {
+      "event": "session.state",
+      "data": {
+        "messages": [
+          {
+            "id": "41",
+            "turn_index": 0,
+            "role": "user",
+            "content": {},
+            "plaintext": "what is stale?",
+            "status": "complete",
+            "error_detail": null,
+            "started_at": null,
+            "completed_at": null,
+            "created_at": "2026-09-18T12:00:00+00:00"
+          },
+          {
+            "id": "42",
+            "turn_index": 1,
+            "role": "assistant",
+            "content": {},
+            "plaintext": "Three insights are.",
+            "status": "complete",
+            "error_detail": null,
+            "started_at": null,
+            "completed_at": null,
+            "created_at": "2026-09-18T12:00:05+00:00"
+          }
+        ],
+        "active_draft": null,
+        "participants": [
+          {
+            "user_id": 7,
+            "role": "editor"
+          }
+        ],
+        "presence_user_ids": [
+          7
+        ],
+        "current_user_id": 7,
+        "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": {
+              "event": "session.state",
+              "data": {
+                "messages": [
+                  {
+                    "id": "41",
+                    "turn_index": 0,
+                    "role": "user",
+                    "content": {},
+                    "plaintext": "what is stale?",
+                    "status": "complete",
+                    "error_detail": null,
+                    "started_at": null,
+                    "completed_at": null,
+                    "created_at": "2026-09-18T12:00:00+00:00"
+                  },
+                  {
+                    "id": "42",
+                    "turn_index": 1,
+                    "role": "assistant",
+                    "content": {},
+                    "plaintext": "Three insights are.",
+                    "status": "complete",
+                    "error_detail": null,
+                    "started_at": null,
+                    "completed_at": null,
+                    "created_at": "2026-09-18T12:00:05+00:00"
+                  }
+                ],
+                "active_draft": null,
+                "participants": [
+                  {
+                    "user_id": 7,
+                    "role": "editor"
+                  }
+                ],
+                "presence_user_ids": [
+                  7
+                ],
+                "current_user_id": 7,
+                "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
+                }
+              }
+            }
+          }
+        },
+        "messages": [
+          {
+            "id": "41",
+            "role": "user",
+            "content": "what is stale?"
+          },
+          {
+            "id": "42",
+            "role": "assistant",
+            "content": "Three insights are."
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "session.page_action",
+      "data": {
+        "id": "9f1c",
+        "name": "scrollToRow",
+        "args": {
+          "id": 4471
+        }
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.session.page_action",
+        "value": {
+          "id": "9f1c",
+          "name": "scrollToRow",
+          "args": {
+            "id": 4471
+          }
+        }
+      }
+    ]
+  },
+  {
+    "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",
+      "data": {
+        "state": "failed"
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.session.stop",
+        "value": {
+          "state": "failed"
+        }
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "session.activity",
+      "data": {
+        "state": "working"
+      }
+    },
+    "agui": [
+      {
+        "type": "ACTIVITY_SNAPSHOT",
+        "messageId": "t1",
+        "activityType": "canopy.session",
+        "content": {
+          "state": "working"
+        },
+        "replace": true
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "session.menu",
+      "data": {
+        "menu": {
+          "source": "hook",
+          "question": "Proceed?",
+          "observed_at": 1758196800,
+          "options": [
+            {
+              "label": "Yes"
+            },
+            {
+              "label": "No"
+            }
+          ]
+        }
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.menu",
+        "value": {
+          "source": "hook",
+          "question": "Proceed?",
+          "observed_at": 1758196800,
+          "options": [
+            {
+              "label": "Yes"
+            },
+            {
+              "label": "No"
+            }
+          ]
+        }
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "session.error",
+      "data": {
+        "code": "draft_conflict",
+        "message": "stale version"
+      }
+    },
+    "agui": [
+      {
+        "type": "RUN_ERROR",
+        "message": "stale version",
+        "code": "draft_conflict"
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "chat.stream_cancelled",
+      "data": {
+        "message_id": "m1",
+        "partial_len": 12
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.chat.stream_cancelled",
+        "value": {
+          "message_id": "m1",
+          "partial_len": 12
+        }
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "chat.stream_error",
+      "data": {
+        "message_id": "m1",
+        "detail": "runner went away"
+      }
+    },
+    "agui": [
+      {
+        "type": "RUN_ERROR",
+        "metadata": {
+          "canopy": {
+            "frame": {
+              "event": "chat.stream_error",
+              "data": {
+                "message_id": "m1",
+                "detail": "runner went away"
+              }
+            }
+          }
+        },
+        "message": "runner went away",
+        "code": "stream_error"
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "draft.committed",
+      "data": {
+        "draft_id": "d1",
+        "user_message_id": "u2"
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.draft.committed",
+        "value": {
+          "draft_id": "d1",
+          "user_message_id": "u2"
+        }
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "draft.discarded",
+      "data": {
+        "draft_id": "d1"
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.draft.discarded",
+        "value": {
+          "draft_id": "d1"
+        }
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "draft.lock_changed",
+      "data": {
+        "draft_id": "d1",
+        "holder_user_id": 7,
+        "expires_at": "2026-09-18T12:01:00+00:00"
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.draft.lock_changed",
+        "value": {
+          "draft_id": "d1",
+          "holder_user_id": 7,
+          "expires_at": "2026-09-18T12:01:00+00:00"
+        }
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "page.invalidate",
+      "data": {
+        "uri": "item://"
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.page.invalidate",
+        "value": {
+          "uri": "item://"
+        }
+      }
+    ]
   }
 ]

package/src/chat/agui.test.ts

@@ -277,7 +277,11 @@ describe('the socket actually asks for it', () => {
   it('is wired to the hook’s public option', () => {
     const source = hookSource()
 
-    expect(source).toContain('protocol=ag-ui')
+    // NOT `expect(source).toContain('protocol=ag-ui')`, which this used to say.
+    // It held the whole time the flag was being dropped by any URL builder that
+    // ignores its path — i.e. by canopy-web's widget and by ace-web. Whether the
+    // flag reaches the socket is asserted where it can be seen, against the URL
+    // a socket really opens: `useSessionSocket.protocol.test.tsx`.
     expect(source).toContain('fromAgui')
     // And the default stays canopy's own vocabulary, which is what lets an
     // existing consumer — ace-web installs this package from npm — notice