[boehlerlukas]

Sidekick mode: an agent in a side panel next to the page

Gleap.openSidekick() opens Kai Support or one of the workspace's customer agents in a full-height panel on the right edge (400 px), with the page's context. By default it pushes the page aside like Intercom's Fin side panel: the page stays visible and usable, no dim. Phones get a full-screen sheet. Agents can also reach out first with a message card above the launcher that opens the panel with their message in the thread. Plan: decision 13 of the Kai re-release (contract in .handover/kai-build/sidekick.md).

API

Gleap.openSidekick({ agentId, context, initialMessage, initialQuestion, mode: 'push' | 'overlay', newConversation });
Gleap.showSidekickMessage({ agentId, message, sender? }); // → boolean: the card above the launcher
Gleap.hideSidekickMessage();
Gleap.setSidekickContext({ title, step: { id, title, index, total }, data: { plan: 'Pro' } }); // a plain object counts as data
Gleap.closeSidekick();
Gleap.isSidekickOpen();
Gleap.setSidekickProactive(false); // no proactive cards or opens on this page
Gleap.on('sidekick-opened' | 'sidekick-closed' | 'sidekick-proactive' | 'sidekick-message-dismissed', cb);

All of it is additive: nothing changes for a page that never calls the sidekick and gets no sidekick trigger.

Layout

• Push (default): a margin on <html> on the panel's side (never a transform), no backdrop, aria-modal="false", Escape inside a page field stays the page's. Fixed headers and footers shrink along: every position: fixed element spanning the viewport (left ≈ 0 and right ≈ the edge, or ≥ 90vw) gets inline left/width on the panel's side while pushed, slides with the page, and gets its previous inline values back exactly on close. A throttled MutationObserver handles fixed elements added (or turned fixed) while open; resizes re-measure. Gleap's own elements and the backdrop are skipped.
• Overlay (dim layer that blocks the page, click closes): when asked (mode: 'overlay'), when the page would get narrower than 720 px, and by default on a page inside an iframe (mode: 'push' forces the push there). sidekick-opened says why (pushFallback: 'iframe').
• Phones (≤ 600 px): the full-screen sheet, never a push; padded for the notch and home indicator, as tall as the visible viewport.
• Closing gives the page back exactly: <html> inline styles, the fixed bars' inline styles, scroll position, focus, launcher. Other unread notifications hide while the panel is open and come back afterwards.

Message cards

• A card in the existing notification stack (same chrome, z-index and position as the chat bubbles): agent avatar (or the bot's initial), up to 3 lines of the message, " · now", its own × button. Clicking it opens the sidekick with the message as the agent's first message; the agent continues from there.
• × (or Escape on the card): gone, and the same card stays away for a day in every tab (gleap cache + BroadcastChannel removes it in open sibling tabs). A route change, the widget opening or another identity take it away without a dismissal. Not shown while the widget or the sidekick is open.
• Built from DOM nodes (no markup from the message), the card is a real <button>, a polite live region announces it, reduced motion is respected. CSS goes through the SDK's existing injected stylesheet (CSP nonce); runtime styles only via CSSOM.
• Default sender = the project's bot persona (operatorName / operatorAvatarImage), as the classic chat notification shows AI messages.

Proactive messages from the socket

The socket announces sidekick and the new sidekick-card. A sidekick message carries display: 'card' | 'open' (no display = open, the earlier protocol). Cards wait for nothing; opens keep the typing / hidden-tab waits. Both: at most one per page view, never over something else, quiet for a day after a dismissal, respect setSidekickProactive(false); cards also respect disabled in-app notifications. The server sends cards / opens only to sockets that announced them; every other client gets the classic in-app conversation instead (Server feat/redesign-rerelease).

Backwards compatible

startAgent and the AI bar are untouched; a Messenger build without the sidekick cap in its ping makes openSidekick (and a card click) fall back to startAgent.

Verified

• npm test: 35 suites, 598 tests (GleapSidekickRules.test.js: envelope, push-risk decisions, card parsing, proactive guards). npm run build passes (build outputs not committed).
• Browser, round 1 (Playwright, private stack): overlay and push open/close with the page restored exactly, Escape and backdrop close, SPA navigation updates the context, context reached Kai Support and a custom agent, proactive opens, phone sheet, light and dark. Screenshots: .handover/kai-build/shots/sidekick/.
• Round 3 (10-27, built-in browser on the demo stack): push at 1440 px with the fixed header shrinking along and an exact restore (header + <html> inline style, scroll), a fixed bar added while open adjusted and restored, overlay at ~1000 px, a card on a 375/390 px phone opening the full-screen sheet with the message in the thread. Screenshots: .handover/kai-build/shots/sidekick/r3-*.

Not in this PR

No version bump or release. Needs GleapSDK/Messenger-App#268 deployed first (older Messenger builds fall back to startAgent) and the Server side (in feat/redesign-rerelease) for context, cards and proactive messages.

🤖 Generated with Claude Code