canopy-ui 0.8.0 → 0.9.0

package/package.json

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

package/src/chat/agui.fixture.json

@@ -231,5 +231,350 @@
         }
       }
     ]
+  },
+  {
+    "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
+      }
+    },
+    "agui": [
+      {
+        "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
+              }
+            }
+          }
+        },
+        "type": "MESSAGES_SNAPSHOT",
+        "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.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": [
+      {
+        "metadata": {
+          "canopy": {
+            "frame": {
+              "event": "chat.stream_error",
+              "data": {
+                "message_id": "m1",
+                "detail": "runner went away"
+              }
+            }
+          }
+        },
+        "type": "RUN_ERROR",
+        "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

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/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)
+  })
+})

package/src/chat/useSessionSocket.ts

@@ -58,6 +58,27 @@ export interface UseSessionSocketOptions {
   protocol?: "canopy" | "ag-ui";
 }
 
+/**
+ * Ask for AG-UI on the URL the caller built — whatever it looks like.
+ *
+ * The hook OWNS this flag rather than handing the caller a path with it already
+ * attached, because that contract was invisible and two of the first three
+ * callers broke it: canopy-web's widget builds `client.sessionSocketUrl(id)` and
+ * ace-web builds `buildCanopyWsUrl(base, id)`, and both ignore the path they are
+ * given (they need their own token in the query). The flag was dropped, the
+ * server answered in native frames, and every one of them decoded as AG-UI to
+ * nothing — a blank chat with no error, caught only in review before it shipped.
+ *
+ * Exported for the test, which asserts on the URL a socket really opens.
+ */
+export function withAguiProtocol(url: string): string {
+  // Empty is a caller saying "no URL yet" (the widget before it has a
+  // session); decorating it would turn a deliberate no-op into a bad request.
+  if (!url) return url;
+  if (/[?&]protocol=/.test(url)) return url;
+  return `${url}${url.includes("?") ? "&" : "?"}protocol=ag-ui`;
+}
+
 export interface UseSessionSocketResult {
   state: SessionState;
   connected: boolean;
@@ -121,6 +142,7 @@ export function useSessionSocket({
   // vocabulary mid-session.
   const protocolRef = useRef(protocol);
   protocolRef.current = protocol;
+  const warnedNativeRef = useRef(false);
   // Control frames that must not be lost across a reconnect (currently
   // only chat.stop). The WS-world analogue of an abortable chat transport.
   const pendingFramesRef = useRef<{ action: string; data: unknown }[]>([]);
@@ -202,8 +224,9 @@ export function useSessionSocket({
     // by an ARGS event from this one — the ids are per-stream.
     resetAguiState();
     const path = `ws/canopy-sessions/${sessionId}/`;
+    const built = wsUrl(path);
     const ws = new WebSocket(
-      wsUrl(protocolRef.current === "ag-ui" ? `${path}?protocol=ag-ui` : path),
+      protocolRef.current === "ag-ui" ? withAguiProtocol(built) : built,
     );
     socketRef.current = ws;
 
@@ -229,6 +252,22 @@ export function useSessionSocket({
       try {
         const raw = JSON.parse(e.data);
         if (protocolRef.current === "ag-ui") {
+          // We asked for AG-UI and the server answered in canopy's own frames:
+          // a server that predates the negotiation, or a URL that lost the flag
+          // on the way (see `withAguiProtocol`). The two are unambiguous — every
+          // AG-UI event has a `type`, and no canopy frame does — so apply it as
+          // what it is. Decoding it as AG-UI yields nothing, which is a blank
+          // chat with no error: the worst possible way to find out.
+          if (typeof raw?.type !== "string" && typeof raw?.event === "string") {
+            if (!warnedNativeRef.current) {
+              warnedNativeRef.current = true;
+              console.warn(
+                "canopy-ui: asked for protocol=ag-ui but the server sent canopy frames; handling them as canopy frames.",
+              );
+            }
+            applyEvent(raw as WsEvent);
+            return;
+          }
           // One AG-UI event can be several canopy frames (a tool call is three
           // events) or none, so this is a fan-out rather than a rename.
           for (const frame of fromAgui(raw)) applyEvent(frame);