cortena-ui 1.5.0 → 1.7.0

package/dist/components/agent-chat.d.ts

@@ -1,8 +1,8 @@
 "use client";
 import { A2UIAction } from "../a2ui/message.js";
 import { A2UIChatBlock } from "../agent-chat/a2ui-block.js";
-import { AgentApprovalRequest, AgentChatClient, AgentChatMessage, AgentSession } from "../agent-chat/types.js";
-import { AgentToolEntry } from "../agent-chat/store.js";
+import { AgentApprovalDecision, AgentApprovalRequest, AgentChatClient, AgentChatMessage, AgentChatStep, AgentSession } from "../agent-chat/types.js";
+import { AgentToolEntry, UseAgentChatResult } from "../agent-chat/store.js";
 import * as React from "react";
 //#region src/components/agent-chat.d.ts
 /**
@@ -26,6 +26,24 @@ export interface AgentThinkingProps {
   streaming?: boolean;
 }
 declare function AgentThinking({ text, defaultOpen, streaming }: AgentThinkingProps): React.JSX.Element | null;
+export interface AgentStepsProps {
+  steps: readonly AgentChatStep[];
+}
+/**
+ * What the agent is doing, one plain sentence per tool call (SKILLS-9).
+ *
+ * This is the surface a person watches while they wait, and it is deliberately
+ * not the tool strip: the strip is the record — names, arguments, output, the
+ * MCP App seam — and reading it requires knowing what `broker_invoke` is. The
+ * strip stays at the foot for anyone who wants the detail.
+ *
+ * NOT a live region of its own. The strip is drawn inside the transcript, and
+ * the transcript is already `role="log" aria-live="polite"` — two nested live
+ * regions is one announcement per change from the inner one and another from
+ * the outer, which is how a screen reader ends up saying every step twice.
+ * `aria-label` stays: it names the group for anyone who navigates to it.
+ */
+declare function AgentSteps({ steps }: AgentStepsProps): React.JSX.Element | null;
 export interface AgentA2UIBlocksProps {
   blocks: readonly A2UIChatBlock[] | undefined;
   /** Set on the streaming bubble: actions are disabled while the turn is live. */
@@ -59,6 +77,8 @@ export interface AgentStreamingBubbleProps {
   text: string;
   thinkingText: string;
   a2ui: readonly A2UIChatBlock[];
+  /** The turn's tool calls in plain words, drawn under the agent's name. */
+  steps?: readonly AgentChatStep[];
 }
 /**
  * The assistant bubble while a turn is live.
@@ -69,7 +89,7 @@ export interface AgentStreamingBubbleProps {
  * (`**bo`) looks worse than its raw form — so the streaming view is plain text
  * under `whitespace-pre-wrap` and `Markdown` takes over on `final`.
  */
-declare function AgentStreamingBubble({ agentName, text, thinkingText, a2ui }: AgentStreamingBubbleProps): React.JSX.Element;
+declare function AgentStreamingBubble({ agentName, text, thinkingText, a2ui, steps }: AgentStreamingBubbleProps): React.JSX.Element;
 /** A `ui://` resource in a tool result is an MCP App: the extension's own screen. */
 export declare function readMcpAppUri(output: unknown): string | null;
 export interface AgentToolCardProps {
@@ -98,19 +118,118 @@ export interface AgentToolRenderContext {
   /** The `ui://` resource this result carries, when it carries one. */
   mcpAppUri: string | null;
 }
-export interface AgentChatProps extends Omit<React.ComponentProps<"div">, "children" | "onError"> {
-  /** The transport. `createAguiAgentChatClient` is the AG-UI implementation. */
-  client: AgentChatClient;
-  /** The extension name, shown on each assistant turn. */
+/**
+ * What a host's own message bubble receives. `index` and `messages` are over
+ * the VISIBLE messages — the filter chain has already run — so
+ * `messages[index - 1]` is the turn before this one, which a feedback control
+ * or a transcript export wants.
+ */
+export interface AgentChatMessageSlotProps {
+  message: AgentChatMessage;
+  index: number;
+  messages: readonly AgentChatMessage[];
+  agentName: string;
+  sessionKey: string | null;
+  /** True while a run is live; every A2UI surface goes read-only. */
+  streaming: boolean;
+  onAction: (action: A2UIAction) => void;
+}
+export interface AgentChatStreamingSlotProps {
+  agentName: string;
+  text: string;
+  thinkingText: string;
+  a2ui: readonly A2UIChatBlock[];
+  /** The turn's tool calls in plain words; the default draws them under the name. */
+  steps: readonly AgentChatStep[];
+}
+export interface AgentChatEmptySlotProps {
   agentName: string;
+  /** A history load is in flight for this session; a skeleton fits here. */
+  loadingHistory: boolean;
+}
+export interface AgentChatLoadOlderSlotProps {
+  hasMore: boolean;
+  loading: boolean;
+  onLoad: () => void;
+}
+export interface AgentChatToolsSlotProps {
+  entries: readonly AgentToolEntry[];
+  approvals: readonly AgentApprovalRequest[];
+  streaming: boolean;
   /**
-   * Names the `sessionStorage` slot this window's session key lives in. Scope
-   * it to the extension id; two chats with different scopes never share a key.
+   * The host's `renderToolCall`, as it was passed: `undefined` for a call the
+   * host declines, so the slot can draw its own line for those and still mount
+   * an MCP App through the one seam the component defines.
    */
-  storageScope: string;
-  /** Do not read or write `sessionStorage`; for a guide or a test. */
-  ephemeral?: boolean;
-  thinking?: "low" | "medium" | "high";
+  renderToolCall: ((context: AgentToolRenderContext) => React.ReactNode | undefined) | undefined;
+  onResolveApproval: (id: string, decision: AgentApprovalDecision) => void;
+}
+export interface AgentChatComposerSlotProps {
+  agentName: string;
+  streaming: boolean;
+  send: UseAgentChatResult["send"];
+  abort: () => void;
+}
+/**
+ * Renders a host may substitute for the component's own, one region each.
+ *
+ * The surface — its state, the order of its regions, the scroller that stays
+ * pinned to the bottom, the sentinel that pages history, the steps and the
+ * tool-card seam — is shared; what each region LOOKS like need not be. This is
+ * how cortenaweb draws its own bubble (Shiki, KaTeX, feedback controls, a
+ * timestamp chip) and its own composer (attachments, agent and model
+ * selectors) on the shared surface instead of keeping a second chat
+ * (PLATFORM-64).
+ *
+ * A component given here replaces its region whole, wrapper included; nothing
+ * of the default is drawn around it.
+ */
+export interface AgentChatComponents {
+  Message: React.ComponentType<AgentChatMessageSlotProps>;
+  /**
+   * The live bubble. It is handed `steps` because the default draws the
+   * progress steps INSIDE the streaming bubble; a host's own bubble draws them
+   * itself, or not at all — nothing else draws them while a run is live.
+   */
+  Streaming: React.ComponentType<AgentChatStreamingSlotProps>;
+  /**
+   * Replaces the whole transcript region while there is nothing to show. Not
+   * while there is an error: the transcript then mounts with the error banner
+   * in it, so a failure before the first message is not hidden behind the
+   * host's welcome screen.
+   */
+  Empty: React.ComponentType<AgentChatEmptySlotProps>;
+  /** Drawn at the top of the transcript while there is, or may be, more. */
+  LoadOlder: React.ComponentType<AgentChatLoadOlderSlotProps>;
+  /** Replaces the tool strip and the approval cards at the foot. */
+  Tools: React.ComponentType<AgentChatToolsSlotProps>;
+  Composer: React.ComponentType<AgentChatComposerSlotProps>;
+}
+/**
+ * Class names for the wrappers a host cannot otherwise reach.
+ *
+ * `transcript` REPLACES the default spacing (`gap-5 px-4 py-4`) rather than
+ * merging with it: a reading column sets its own gutter through a class, and a
+ * utility left on the element would fight it. The structural classes — flex,
+ * min-width — stay in either case.
+ */
+export interface AgentChatClassNames {
+  header?: string;
+  scroll?: string;
+  transcript?: string;
+  /**
+   * The history sentinel at the top of the transcript. Out of the flow by
+   * default (`absolute inset-x-0 top-0 h-px`), so it adds no space; a host
+   * whose column already reserved a row for it passes an in-flow class.
+   */
+  sentinel?: string;
+  tools?: string;
+  composer?: string;
+}
+/** What every `AgentChat` takes, however its state is owned. */
+export interface AgentChatBaseProps extends Omit<React.ComponentProps<"div">, "children" | "onError"> {
+  /** The extension name, shown on each assistant turn. */
+  agentName: string;
   /** Rendered between the tool strip and the composer — an attachment picker. */
   attachmentsSlot?: React.ReactNode;
   /**
@@ -121,8 +240,65 @@ export interface AgentChatProps extends Omit<React.ComponentProps<"div">, "child
   renderToolCall?: (context: AgentToolRenderContext) => React.ReactNode | undefined;
   /** Header content, e.g. the pop-up's own window controls. */
   headerSlot?: React.ReactNode;
+  /** No header at all — for a host with its own session list and New button. */
+  hideHeader?: boolean;
+  /** The host's own renders for each region. See `AgentChatComponents`. */
+  components?: Partial<AgentChatComponents>;
+  /** Classes for the wrappers. See `AgentChatClassNames`. */
+  classNames?: AgentChatClassNames;
+  /**
+   * Page older history from the sentinel at the top of the transcript as the
+   * reader reaches it, not only from the `LoadOlder` button. Off by default —
+   * the pop-up pages on a click. When on, it is armed only once the scroller
+   * overflows: a transcript shorter than its viewport has its sentinel
+   * permanently in view, and paging on that pulled every page the server had
+   * into a chat with three messages in it.
+   */
+  autoLoadOlder?: boolean;
 }
-declare function AgentChat({ client, agentName, storageScope, ephemeral, thinking, attachmentsSlot, renderToolCall, headerSlot, className, ...props }: AgentChatProps): React.JSX.Element;
+/**
+ * The surface owning its own state: it calls `useAgentChat` on the client it is
+ * given. This is what `AgentChatPopup` mounts.
+ */
+export interface AgentChatOwnedProps extends AgentChatBaseProps {
+  /** The transport. `createAguiAgentChatClient` is the AG-UI implementation. */
+  client: AgentChatClient;
+  /**
+   * Names the `sessionStorage` slot this window's session key lives in. Scope
+   * it to the extension id; two chats with different scopes never share a key.
+   */
+  storageScope: string;
+  /** Do not read or write `sessionStorage`; for a guide or a test. */
+  ephemeral?: boolean;
+  thinking?: "low" | "medium" | "high";
+  chat?: undefined;
+}
+/**
+ * The surface drawing state the host owns.
+ *
+ * A host that needs the state OUTSIDE the surface — a sidebar that lists
+ * sessions, a shortcut that stops the run, a page that routes on the session
+ * key — holds it itself and passes a `UseAgentChatResult` here; the surface
+ * then draws that state instead of holding its own. The result may come from
+ * `useAgentChat`, or from a store of the host's own projected onto the same
+ * shape, which is how cortenaweb drives this surface from the zustand stores
+ * the rest of its shell reads (PLATFORM-64). No client, no storage: the host
+ * owns both.
+ */
+export interface AgentChatHostedProps extends AgentChatBaseProps {
+  chat: UseAgentChatResult;
+  client?: undefined;
+  storageScope?: undefined;
+  ephemeral?: undefined;
+  thinking?: undefined;
+}
+export type AgentChatProps = AgentChatOwnedProps | AgentChatHostedProps;
+/**
+ * Two ways in, one surface. The hook is called in a component of its own so
+ * a host that hands over `chat` never calls it — and so a mount that switches
+ * from one mode to the other remounts rather than changing its hook order.
+ */
+declare function AgentChat(props: AgentChatProps): React.JSX.Element;
 export interface AgentSessionDrawerProps {
   sessions: readonly AgentSession[];
   current: string | null;
@@ -139,5 +315,5 @@ export interface AgentSessionDrawerProps {
  */
 declare function AgentSessionDrawer({ sessions, current, loading, onResume }: AgentSessionDrawerProps): React.JSX.Element;
 //#endregion
-export { AgentA2UIBlocks, AgentApprovalCard, AgentChat, AgentMessageBubble, AgentSessionDrawer, AgentStreamingBubble, AgentThinking, AgentToolCard };
+export { AgentA2UIBlocks, AgentApprovalCard, AgentChat, AgentMessageBubble, AgentSessionDrawer, AgentSteps, AgentStreamingBubble, AgentThinking, AgentToolCard };
 //# sourceMappingURL=agent-chat.d.ts.map