@streamoid/agent 0.6.51 → 0.6.53

package/README.md

@@ -53,10 +53,13 @@ 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.

package/dist/index.d.ts

@@ -50,6 +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 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;
 }
 
@@ -63,6 +77,19 @@ export interface AgentSurfaceState {
   activePanel?: { id: string; kind: string; title: string } | null;
 }
 
+/** `adapters.support` — what the "Get help" home ({@link showAgentSupport})
+ *  and its messages say about the host. All optional; the home works without. */
+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 in the Get help
+   * home's "We'll include" chip. A `hostContext.app_version` the host passes
+   * itself wins over this.
+   */
+  appVersion?: string;
+}
+
 export interface AgentChatShellAdapters {
   auth: AgentChatShellAuth;
   workspace: { current: AgentChatShellWorkspace };
@@ -162,6 +189,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
@@ -171,6 +208,12 @@ export interface AgentChatShellAdapters {
    * offered the widening by the run that needs it.
    */
   scope?: AgentScopeAdapter | null;
+  /**
+   * Details for the "Get help" home ({@link showAgentSupport}) and for message
+   * routing. Purely additive. There are deliberately no billing or credit
+   * callbacks: the billing flow runs in the chat, driven by the support agent.
+   */
+  support?: AgentSupportAdapter | null;
 }
 
 export interface AgentScopeOutcome {
@@ -231,13 +274,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
@@ -448,3 +493,55 @@ export declare function enqueueChatPrompt(
  * mounts, so reveal-then-call and call-then-reveal both work.
  */
 export declare function focusAgentComposer(): void;
+
+/**
+ * Open the pane's "Get help" home. Call it from the app switcher's "Help and
+ * Support" row, in the same handler that reveals the pane.
+ *
+ * This REPLACES `enqueueChatPrompt({ prompt: "I need help and support",
+ * forceNewConversation: true })`, which auto-sent a message. This sends
+ * nothing: the pane shows a fresh, empty conversation as the Get help home —
+ * a title, an incident banner when a product is degraded, the ordinary
+ * composer, a "We'll include" line and four cards (Ask a question, Report a
+ * problem, Talk to the Streamoid team, Billing and credits). A card sends its
+ * prompt through the chat's own send path; typing works as usual.
+ *
+ * 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.
+ *
+ * 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
+ * pane mounts. Calling it while another conversation is open starts a new,
+ * 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(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;
+}