@streamoid/agent 0.6.53 → 0.6.54

package/README.md

@@ -63,3 +63,127 @@ 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

@@ -164,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
@@ -545,3 +558,123 @@ export interface ShowAgentSupportOptions {
    */
   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;
+}