canopy-ui 0.8.0 → 0.10.0

package/src/chat/agui.ts

@@ -65,6 +65,19 @@ export function fromAgui(frame: AguiFrame): WsEvent[] {
   const type = typeof frame.type === "string" ? frame.type : "";
   const m = meta(frame);
 
+  // The server's own frame, when it sent one. Where the AG-UI spelling is lossy
+  // for canopy — a run error with no slot for which message failed, a messages
+  // snapshot with none for drafts, presence or a pending dialog, an interrupt
+  // that re-encodes the menu — the original rides under `metadata.canopy.frame`
+  // (`_verbatim` in agui.py), and returning it beats rebuilding it: a rebuilt
+  // frame carries whatever this function guessed, not what the server said.
+  // One rule for every such event, so a newly lossy projection needs no new case
+  // here — which is how the connect snapshot went missing in the first place.
+  const original = m.frame;
+  if (original && typeof original === "object" && typeof (original as WsEvent).event === "string") {
+    return [original as WsEvent];
+  }
+
   switch (type) {
     case "TEXT_MESSAGE_START":
       return [

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.protocol.test.tsx

@@ -0,0 +1,124 @@
+// @vitest-environment jsdom
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { useSessionSocket, withAguiProtocol } from './useSessionSocket'
+
+/**
+ * What the socket REALLY opens, and what it does with what comes back.
+ *
+ * This replaced an assertion that the hook's source contained `protocol=ag-ui`.
+ * That was true the whole time the flag was being dropped: the hook put it on
+ * the PATH it handed the caller's URL builder, and two of the first three
+ * builders ignore their path. Only opening a socket and reading its URL can see
+ * that — so that is what these do.
+ */
+
+class FakeSocket {
+  static opened: FakeSocket[] = []
+  onopen: (() => void) | null = null
+  onmessage: ((e: { data: string }) => void) | null = null
+  onclose: (() => void) | null = null
+  onerror: (() => void) | null = null
+  readyState = 0
+  constructor(public url: string) {
+    FakeSocket.opened.push(this)
+  }
+  send() {}
+  close() {}
+  receive(frame: unknown) {
+    this.onmessage?.({ data: JSON.stringify(frame) })
+  }
+}
+
+beforeEach(() => {
+  FakeSocket.opened = []
+  vi.stubGlobal('WebSocket', FakeSocket)
+})
+afterEach(() => vi.unstubAllGlobals())
+
+function lastUrl(): string {
+  return FakeSocket.opened.at(-1)!.url
+}
+
+describe('the flag survives whatever URL the caller builds', () => {
+  it('with a builder that uses the path it is given', () => {
+    renderHook(() =>
+      useSessionSocket({ sessionId: 's1', wsUrl: (p) => `wss://h/${p}`, protocol: 'ag-ui' }),
+    )
+    expect(lastUrl()).toBe('wss://h/ws/canopy-sessions/s1/?protocol=ag-ui')
+  })
+
+  it('with a builder that IGNORES its path — canopy-web’s widget', () => {
+    // `() => client.sessionSocketUrl(sessionId)`: the widget's real shape.
+    renderHook(() =>
+      useSessionSocket({ sessionId: 's1', wsUrl: () => 'wss://h/ws/canopy-sessions/s1/', protocol: 'ag-ui' }),
+    )
+    expect(lastUrl()).toContain('protocol=ag-ui')
+  })
+
+  it('with a builder that carries its own token — ace-web', () => {
+    // `buildCanopyWsUrl(base, id)` puts a token in the query, so the flag has
+    // to JOIN the query rather than start a second one.
+    renderHook(() =>
+      useSessionSocket({ sessionId: 's1', wsUrl: () => 'wss://h/ws/canopy-sessions/s1/?token=abc', protocol: 'ag-ui' }),
+    )
+    expect(lastUrl()).toBe('wss://h/ws/canopy-sessions/s1/?token=abc&protocol=ag-ui')
+  })
+
+  it('asks for nothing when the caller asks for nothing', () => {
+    // The default is canopy's own frames, which is what an un-upgraded consumer
+    // must keep getting.
+    renderHook(() => useSessionSocket({ sessionId: 's1', wsUrl: () => 'wss://h/x/?token=abc' }))
+    expect(lastUrl()).toBe('wss://h/x/?token=abc')
+  })
+})
+
+describe('withAguiProtocol', () => {
+  it('does not add the flag twice', () => {
+    expect(withAguiProtocol('wss://h/x/?protocol=ag-ui')).toBe('wss://h/x/?protocol=ag-ui')
+  })
+
+  it('leaves an empty URL empty — the caller’s "not yet"', () => {
+    expect(withAguiProtocol('')).toBe('')
+  })
+})
+
+describe('a server that answers in canopy frames anyway', () => {
+  it('is understood, not decoded to nothing', () => {
+    // Asked for AG-UI, got native: an old server, or a flag lost on the way.
+    // Decoding these as AG-UI yields zero frames — a blank chat with no error.
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const onTitleUpdated = vi.fn()
+    renderHook(() =>
+      useSessionSocket({ sessionId: 's1', wsUrl: (p) => `wss://h/${p}`, protocol: 'ag-ui', onTitleUpdated }),
+    )
+
+    act(() => {
+      FakeSocket.opened.at(-1)!.receive({
+        event: 'session.title_updated',
+        data: { title: 'Still readable' },
+      })
+    })
+
+    expect(onTitleUpdated).toHaveBeenCalledTimes(1)
+    expect(warn).toHaveBeenCalledTimes(1)
+    warn.mockRestore()
+  })
+
+  it('still decodes real AG-UI events as AG-UI', () => {
+    const onTitleUpdated = vi.fn()
+    renderHook(() =>
+      useSessionSocket({ sessionId: 's1', wsUrl: (p) => `wss://h/${p}`, protocol: 'ag-ui', onTitleUpdated }),
+    )
+
+    act(() => {
+      FakeSocket.opened.at(-1)!.receive({
+        type: 'STATE_DELTA',
+        delta: [{ op: 'replace', path: '/title', value: 'Via AG-UI' }],
+      })
+    })
+
+    expect(onTitleUpdated).toHaveBeenCalledTimes(1)
+  })
+})