@streamoid/agent 0.6.52 → 0.6.54

package/README.md

@@ -53,10 +53,137 @@ tank`); `title` keeps its original identity. Preserve proper names, acronyms and
 
 Embedded and standalone chat use `ScComposerSurface` and `ScSuggestionRow` from
 `@streamoid/ui` 0.6.86+. An empty composer starts with three 20px text lines and
-grows to 170px before scrolling. Suggestions are native buttons in flat rows
-with hairline separators, and fill the composer without navigating or sending.
+grows to 170px before scrolling. Suggestions are native buttons in a stack of
+cards (the DS row spaces and borders itself), and fill the composer without
+navigating or sending. A panel scoped to an app shows exactly three when three
+are available (see `AgentScopeAdapter.sections` in `index.d.ts`).
 
-The secondary line shows `meta.outcome_summary` (falling back to
-`meta.expected_output`), optionally followed by authored `meta.ceiling_minutes`
+The secondary line shows `meta.summary` — one outcome-first sentence — falling
+back to `meta.outcome_summary`, then `meta.expected_output` (which stays the
+agent's spec), optionally followed by authored `meta.ceiling_minutes`
 and `meta.estimated_credits`. Unknown estimates are omitted. Scoped suggestions
 use `deliverable` and `ceilingMinutes` from the host's outcome catalogue.
+
+
+## The Ask CXO side pane — `@streamoid/agent/pane`
+
+Every product app shows the chat the same way: rail | **pane** | page. The
+shell for it ships here, so the apps stop hand-building it around
+`AgentPanel` (they had drifted on width, unmount-on-close, workspace switch,
+Escape, mobile and persistence).
+
+`@streamoid/agent/pane` is a **light entry** (~16kB, React and
+`@streamoid/ui` are yours). It never imports the 5MB chat statically — the
+chat is `import()`ed when the pane first opens (or on `prefetch`), so import
+the pane eagerly in your shell.
+
+```tsx
+import { useMemo } from "react";
+import { AgentSidePane, useAgentPaneController, type AgentSidePaneAdapters } from "@streamoid/agent/pane";
+
+export function Shell() {
+  const pane = useAgentPaneController({
+    workspaceId,                                   // persisted per workspace
+    legacyWidthKey: "artifax.assistant.width",     // your old width key, migrated once
+    // persistKey: "artifax-assistant-session",    // keep an existing session key
+    // bindShortcut: false,                        // if ⌘K is bound elsewhere
+  });
+
+  const adapters = useMemo<AgentSidePaneAdapters>(() => ({
+    auth, workspace: { current: { id: workspaceId, name } }, theme: { mode },
+    config: { apiBase, hide: { sidepane: true, newBrief: true, notifications: true }, widgetMode: "inline_ask" },
+  }), [/* … */]);                                  // memoise it
+
+  return (
+    <div style={{ display: "flex", height: "100vh" }}>
+      <Rail
+        askActive={pane.open}                      // the trigger's `active`
+        onAsk={pane.askCxo}                        // open + focus the composer (never a toggle)
+        onAskIntent={pane.prefetch}                // hover / focus
+        onHelp={() => pane.requestSupport({ currentPage })}
+      />
+      <AgentSidePane controller={pane} adapters={adapters}
+        hostContext={hostContext} scope={scope} support={{ appVersion }} canvas={canvas} />
+      {/* An artefact takes the page: hide main (display:none, not unmount). */}
+      <main style={{ flex: 1, minWidth: 0, display: pane.surface === "fullscreen" ? "none" : undefined }}>
+        <Outlet context={{ askAbout: pane.askAbout }} />
+      </main>
+    </div>
+  );
+}
+```
+
+What the pane does, identically in every app:
+
+- **Geometry.** Docked at ≥768px: in flow beside the page, width
+  `SC_ASSISTANT_PANEL_WIDTH` (**510px**, from `@streamoid/ui`) within
+  `SC_ASSISTANT_PANEL_BOUNDS` (360–900), resizable with `ScPanelResizeHandle`,
+  persisted under `streamoid.askPane.width`. Below 768px: a full-screen sheet
+  (`role="dialog"`, focus trap, siblings `inert`, focus restored on close).
+  Geometry is inline style, so no utility class from either stylesheet can
+  move it.
+- **Fullscreen.** `onSurfaceChange` reporting a non-text artefact widens the
+  pane over the page (`controller.surface === "fullscreen"` — hide your
+  `main`). Escape returns to the side pane and that artefact is not widened
+  again while it stays open (also across a close and reopen); a different one
+  still is. A pane closed over a live artefact — or one an artefact opened in
+  while closed — reopens fullscreen. No expand button.
+- **Stays mounted** after the first open; closing hides it, so an answer still
+  streaming keeps going. Before the first open nothing loads.
+- **Persistence.** Open state and the conversation, per workspace, survive a
+  reload (fullscreen comes back as the side pane). A workspace change closes
+  the pane, drops the old conversation, **remounts the chat** (no draft,
+  upload or selection chip carries over) and loads the new workspace's.
+- **Escape** (bubble phase): docked, it closes only when focus is inside the
+  pane, no nested dialog holds the key, and nothing `preventDefault`ed it.
+  Fullscreen collapses to the side pane first. On the sheet, focus need not be
+  inside (the page is inert).
+- **Back button** (phone): opening the sheet pushes one history entry (same
+  URL, your router's state kept); Back closes the sheet. Closing with × or
+  Escape removes the entry, so no stray Back is left behind.
+- **Errors.** A pane-local error boundary: "Ask CXO couldn’t load" + Retry
+  (re-imports). Loading shows "Loading Ask CXO…".
+- **Header** is the chat's own (title + context, New task, History, ×);
+  × calls `controller.close`.
+
+Controller calls: `reveal()` / `close()` / `toggle()`, `askCxo()`,
+`askAbout(prompt)` (new conversation + send, via `enqueueChatPrompt`),
+`requestSupport({ currentPage }?)` (Get help home via `showAgentSupport`),
+`prefetch()`, `width` / `setWidth` / `commitWidth`, and
+`selectionSnapshot` — the selection the pane **holds** (its snapshot of
+`scope.selection`: taken on open, on New task and on `askCxo` with no chat;
+cleared when a chat opens or the chip is removed). Count or split suggestions
+on that, with the pane's own rule: `paneSuggestionCount(sections,
+pane.selectionSnapshot)` / `deriveScopeSuggestions(...)`, both exported here.
+A host mounting `AgentPanel` directly gets the same value from
+`adapters.onSelectionSnapshot`.
+
+**Stylesheet.** Import the chat's CSS into its own cascade layer so its
+compiled utilities cannot beat yours (the Catalogix / Photogenix pattern):
+
+```css
+@import "@streamoid/agent/style.css" layer(streamoid-agent);
+```
+
+### Migrating each app (do it in the app's `@streamoid/agent` 0.6.54 bump PR)
+
+**Artifax** (`apps/artifax/src/components/{AppShell,AssistantPanel}.tsx`)
+- `useAgentPaneController({ workspaceId: workspaceID, persistKey: "artifax-assistant-session", legacyWidthKey: "artifax.assistant.width" })` in `AppShell`; render `<AgentSidePane>` in place of `AssistantPanel`, keeping its adapters/hostContext/scope.
+- Delete `lib/assistantSurface.ts` (reducer + tests) and `lib/assistantSession.ts`, the shell's Escape effect, `prefetchAgentChunk`, `askCxo`, `requestSupport`, the `useStreamoidSearchShortcut` call. `main` hides on `pane.surface === "fullscreen"` (as now). `onAskCxoRequest(pane.askCxo)` stays.
+- Delete `usePaneSelectionSnapshot` / `noteAssistantComposerFocus` (`lib/assistantScope.ts`) and the test copy `src/test/paneSuggestions.ts`; use `pane.selectionSnapshot` and `paneSuggestionCount` / `deriveScopeSuggestions`.
+- Default width stays 510; a stored width migrates.
+
+**Tactix** (`apps/tactix/src/components/{TactixShell,AssistantPanel}.tsx`)
+- `useAgentPaneController({ workspaceId, legacyWidthKey: "tactix.assistant.width" })` in `TactixShell`; `<AgentSidePane>` replaces `AssistantPanel`. Outlet context `askCxoAbout` becomes `pane.askAbout`.
+- Delete the shell's `askCxo` / `askCxoAbout` / `requestSupport` / `prefetchAgent` and the panel's unguarded Escape effect. Hide `main` on fullscreen (new: artefacts now widen). Gains: mobile sheet, persistence, workspace reset.
+- Default width 480 → 510 (DS constant) for users who never resized.
+
+**Catalogix** (`dashboard/app/containers/AskCxo/`)
+- `useAgentPaneController({ workspaceId, legacyWidthKey: "catalogix.ask.width" })` where `useAppStore`'s ask slice is read; `<AgentSidePane>` replaces `AskCxo/index.jsx` + `AskCxoPanel.jsx`. The rail's trigger/⌘K/Help call the controller (pass `bindShortcut: false` if ⌘K stays bound in `LeftMenu`).
+- Delete `askOpen` / `askChatId` from `useAppStore` (and the workspace-switch reset on its setter — the controller does it), `askCxo.js`'s `importAgent` / `prefetchAgent` / `askCxo`. Hide the page on fullscreen (new). Gains: persistence, Back button.
+- Default width 480 → 510.
+
+**Photogenix** (`dashboard/client/src/features/ask/`)
+- `useAgentPaneController({ workspaceId, legacyWidthKey: "photogenix.ask.width" })` in the shell; `<AgentSidePane>` replaces `AskPane.tsx` + `AskCxoPanel.tsx`; `useAskConversation.ts` goes (the controller owns `chatId`).
+- Delete the pane's own sheet/focus-trap/Escape code. Hide the page on fullscreen (new). Gains: stays mounted (no SSE abort on close), persistence, Back button.
+- Default width 480 → 510.

package/dist/agentScope-BlOT7qMu.js

@@ -0,0 +1,114 @@
+import { resolveStreamoidProduct as b, streamoidProductLabel as k } from "@streamoid/ui";
+function a(e) {
+  if (typeof e != "string" || !e.trim()) return null;
+  const n = b(e.trim());
+  return n && n !== "cxo" ? n : null;
+}
+function d(e) {
+  return e && k(e) || "All apps";
+}
+function $(e, n) {
+  if (e === null || e !== a(n?.app)) return null;
+  const i = (Array.isArray(n?.breadcrumbs) ? n.breadcrumbs.filter((t) => typeof t == "string" && !!t.trim()).map((t) => t.trim()) : []).join(" › ") || (typeof n?.page == "string" ? n.page.trim() : "");
+  return i ? `${d(e)} · ${i}` : d(e);
+}
+function p(e, n) {
+  return !e.kinds || e.kinds.length === 0 || n === void 0 ? !0 : e.kinds.map((r) => r.toLowerCase()).includes(n.toLowerCase());
+}
+function h(e) {
+  return e.charAt(0).toUpperCase() + e.slice(1);
+}
+function m(e, n) {
+  const r = e.instruction?.includes("{subject}") ? e.instruction : `${e.label}: {subject}`;
+  return h(r.replace(/\{subject\}/g, n).trim());
+}
+function w(e, n) {
+  const r = [];
+  for (const i of e ?? []) {
+    if (!i?.outcomes?.length) continue;
+    const t = (i.samples ?? []).find(
+      (u) => i.outcomes.some((f) => p(f, u.kind))
+    ), c = (u, f) => i.outcomes.find((l) => l.key === f && p(l, u)) ?? i.outcomes.find((l) => p(l, u)), s = n ? c(n.kind, t?.primaryOutcomeKey) : void 0;
+    if (n && s) {
+      r.push({
+        id: `${i.key}:${s.key}:selection`,
+        sectionKey: i.key,
+        outcomeKey: s.key,
+        subject: "selection",
+        text: m(s, n.subject || n.label),
+        ceilingMinutes: s.ceilingMinutes,
+        deliverable: s.deliverable
+      });
+      continue;
+    }
+    if (!t) continue;
+    const o = c(t.kind, t.primaryOutcomeKey);
+    o && r.push({
+      id: `${i.key}:${o.key}:${t.id}`,
+      sectionKey: i.key,
+      outcomeKey: o.key,
+      sampleId: t.id,
+      sampleTitle: t.subject || t.title,
+      subject: "sample",
+      text: m(o, t.subject || t.title),
+      ceilingMinutes: o.ceilingMinutes,
+      deliverable: o.deliverable,
+      imageUrl: t.imageUrl ?? null
+    });
+  }
+  return r;
+}
+function O(e, n) {
+  return n ? e.length === 0 ? !1 : e.every((r) => a(r) === n) : !0;
+}
+const v = 3;
+function A(e, n, r = v) {
+  const i = (s) => (s.value ?? s.title).trim().toLowerCase(), t = e.slice(0, r), c = new Set(t.map(i));
+  for (const s of n) {
+    if (t.length >= r) break;
+    const o = i(s);
+    c.has(o) || (c.add(o), t.push(s));
+  }
+  return t;
+}
+function S(e) {
+  return ["headline", "subline", "placeholder"].filter(
+    (n) => !e?.[n]?.trim()
+  );
+}
+let g = !1;
+function C() {
+  try {
+    return process.env.NODE_ENV === "development";
+  } catch {
+    return !1;
+  }
+}
+function L(e, n, r = C()) {
+  if (!r || g || !e) return !1;
+  const i = S(n);
+  return i.length === 0 ? !1 : (g = !0, console.warn(
+    `[@streamoid/agent] adapters.scope for "${e}" has no ${i.join(", ")}; the Ask CXO panel falls back to generic copy. Pass an app-specific question (headline), helper line (subline) and composer hint (placeholder).`
+  ), !0);
+}
+function y(e) {
+  return a(e.meta?.origin_app);
+}
+function K(e) {
+  const n = e.meta?.scope;
+  return n === "all" ? null : a(n) ?? y(e);
+}
+function M(e, n) {
+  return n ? e.filter((r) => y(r) === n) : [...e];
+}
+export {
+  M as a,
+  O as b,
+  K as c,
+  w as d,
+  $ as e,
+  A as f,
+  a as h,
+  d as s,
+  L as w
+};

package/dist/index.d.ts

@@ -50,10 +50,20 @@ export interface AgentHostContext {
   ids?: Record<string, string | number>;
   /** A short list of what is on screen — board names, selected items. */
   visible?: string[];
-  /* The pane merges two keys of its own into what is sent, never replacing
-   * the host's: `entry: "help_and_support"` on a conversation started from
-   * the Get help home (`showAgentSupport`), and `app_version` from
-   * `adapters.support.appVersion`. */
+  /* The pane merges keys of its own into what is sent, never replacing the
+   * host's: `app_version` from `adapters.support.appVersion` on every message;
+   * and on a conversation started from the Get help home (`showAgentSupport`)
+   * `entry: "help_and_support"`, `current_page` (from `showAgentSupport({
+   * currentPage })`), `browser` ("Chrome") and `details_shared: true`. If the
+   * user removes the home's "We'll include" chip, that conversation's
+   * messages carry only `entry`, `details_shared: false` and the routing keys
+   * `scope` and `app` (plus `selection` / `ids.selection` while the composer's
+   * selection chip is attached) — none of the host's other keys, nor the
+   * pane's. The backend latches the opt-out on the conversation and strips
+   * the details from every later turn itself, even after a remount. */
+  /** Pane-set on the Get help conversation: whether the user shared the
+   *  "We'll include" details. Hosts do not set it. */
+  details_shared?: boolean;
   [key: string]: unknown;
 }
 
@@ -73,9 +83,9 @@ export interface AgentSupportAdapter {
   /**
    * The host app's own build version, e.g. `0.0.61`. Sent as
    * `hostContext.app_version` with EVERY message — support or not — so a
-   * problem report names the build it came from. Also shown as a chip on the
-   * Get help home's "We'll include" line. A `hostContext.app_version` the host
-   * passes itself wins over this.
+   * problem report names the build it came from. Also shown in the Get help
+   * home's "We'll include" chip. A `hostContext.app_version` the host passes
+   * itself wins over this.
    */
   appVersion?: string;
 }
@@ -154,6 +164,19 @@ export interface AgentChatShellAdapters {
    * Fires only on change, and only for the conversation on screen.
    */
   onSurfaceChange?: (state: AgentSurfaceState) => void;
+  /**
+   * The selection the pane HOLDS — its snapshot of `scope.selection`, which its
+   * suggestions and composer chip are built from — reported whenever it
+   * changes, and once on mount.
+   *
+   * The pane does not follow `scope.selection` live: it snapshots it when it
+   * mounts, when the conversation goes back to none (New task), and on
+   * `focusAgentComposer()` while no conversation is open; it clears it when an
+   * existing conversation opens or the user removes the chip. A host that
+   * splits or counts its suggestions on the selection must use THIS value, not
+   * its live one. `AgentSidePane` wires it to `controller.selectionSnapshot`.
+   */
+  onSelectionSnapshot?: (selection: AgentScopeSelection | null) => void;
   /**
    * Supply the canvas as a component and the Dreamer panel drops its iframe:
    * no embedded page, so no cross-origin auth, no postMessage handshake, no
@@ -179,6 +202,16 @@ export interface AgentChatShellAdapters {
    * - `sections`: the app's outcome table. One suggestion per section, from
    *   its first sample's primary outcome. Change the samples and the
    *   suggestions follow. Omit it for the catalog briefs this app can run alone.
+   *   The panel shows EXACTLY THREE suggested tasks when three exist: the
+   *   sections' suggestions in table order (a fourth and later are left to
+   *   "View all tasks"), topped up with the catalog briefs this app can run
+   *   alone — those flagged for the empty chat first, by their authored rank,
+   *   then the rest — never repeating one. Fewer only when fewer exist.
+   * - `headline`, `subline`, `placeholder`: the panel's app-specific question,
+   *   helper line and composer hint. Pass all three: a scoped host that leaves
+   *   any out gets one `console.warn` in a development build. Honoured at CXO
+   *   home too (`hostContext.app` absent or `"cxo"`), where the defaults are
+   *   the hub's own when they are absent.
    * - `selection`: what was selected when the pane opened — a removable chip
    *   in the composer, and the subject suggestions name.
    * - `onSuggestion`: DEPRECATED AND NOT CALLED. Picking a suggestion always
@@ -254,13 +287,15 @@ export interface AgentScopeAdapter {
   sections?: AgentScopeSection[] | null;
   selection?: AgentScopeSelection | null;
   /** The line above the composer before the first turn, in the host's own
-   *  words. Absent or blank = "Describe what you want to create". */
+   *  words — the app-specific question. Absent or blank = "Describe what you
+   *  want to create" in an app, "Run your retail operations from here" at CXO
+   *  home. */
   headline?: string | null;
-  /** The quieter line under it. Absent or blank = "CXO will plan the steps
-   *  and pause for your approval." */
+  /** The quieter helper line under it. Absent or blank = "CXO will plan the
+   *  steps and pause for your approval." in an app, none at CXO home. */
   subline?: string | null;
   /** The empty composer's hint before the first turn. Absent or blank =
-   *  "What needs to get done". */
+   *  "What needs to get done". Honoured in an app and at CXO home alike. */
   placeholder?: string | null;
   /**
    * @deprecated NOT CALLED. A suggestion always fills the composer. Kept so
@@ -487,7 +522,16 @@ export declare function focusAgentComposer(): void;
  * Every message of the conversation that starts on the home carries
  * `hostContext.entry = "help_and_support"`, merged into the host's own
  * context, for as long as that conversation stays open — so follow-ups keep
- * routing to the support agent. Starting a new task, or opening another
+ * routing to the support agent.
+ *
+ * The home's "We'll include" line is ONE removable chip naming what the
+ * support conversation is sent: workspace, `options.currentPage`, version
+ * and browser, after the app (plain text, always shared — it routes the
+ * request). Removing it (✕) sends none of them — only `entry`,
+ * `details_shared: false` and the routing keys `scope` and `app` — until the
+ * user restores it or the home is opened again. The opt-out is persisted on
+ * the conversation server-side, which also leaves the workspace off the
+ * support email and the issue. Starting a new task, or opening another
  * conversation from history, leaves the mode.
  *
  * Queued like {@link enqueueChatPrompt}: the call may come before or after the
@@ -495,4 +539,142 @@ export declare function focusAgentComposer(): void;
  * empty one. Do not also set the panel's `chatId` to a new id — `null` (or
  * leaving it alone) is right; the pane navigates itself.
  */
-export declare function showAgentSupport(): void;
+export declare function showAgentSupport(options?: ShowAgentSupportOptions | null): void;
+
+/** Options for {@link showAgentSupport}. All optional; omit them entirely and
+ *  the home behaves exactly as with no argument. */
+export interface ShowAgentSupportOptions {
+  /**
+   * A short, human label for where the user was BEFORE opening help — the
+   * task or page they were on, e.g. `"SS26 range plan"` or `"Explore"`. Not a
+   * URL or a route (`hostContext.url`/`route` already carry those).
+   *
+   * Shown in the home's "We'll include" chip
+   * (`CXO · demo workspace · SS26 range plan · v0.0.61 · Chrome`) and sent as
+   * `hostContext.current_page` on every message of the support conversation,
+   * unless the user removes the chip. Cleared when the user leaves the home or
+   * its conversation (New task, another conversation); each call replaces it,
+   * and a call without it shows none.
+   */
+  currentPage?: string | null;
+}
+
+/* ── Ask CXO side pane (`@streamoid/agent/pane`) ───────────────────────────
+ *
+ * The TYPES of the shared side pane live here, beside the adapters they are
+ * built from; its VALUES (`useAgentPaneController`, `AgentSidePane`, …) are
+ * declared in `pane.d.ts` and exported only from the `@streamoid/agent/pane`
+ * subpath — the light entry that does not pull in this 5MB bundle. Keep both
+ * in step with `src/embed/pane/`. */
+
+/** `closed` → `pane` (the side pane) → `fullscreen` (a non-text artefact took
+ *  the page). Fullscreen is never restored on reload. */
+export type AgentPaneSurface = 'closed' | 'pane' | 'fullscreen';
+
+export interface AgentPaneControllerOptions {
+  /** The workspace the pane's conversation belongs to. The open state and the
+   *  conversation are persisted per workspace; a change closes the pane, drops
+   *  the old workspace's conversation and loads the new one's saved state. An
+   *  empty value (not resolved yet) persists nothing. */
+  workspaceId: string | null | undefined;
+  /** localStorage prefix for the per-workspace session
+   *  (`<persistKey>:<workspaceId>`). Default `streamoid.askPane.session`.
+   *  Artifax passes `artifax-assistant-session` to keep its users' open chats
+   *  across the migration — its stored `{ surface: 'rail', chatId }` is read. */
+  persistKey?: string;
+  /** The app's old width key(s), copied once into `streamoid.askPane.width`
+   *  while that key is still empty: `artifax.assistant.width`,
+   *  `tactix.assistant.width`, `catalogix.ask.width`, `photogenix.ask.width`. */
+  legacyWidthKey?: string | readonly string[];
+  /** Bind ⌘K / Ctrl+K to `askCxo` (with a prefetch). Default `true`; pass
+   *  `false` where the host binds the chord to something else. */
+  bindShortcut?: boolean;
+}
+
+/** Options for {@link AgentPaneController.requestSupport} — exactly
+ *  {@link showAgentSupport}'s, passed straight through. */
+export type AgentPaneSupportOptions = ShowAgentSupportOptions;
+
+export interface AgentPaneController {
+  /** The pane is showing (side pane or fullscreen). Hand it to the rail's Ask
+   *  CXO trigger as `active`. */
+  open: boolean;
+  /** `fullscreen` while a non-text artefact holds the page. A host whose page
+   *  sits beside the pane HIDES it (`display: none`, not unmount — the page
+   *  keeps its scroll and form state) for exactly as long:
+   *  `<main style={{ display: controller.surface === 'fullscreen' ? 'none' : undefined }}>`. */
+  surface: AgentPaneSurface;
+  /** The conversation on screen; `null` lets the chat create one. Persisted
+   *  per workspace with the open state. */
+  chatId: string | null;
+  /** Show the pane. Open, never toggle. Applies the chat's latest surface
+   *  report: an artefact still live behind a closed pane reopens fullscreen,
+   *  unless the user declined it with Escape. */
+  reveal(): void;
+  /** Hide the pane. It stays mounted: an answer still streaming keeps going,
+   *  and an artefact stays live (reports arriving while closed are kept). */
+  close(): void;
+  toggle(): void;
+  /** The rail trigger / ⌘K: reveal and put the caret in the composer. */
+  askCxo(): void;
+  /** Reveal on a NEW conversation and send `prompt` in it, without waiting for
+   *  the network (`enqueueChatPrompt`). `false` when the prompt is blank. */
+  askAbout(prompt: string): boolean;
+  /** Help & Support: reveal on the Get help home ({@link showAgentSupport});
+   *  sends nothing. */
+  requestSupport(options?: AgentPaneSupportOptions | null): void;
+  /** Warm the agent chunk — wire to the trigger's hover and focus. */
+  prefetch(): void;
+  /** Docked width in px, from `SC_ASSISTANT_PANEL_WIDTH` within
+   *  `SC_ASSISTANT_PANEL_BOUNDS`, persisted under `streamoid.askPane.width`. */
+  width: number;
+  /** Live width during a drag; not persisted. */
+  setWidth(width: number): void;
+  /** Persist a width (drag end). */
+  commitWidth(width: number): void;
+  bounds: { min: number; max: number };
+  /** The selection the pane HOLDS (see `adapters.onSelectionSnapshot`) —
+   *  `null` until the chat mounts. Split or count suggestions on this, e.g.
+   *  `paneSuggestionCount(sections, controller.selectionSnapshot)`, not on the
+   *  host's live selection. */
+  selectionSnapshot: AgentScopeSelection | null;
+  /** Changes on every real workspace switch (not when an unresolved id first
+   *  resolves). `AgentSidePane` keys the chat on it, so a switch remounts the
+   *  chat — workspace A's draft, uploads and selection chip never reach B —
+   *  and `selectionSnapshot` resets in the same update. */
+  workspaceEpoch: number;
+  /** Wiring for `AgentSidePane`; hosts do not need these. */
+  setChatId(chatId: string | null): void;
+  reportSurface(state: AgentSurfaceState): void;
+  collapse(): void;
+  reportSelectionSnapshot(selection: AgentScopeSelection | null): void;
+}
+
+/** The adapters a host still supplies to {@link AgentSidePaneProps}. The pane
+ *  fills `navigation`, `onClose`, `onSurfaceChange` and `onSelectionSnapshot`
+ *  from the controller and takes `hostContext`, `scope`, `support` and
+ *  `canvas` as props. */
+export type AgentSidePaneAdapters = Omit<
+  AgentPanelAdapters,
+  | 'navigation'
+  | 'onClose'
+  | 'onSurfaceChange'
+  | 'onSelectionSnapshot'
+  | 'hostContext'
+  | 'scope'
+  | 'support'
+  | 'canvas'
+>;
+
+export interface AgentSidePaneProps {
+  controller: AgentPaneController;
+  /** Memoise it: a new object every render re-renders the whole chat. */
+  adapters: AgentSidePaneAdapters;
+  hostContext?: AgentHostContext | null;
+  scope?: AgentScopeAdapter | null;
+  support?: AgentSupportAdapter | null;
+  canvas?: HostCanvasContextValue;
+  className?: string;
+  /** Accessible name of the pane landmark. Default "Ask CXO assistant". */
+  ariaLabel?: string;
+}