@dataverse-kit/agent-kit 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,863 @@
+import * as React$1 from 'react';
+import { A as AgentMessage, a as AgentParticipant, b as AgentFailure, c as AgentRunStatus, d as AgentAvailability, e as AgentUsage, f as AgentSource, g as AgentCitation, h as AgentToolCall, i as AgentAttachment, I as IAgentService } from './protocol-CZJ1v9Hq.cjs';
+export { j as AgentCapabilities, k as AgentEvent, l as AgentProviderName, m as AgentRole, n as AgentServiceConfig, o as AgentTurn, p as AgentTurnResult, T as ToolCallStatus } from './protocol-CZJ1v9Hq.cjs';
+import { Announcement, DayDividerLabel, ConversationState } from './core.cjs';
+export { ANNOUNCE_FULL_TEXT_MAX_CHARS, CitationSegment, ClaudeLikeStreamEvent, ConversationStatus, DEFAULT_GROUP_WINDOW_MS, DayBucket, ExtractedMarker, FoundryLikeResult, GroupingOptions, MessageGroup, NO_ANNOUNCEMENT, NormalizeCtx, STICK_TO_BOTTOM_THRESHOLD_PX, ScrollGeometry, appendUserMessage, applyAgentEvent, bucketByDay, classifyTransportFailure, createIdPrefixCounter, dayKeyOf, deriveAnnouncement, extractCitationMarkers, fromClaudeStreamEvent, fromFoundryChatResult, fromOpenAiChatChunk, fromSseLine, groupMessages, initialConversation, isSameAuthorRun, isTerminalStatus, renumberCitations, runStatusSeverity, shouldStickToBottom, splitTextByCitations } from './core.cjs';
+import { BadgeProps } from '@fluentui/react-components';
+export { A as AgentKitHostProvider, a as AgentKitHostProviderProps, R as ResolveHostThemeInput, b as agentDarkTheme, c as agentTheme, d as createAgentDarkTheme, e as createAgentTheme, n as nextAgentIdPrefix, r as resolveHostTheme } from './index-DGN6eYnp.cjs';
+export { MockAgentService, MockAgentServiceOptions, MockScenario, MockScenarioName, NullAgentService, Scheduler, createAgentService, decide, immediateScheduler, mockScenarios, realScheduler } from './services.cjs';
+
+interface MessageActionsProps {
+    message: AgentMessage;
+    onCopy?: (message: AgentMessage) => void;
+    onRetry?: (message: AgentMessage) => void;
+    onFeedback?: (message: AgentMessage, vote: 'up' | 'down') => void;
+}
+/**
+ * The hover row on a message.
+ *
+ * ★★ It is revealed by `:hover` **or `:focus-within`** — see MessageBubble's styles. A
+ *    hover-only affordance is a WCAG 2.1.1 (Keyboard, Level A) failure outright: there is no
+ *    pointer-free route to it at all. The other naive choice, leaving the row permanently in
+ *    the tab order, adds N tab stops per message. Reveal-on-focus plus a roving tabindex gives
+ *    exactly one tab stop per message and a keyboard route to every action.
+ */
+declare function MessageActions({ message, onCopy, onRetry, onFeedback, }: MessageActionsProps): React$1.ReactElement | null;
+
+interface MessageListProps extends Omit<MessageActionsProps, 'message'> {
+    messages: readonly AgentMessage[];
+    participants?: readonly AgentParticipant[];
+    /** Renders the typing indicator and suppresses the "jump to latest" nudge. */
+    busy?: boolean;
+    announcement?: Announcement;
+    groupWindowMs?: number;
+    timeZone?: string;
+    locale?: string;
+    /** Injected so day labels are deterministic in tests and Chromatic. */
+    now?: number;
+    emptyState?: React$1.ReactNode;
+}
+/**
+ * The transcript.
+ *
+ * ★ It is NOT a live region. Announcements go through `LiveAnnouncer`, fed by
+ *   `deriveAnnouncement` on state TRANSITIONS — a live region over the streaming node queues
+ *   every token and a screen reader never finishes reading.
+ *
+ * ★ Grouping (avatar + name once per run) is VISUAL. Every `MessageBubble` still carries its
+ *   author and timestamp in the accessible tree.
+ */
+declare function MessageList(props: MessageListProps): React$1.ReactElement;
+
+interface MessageBubbleProps extends Omit<MessageActionsProps, 'message'> {
+    message: AgentMessage;
+    author?: AgentParticipant;
+    /** First message of a run — renders the avatar and name. */
+    isRunStart?: boolean;
+    locale?: string;
+}
+declare function MessageBubble(props: MessageBubbleProps): React$1.ReactElement;
+
+interface StreamingTextProps {
+    text: string;
+    streaming?: boolean;
+}
+/**
+ * The in-flight answer.
+ *
+ * ★ A STABLE element, deliberately. If this subtree remounted per token, any focus inside the
+ *   streaming bubble (a citation chip, a copy button) would be thrown to `<body>` mid-answer.
+ *   Only the text node changes; the element identity does not. `useStreamingText.test.tsx`
+ *   pins that as an invariant rather than leaving it to a comment.
+ */
+declare function StreamingText({ text, streaming }: StreamingTextProps): React$1.ReactElement;
+
+interface TypingIndicatorProps {
+    /** Announced. Keep it short — it interrupts nothing but is read on appearance. */
+    label?: string;
+}
+/**
+ * ★ This carries "the assistant is responding" for screen readers, via its own `role="status"`
+ *   firing when it MOUNTS. That is why `deriveAnnouncement` does not also announce the start —
+ *   doing both would say it twice.
+ */
+declare function TypingIndicator({ label }: TypingIndicatorProps): React$1.ReactElement;
+
+interface ComposerProps {
+    value: string;
+    onChange: (value: string) => void;
+    onSend: (value: string) => void;
+    onStop?: () => void;
+    busy?: boolean;
+    disabled?: boolean;
+    placeholder?: string;
+    maxLength?: number;
+    /** 'enter' sends on Enter; 'mod+enter' needs Ctrl/Cmd. */
+    sendOn?: 'enter' | 'mod+enter';
+    /** Rendered left of the send button — attachments, formatting, etc. */
+    toolbar?: React$1.ReactNode;
+}
+/**
+ * The send box.
+ *
+ * ★ `sendOn` is configurable, and defaults to Enter only because that is what users expect
+ *   from Teams. Enter-to-send in a multiline field is hostile to dictation and voice control,
+ *   and Shift+Enter is undiscoverable — hence the `aria-describedby` hint, which makes the
+ *   contract audible instead of folklore.
+ *
+ * ★ Deliberately NOT Fluent's `Toolbar` for the affordance row: it reaches
+ *   `useArrowNavigationGroup`. Consumers pass plain buttons, or the in-tree ActionToolbar.
+ */
+declare function Composer(props: ComposerProps): React$1.ReactElement;
+
+interface SuggestedPromptsProps {
+    prompts: readonly string[];
+    onPick: (prompt: string) => void;
+    heading?: string;
+}
+/** ★ Plain Buttons in a labelled list, not Fluent's `TagGroup` — `react-tags` reaches
+ *  `useArrowNavigationGroup`, and chips gain nothing from it here. */
+declare function SuggestedPrompts({ prompts, onPick, heading, }: SuggestedPromptsProps): React$1.ReactElement | null;
+
+interface EmptyConversationProps {
+    title?: string;
+    description?: string;
+    prompts?: readonly string[];
+    onPick?: (prompt: string) => void;
+}
+declare function EmptyConversation({ title, description, prompts, onPick, }: EmptyConversationProps): React$1.ReactElement;
+
+interface SystemNoticeProps {
+    failure?: AgentFailure;
+    guarded?: boolean;
+    onRetry?: () => void;
+}
+/**
+ * A terminal state the user needs to see.
+ *
+ * ★ `blocked` / `refused` / `notProvisioned` render as WARNING or INFO, not error — they are
+ *   different outcomes needing different fixes, and flattening them into "something went
+ *   wrong" is what makes an unprovisioned environment look broken.
+ * ★ The state is in the TEXT, never only in the colour (WCAG 1.4.1).
+ */
+declare function SystemNotice({ failure, guarded, onRetry }: SystemNoticeProps): React$1.ReactElement | null;
+
+interface DayDividerProps {
+    label: DayDividerLabel;
+    locale?: string;
+}
+/** Map the pure descriptor to words. ★ The formatting lives HERE, not in ./core, so the host
+ *  can localise it and so the core function stays deterministic across CI locales. */
+declare function formatDayLabel(label: DayDividerLabel, locale?: string): string;
+/** ★ `role="separator"` with an accessible name. A bare text node floating between list items
+ *  reads as a message. */
+declare function DayDivider({ label, locale }: DayDividerProps): React$1.ReactElement;
+
+interface AgentStatusBadgeProps {
+    status: AgentRunStatus;
+    /** Shown in a tooltip — the provider's own message, when there is one. */
+    reason?: string;
+    size?: BadgeProps['size'];
+}
+/** Exported so the label contract can be asserted directly rather than scraped from markup. */
+declare function runStatusLabel(status: AgentRunStatus): string;
+declare function AgentStatusBadge({ status, reason, size }: AgentStatusBadgeProps): React$1.ReactElement;
+
+interface AvailabilityBannerProps {
+    availability?: AgentAvailability;
+    onRetry?: () => void;
+    /** Rendered beside Retry — a link to the setup doc, a "Configure" button. */
+    actions?: React$1.ReactNode;
+}
+/**
+ * Whether the agent can answer here, and if not, why.
+ *
+ * ★★ `notProvisioned` renders as INFORMATION, not an error. Nobody having configured the service
+ *    yet is a normal state in an on-demand Azure estate; dressing it as a failure is what makes a
+ *    working app look broken, and it needs a completely different response from an outage.
+ *
+ * ★ `reason` is displayed rather than summarised. "Not licensed" and "not on this host" need
+ *   different fixes, and the seam keeps them distinct precisely so the UI can say which.
+ */
+declare function AvailabilityBanner({ availability, onRetry, actions, }: AvailabilityBannerProps): React$1.ReactElement | null;
+
+interface UsageMeterProps {
+    usage?: AgentUsage;
+    show?: readonly ('tokens' | 'cost' | 'duration' | 'model')[];
+}
+/**
+ * Tokens, cost, latency.
+ *
+ * ★★ "Not reported" is rendered as such, never as 0. A provider that does not report cost and
+ *    one that cost nothing are completely different facts, and showing `$0.00` for the first is
+ *    a confident lie — the kind that gets believed because it looks like data.
+ */
+declare function UsageMeter({ usage, show, }: UsageMeterProps): React$1.ReactElement | null;
+
+interface ThrottleNoticeProps {
+    failure?: AgentFailure;
+    onRetry?: () => void;
+    /** Injected so the countdown is testable without fake timers. */
+    now?: () => number;
+}
+/**
+ * A rate-limit notice that counts down.
+ *
+ * ★ It renders only for a failure that is BOTH retriable and carries `retryAfterMs`. A countdown
+ *   over an unknown wait would be invented, and a retry button that fires into an active throttle
+ *   just burns the next window.
+ */
+declare function ThrottleNotice({ failure, onRetry, now }: ThrottleNoticeProps): React$1.ReactElement | null;
+
+interface ModelBadgeProps {
+    provider?: string;
+    model?: string;
+    version?: string;
+}
+/** Which agent, which model, which version — so a run can be traced to a configuration. */
+declare function ModelBadge({ provider, model, version }: ModelBadgeProps): React$1.ReactElement | null;
+
+/** An agent a host can offer. Names WHICH agent answers — never a credential. */
+interface AgentDescriptor {
+    id: string;
+    name: string;
+    model?: string;
+    version?: string;
+    description?: string;
+    /** Last known health. `undefined` means "not probed", which is not the same as healthy. */
+    status?: AgentRunStatus;
+}
+/** One completed turn, for the run history. */
+interface AgentRunRecord {
+    id: string;
+    status: AgentRunStatus;
+    startedAt: number;
+    prompt?: string;
+    usage?: AgentUsage;
+    correlationId?: string;
+    model?: string;
+}
+
+interface AgentPickerProps {
+    agents: readonly AgentDescriptor[];
+    selectedId?: string;
+    onSelect: (id: string) => void;
+    label?: string;
+    disabled?: boolean;
+}
+/**
+ * Choose which agent answers.
+ *
+ * ★ Fluent's `Dropdown` — measured tabster-safe. `react-combobox` imports only
+ *   `useTabsterAttributes`, `useMergedTabsterAttributes_unstable`, `useSetKeyboardNavigation` and
+ *   `useOnKeyboardNavigationChange`; `useTabsterAttributes` calls `useTabster()` with NO argument,
+ *   and `useTabster`'s default factory is the identity, so it never reaches a `get*` factory or
+ *   `attrHandlers.set`. Two reviewers disagreed about this and the source settled it.
+ *
+ * ★ Selecting an agent is a CONFIG change, not a capability change: the seam still has no write
+ *   method whichever agent is chosen.
+ */
+declare function AgentPicker({ agents, selectedId, onSelect, label, disabled, }: AgentPickerProps): React$1.ReactElement;
+
+interface RunTimelineProps {
+    message: AgentMessage;
+    /** Collapsed by default: a trace is diagnostic, not the primary reading. */
+    defaultOpen?: boolean;
+}
+/**
+ * What one turn actually did: its outcome, the tools it called, what it cited, what it cost.
+ *
+ * ★ An ORDERED LIST, not Fluent's `Tree`. `react-tree` reaches `useArrowNavigationGroup`, and a
+ *   trace is a sequence — the ordering is the information. If steps ever nest, revisit rather
+ *   than flattening a tree into a list.
+ *
+ * ★ Each step's status is in TEXT beside it. A row of coloured dots conveys nothing to a
+ *   screen reader and little to a colour-blind reader.
+ */
+declare function RunTimeline({ message, defaultOpen }: RunTimelineProps): React$1.ReactElement | null;
+
+interface RunHistoryPanelProps {
+    runs: readonly AgentRunRecord[];
+    /**
+     * A grid to render instead of the built-in list.
+     *
+     * ★★ THIS SLOT IS WHY THERE IS NO `RunHistoryList`. A run history is tabular, and this repo
+     *    already ships a grid — `@dataverse-kit/grid-kit/v9` — with sorting, virtualisation and
+     *    column chooser. Re-implementing a thin version here would be a second grid to maintain
+     *    and a worse one.
+     *
+     *    It is a SLOT rather than a dependency because grid-kit/v9's `DataGrid` builds on
+     *    `react-table` and its toolbar on `Menu`, both of which reach tabster. A host that accepts
+     *    that passes a grid in; a host that does not gets the fallback list below. That is
+     *    surface-kit's documented "pass grids in as children" pattern, and it moves the tabster
+     *    decision to the host, where it belongs.
+     */
+    grid?: React$1.ReactNode;
+    locale?: string;
+    emptyLabel?: string;
+}
+declare function RunHistoryPanel({ runs, grid, locale, emptyLabel, }: RunHistoryPanelProps): React$1.ReactElement;
+
+interface AgentOpsPanelProps {
+    availability?: AgentAvailability;
+    agents?: readonly AgentDescriptor[];
+    selectedAgentId?: string;
+    onSelectAgent?: (id: string) => void;
+    runs?: readonly AgentRunRecord[];
+    /** Passed straight through to RunHistoryPanel — see that component for why it is a slot. */
+    runsGrid?: React$1.ReactNode;
+    onRefresh?: () => void;
+    locale?: string;
+}
+/** The composed ops surface: is it available, which agent, what has it done. */
+declare function AgentOpsPanel(props: AgentOpsPanelProps): React$1.ReactElement;
+
+interface AgentAppShellProps {
+    /** The left icon rail. Hidden below `sm`. */
+    rail?: React$1.ReactNode;
+    /** The conversation list. Collapses to an overlay below `md`. */
+    sidebar?: React$1.ReactNode;
+    /** The conversation header, above the main region. */
+    header?: React$1.ReactNode;
+    /** The transcript + composer. */
+    children?: React$1.ReactNode;
+    /** The detail pane. Hidden below `lg` — the consumer decides what to do with it there. */
+    rightPane?: React$1.ReactNode;
+    sidebarWidth?: number;
+    /**
+     * Drive the layout from a KNOWN width instead of measuring.
+     *
+     * ★ Mirrors `FormSurface.containerWidth` in surface-kit/v9, and exists for the same reason: a
+     *   PCF host already knows its `context.allocatedWidth`, so making it wait for a
+     *   ResizeObserver round-trip is a needless reflow. It is also what makes the collapse
+     *   TESTABLE — jsdom's ResizeObserver is a stub that never fires, so a measured width stays 0
+     *   forever and only the roomy branch would ever run.
+     */
+    containerWidth?: number;
+    /** Controlled sidebar visibility on narrow widths. */
+    sidebarOpen?: boolean;
+    onSidebarOpenChange?: (open: boolean) => void;
+    label?: string;
+}
+/**
+ * The Teams-like frame: rail │ list │ conversation │ detail pane.
+ *
+ * ★★ BOUNDARY WITH surface-kit, in one sentence: **surface-kit owns record/form geometry;
+ *    agent-kit owns conversation geometry.** `FormSurface`/`Section`/`PivotSurface` are for a
+ *    Dataverse record; this is for a thread. `MasterDetailSurface` is not this — it is v8-only
+ *    and two-pane. When surface-kit's deferred v9 composites land, this row is the one to check
+ *    for overlap.
+ *
+ * ★★ IT IS NOT A SECOND BREAKPOINT AUTHORITY. The cutoffs come from
+ *    `@dataverse-kit/surface-kit/v9` (`BREAKPOINTS`, `resolveBreakpoint`), which surface-kit's
+ *    CLAUDE.md states as an invariant: "every responsive stacking decision flows through
+ *    responsive/builders.ts". Redeclaring 480/768 here is how two files start disagreeing.
+ *
+ * ★ It measures its CONTAINER, not the viewport (`useContainerWidth`). A PCF control or a
+ *   custom page occupies a pane, not a window — `context.allocatedWidth`, not `window.innerWidth`
+ *   — so a viewport media query would collapse the wrong way in the host this kit targets.
+ */
+declare function AgentAppShell(props: AgentAppShellProps): React$1.ReactElement;
+
+type PresenceState = 'available' | 'busy' | 'away' | 'offline' | 'dnd' | 'unknown';
+/**
+ * One row in the conversation list.
+ *
+ * ★★ THE LIST IS FLAT, AND THAT IS A DECISION.
+ *
+ *    A Teams *chat* list — which is what this models, and what the reference screenshot shows —
+ *    is flat: a sequence of conversations. A Teams *teams/channels* tree is not, and it would
+ *    need `role="tree"` with `treeitem`/`group`/`aria-level`/`aria-expanded` and Right/Left
+ *    expand-collapse. That is a genuinely different widget, and hand-rolling APG Tree is large;
+ *    if nesting is ever needed, use Fluent's `Tree` behind the host's `targetDocument` isolation
+ *    rather than growing this one.
+ */
+interface ConversationSummary {
+    id: string;
+    title: string;
+    /** Last message, one line. */
+    preview?: string;
+    timestamp?: number;
+    unreadCount?: number;
+    participant?: AgentParticipant;
+    presence?: PresenceState;
+    /** Renders a muted style and omits unread from the accessible name. */
+    muted?: boolean;
+}
+interface RailItem {
+    id: string;
+    label: string;
+    icon: React.ReactElement;
+    badgeCount?: number;
+}
+
+interface AppRailProps {
+    items: readonly RailItem[];
+    selectedId?: string;
+    onSelect: (id: string) => void;
+    /** Items beyond this many move into the overflow menu. */
+    maxVisible?: number;
+    label?: string;
+    footer?: React$1.ReactNode;
+}
+/**
+ * The left icon rail.
+ *
+ * ★★ The overflow uses Fluent's real `Menu`, which reaches `useArrowNavigationGroup` → tabster.
+ *    That is DELIBERATE, per the split-by-cost decision: a menu is a genuine APG widget (focus
+ *    trap, typeahead, Escape, roving) and hand-rolling it is 100+ LOC, whereas a PCF host closes
+ *    the tabster gap in one line with `targetDocument`. The coexistence spike (see CLAUDE.md)
+ *    measured two cores on one window and found no double-handling, so this is safe under
+ *    isolation. `Menu` is the ONE tabster-touching component in the shell.
+ *
+ * ★ Each rail button is its own tab stop deliberately: the rail is app-level navigation, not a
+ *   composite widget, and roving it would hide destinations from a Tab-only user.
+ */
+declare function AppRail(props: AppRailProps): React$1.ReactElement;
+
+interface ConversationListProps {
+    items: readonly ConversationSummary[];
+    selectedId?: string;
+    onSelect: (id: string) => void;
+    label?: string;
+    locale?: string;
+    empty?: React$1.ReactNode;
+}
+/**
+ * The chat list.
+ *
+ * ★★ A LISTBOX with `aria-activedescendant`, not a stack of buttons and not a `Tree`.
+ *
+ *    A bare button list is not a simpler tree — it is a widget with no collection semantics at
+ *    all: N tab stops, no selected state, no set size or position, no arrow navigation. A
+ *    listbox is ONE tab stop, Up/Down/Home/End move an active option, and `aria-selected` says
+ *    which conversation is open.
+ *
+ *    `Tree` would be right if this nested (teams → channels); it does not — see ./types.ts,
+ *    where that decision is written down.
+ *
+ * ★ Modelled on the estate's existing activedescendant listbox
+ *   (`shared/pcf-gallery/controls/choice-grid/.../ChoiceGridApp.tsx`), including the detail that
+ *   `scrollIntoView` is guarded on the METHOD (`?.()`), not just the element: it is not
+ *   implemented everywhere a React tree runs, and an unguarded call inside an effect does not
+ *   degrade — it throws, React unmounts, and the list renders nothing.
+ */
+declare function ConversationList(props: ConversationListProps): React$1.ReactElement;
+
+interface ConversationListItemProps {
+    summary: ConversationSummary;
+    selected: boolean;
+    active: boolean;
+    id: string;
+    locale?: string;
+    onSelect: (id: string) => void;
+}
+/**
+ * Build the row's accessible name.
+ *
+ * ★★ Unread count and presence go in the NAME, not only in a badge and a colour dot. A screen
+ *    reader hearing "Contoso" forty times learns nothing about which conversations are waiting,
+ *    and a colour-only unread indicator is a WCAG 1.4.1 failure. Exported so it can be asserted
+ *    directly rather than inferred from rendered markup.
+ */
+declare function conversationAccessibleName(summary: ConversationSummary, locale?: string): string;
+declare function ConversationListItem(props: ConversationListItemProps): React$1.ReactElement;
+
+interface ConversationTab {
+    id: string;
+    label: string;
+}
+interface HeaderAction {
+    key: string;
+    label: string;
+    icon?: React$1.ReactElement;
+    onClick: () => void;
+}
+interface ConversationHeaderProps {
+    title: string;
+    subtitle?: string;
+    participant?: AgentParticipant;
+    presence?: PresenceState;
+    tabs?: readonly ConversationTab[];
+    selectedTabId?: string;
+    onTabSelect?: (id: string) => void;
+    actions?: readonly HeaderAction[];
+    /** Rendered right of the tabs — a search box, a right-pane toggle. */
+    trailing?: React$1.ReactNode;
+}
+/**
+ * The bar above the transcript: who you are talking to, the tab strip, and the actions.
+ *
+ * ★★ The tab strip is Fluent's real `TabList`, and that is DELIBERATE. `react-tabs` reaches
+ *    `useArrowNavigationGroup` → `getMover` → tabster, but rebuilding it by hand is not the
+ *    "simple horizontal list" it looks like: tabster's Mover carries RTL inversion,
+ *    Home/End/PageUp/PageDown, cyclic wrap, disabled-item skipping, and a caret-position guard
+ *    that declines arrow keys while the caret is inside a text input — roughly 120-180 LOC to
+ *    reproduce, against a widget nobody has tested. Per the split-by-cost decision the kit uses
+ *    Fluent's and the PCF host supplies an isolated `targetDocument`; the coexistence spike
+ *    measured that two tabster cores share a window without double-handling.
+ *
+ * ★ Manual activation (Fluent's default, `selectTabOnFocus` off): arrowing through the tabs must
+ *   not fire N conversation loads on the way past.
+ *
+ * ★ `aria-controls` is NOT set here. The panel these tabs govern is rendered by the consumer,
+ *   elsewhere in the tree, so the id contract would have to cross components — and an
+ *   `aria-controls` pointing at nothing is worse than none. Pass `panelId` when that contract
+ *   exists; until then the relationship is left unstated rather than stated falsely.
+ */
+declare function ConversationHeader(props: ConversationHeaderProps): React$1.ReactElement;
+
+interface RightPaneProps {
+    open: boolean;
+    title: string;
+    onClose: () => void;
+    children?: React$1.ReactNode;
+    width?: number;
+}
+/**
+ * The detail pane beside the conversation — sources, a record, a trace.
+ *
+ * ★ A plain `<aside>`, NOT Fluent's `Drawer`. `react-drawer` composes dialog internals, and an
+ *   inline pane needs none of a drawer's modality: it sits in the layout rather than over it.
+ */
+declare function RightPane({ open, title, onClose, children, width }: RightPaneProps): React$1.ReactElement | null;
+
+interface GlobalSearchBarProps {
+    value: string;
+    onChange: (value: string) => void;
+    onSubmit?: (value: string) => void;
+    placeholder?: string;
+}
+/** ★ `SearchBox` is `react-search`, which has no tabster dependency — safe. */
+declare function GlobalSearchBar({ value, onChange, onSubmit, placeholder, }: GlobalSearchBarProps): React$1.ReactElement;
+
+interface AgentAvatarProps {
+    participant?: AgentParticipant;
+    presence?: PresenceState;
+    size?: 24 | 28 | 32 | 36 | 40 | 48;
+    name?: string;
+}
+/**
+ * ★ `Avatar` and `PresenceBadge` are measured tabster-safe (`react-avatar` imports only
+ *   `createCustomFocusIndicatorStyle`; `react-badge` has no tabster dependency at all), so
+ *   these are Fluent's rather than in-tree.
+ *
+ * ★ `AvatarGroup` is NOT — it pulls `react-popover`, which reaches `useModalAttributes`. If a
+ *   facepile is ever wanted, that is the component to check first.
+ */
+declare function AgentAvatar({ participant, presence, size, name }: AgentAvatarProps): React$1.ReactElement;
+
+interface CitationChipProps {
+    marker: string;
+    source?: AgentSource;
+    onOpen?: (source: AgentSource) => void;
+}
+/** An inline `[1]`. ★ `Tooltip` is measured tabster-safe (`react-tooltip` imports only
+ *  `useIsNavigatingWithKeyboard`), so this one is Fluent's rather than in-tree. */
+declare function CitationChip({ marker, source, onOpen }: CitationChipProps): React$1.ReactElement;
+
+interface CitationListProps {
+    /** The answer text — used to work out which sources were actually cited. */
+    text: string;
+    sources: readonly AgentSource[];
+    onOpenSource?: (source: AgentSource) => void;
+    defaultOpen?: boolean;
+}
+/**
+ * The sources under an answer.
+ *
+ * ★★ IT SHOWS ONLY THE SOURCES THE TEXT ACTUALLY CITES. A retriever commonly returns a dozen
+ *    chunks for a two-citation answer, and listing all twelve implies the answer rests on
+ *    twelve things when it rests on two. That overstated provenance is what makes a citation
+ *    panel decorative instead of trustworthy, so `renumberCitations` drops the uncited ones
+ *    and renumbers what remains into first-appearance order.
+ *
+ * ★ A Disclosure, not Fluent's `Accordion`: APG's disclosure pattern is `<button aria-expanded
+ *   aria-controls>` and a labelled region, and `Accordion` reaches `useArrowNavigationGroup`
+ *   to add arrow-key movement between headers that a single source list does not need.
+ */
+declare function CitationList({ text, sources, onOpenSource, defaultOpen, }: CitationListProps): React$1.ReactElement | null;
+
+interface SourceCardProps {
+    source: AgentSource;
+    /** The marker this source was cited as, if any. */
+    marker?: string;
+    onOpen?: (source: AgentSource) => void;
+    showSnippet?: boolean;
+}
+declare function SourceCard({ source, marker, onOpen, showSnippet }: SourceCardProps): React$1.ReactElement;
+
+interface AnswerWithCitationsProps {
+    text: string;
+    citations?: readonly AgentCitation[];
+    sources?: readonly AgentSource[];
+    onOpenSource?: (source: AgentSource) => void;
+}
+/** Renders the answer with a chip where each marker was. */
+declare function AnswerWithCitations({ text, citations, sources, onOpenSource, }: AnswerWithCitationsProps): React$1.ReactElement;
+
+interface GroundingPanelProps {
+    /** The SAME object passed as `AgentTurn.grounding`. */
+    grounding?: Record<string, unknown>;
+    title?: string;
+    defaultOpen?: boolean;
+}
+/**
+ * What the model was told.
+ *
+ * ★★ It renders the SAME object the turn carried (`AgentTurn.grounding`), which is the point:
+ *    the facts the host computed deterministically and the facts shown on screen cannot drift
+ *    apart, because there is only one of them. The model EXPLAINS these; it must never be the
+ *    thing that derives them — a hallucinated identifier is worse than no answer.
+ *
+ * ★ A definition list on a CSS grid, not a `Table`: `react-table` reaches
+ *   `useArrowNavigationGroup`, and key/value pairs are not tabular data.
+ */
+declare function GroundingPanel({ grounding, title, defaultOpen, }: GroundingPanelProps): React$1.ReactElement | null;
+
+interface ProviderAttributionProps {
+    provider?: string;
+    model?: string;
+    guarded?: boolean;
+}
+/**
+ * Who produced this answer.
+ *
+ * ★★ WHEN `guarded` IS SET THE VISIBLE TEXT MUST CHANGE, and that is the whole contract.
+ *    `guarded` means the provider WITHHELD its generated answer and substituted safe text.
+ *    Attributing that substitute to the model as if it were the model's words is the
+ *    misattribution this component exists to prevent — so the difference is in words a reader
+ *    sees, not a colour, an icon or a `data-` attribute. The gate asserts BOTH directions.
+ */
+declare function ProviderAttribution({ provider, model, guarded }: ProviderAttributionProps): React$1.ReactElement | null;
+/** Convenience: read the attribution straight off a message. */
+declare function messageAttribution(message: AgentMessage): ProviderAttributionProps;
+
+interface ActionCardProps {
+    title: string;
+    description?: React$1.ReactNode;
+    icon?: React$1.ReactElement;
+    /** Renders an emphasised edge while a decision is outstanding. */
+    pending?: boolean;
+    children?: React$1.ReactNode;
+    footer?: React$1.ReactNode;
+}
+/** The container the action family shares. ★ Built on the in-tree `CardSurface`, never Fluent's
+ *  `Card` — see internal/CardSurface.tsx for why that one unmounts the tree on a form. */
+declare function ActionCard({ title, description, icon, pending, children, footer }: ActionCardProps): React$1.ReactElement;
+
+interface ApprovalCardProps {
+    toolCall: AgentToolCall;
+    onApprove: (call: AgentToolCall, argumentsJson: string) => void;
+    onDeny: (call: AgentToolCall) => void;
+    /** Enables in-place editing of the proposed arguments before approval. */
+    allowEdit?: boolean;
+    busy?: boolean;
+}
+/**
+ * A tool call awaiting a human decision.
+ *
+ * ★★ THE KIT DOES NOT RUN THE TOOL. It renders the request and raises a callback; the HOST
+ *    executes and feeds the outcome back as a `tool_result` event. That is what keeps "the kit
+ *    has no tools" a structural statement about this package rather than a promise about a
+ *    prompt — `IAgentService` has no method that could invoke one.
+ *
+ * ★★ IT CANNOT DOUBLE-SUBMIT, and that is asserted two ways, because counting the callback
+ *    alone is a one-field signature: it shows what the component SENT, and a card that
+ *    re-enables after an async settle would still submit twice later. The gate asserts one
+ *    `onApprove` across two synchronous clicks AND that the control is disabled afterwards.
+ */
+declare function ApprovalCard({ toolCall, onApprove, onDeny, allowEdit, busy, }: ApprovalCardProps): React$1.ReactElement;
+
+interface ToolCallCardProps {
+    toolCall: AgentToolCall;
+    defaultExpanded?: boolean;
+}
+/** A tool call that needed no approval — collapsed by default, expandable for the arguments.
+ *  ★ A Disclosure rather than `Accordion`: see internal/Disclosure.tsx. */
+declare function ToolCallCard({ toolCall, defaultExpanded }: ToolCallCardProps): React$1.ReactElement;
+
+interface ParameterReviewProps {
+    /** RAW arguments as the model emitted them. */
+    argumentsJson: string;
+    readOnly?: boolean;
+    onChange?: (next: string) => void;
+}
+/**
+ * The arguments a tool call is proposing, laid out for a human to check before approving.
+ *
+ * ★ A definition list on a CSS grid, NOT a `Table`/`DataGrid` — both reach
+ *   `useArrowNavigationGroup`, and this is key/value data rather than a grid.
+ *
+ * ★★ It falls back to showing the RAW string when the JSON does not parse, and that matters:
+ *    a half-streamed arguments blob is not valid JSON, and an approval UI that silently
+ *    rendered nothing would ask the user to approve something they cannot see. Showing the raw
+ *    text is honest; showing an empty table is not.
+ */
+declare function ParameterReview({ argumentsJson, readOnly, onChange }: ParameterReviewProps): React$1.ReactElement;
+
+interface ActionResultProps {
+    status: 'succeeded' | 'failed' | 'denied';
+    message: string;
+    correlationId?: string;
+    onRetry?: () => void;
+}
+/** ★ The correlation id is surfaced, not hidden: it is the only thing that lets someone paged
+ *  at 3am find this specific run in App Insights. */
+declare function ActionResult({ status, message, correlationId, onRetry }: ActionResultProps): React$1.ReactElement;
+
+interface ConfirmInlineProps {
+    open: boolean;
+    title: string;
+    body: React$1.ReactNode;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    destructive?: boolean;
+    onConfirm: () => void;
+    onCancel: () => void;
+}
+/**
+ * An in-tree confirmation, replacing Fluent's `Dialog`.
+ *
+ * ★ `react-dialog` reaches `useModalAttributes` → `getModalizer` + `getRestorer` →
+ *   `core.attrHandlers.set`. The gallery's `image-gallery-field` removed `Dialog` for exactly
+ *   this and cut its bundle 431,706 → 317,346 bytes, so the trade is well established.
+ *
+ * ★★ BUT THAT PRECEDENT SHIPS THREE FOCUS DEFECTS, AND THIS FIXES THEM. Read against it:
+ *    it focuses into the dialog and handles Escape, but it (1) never returns focus to the
+ *    trigger on close, (2) has no focus trap, so Tab walks straight out of a `role="alertdialog"`,
+ *    and (3) omits `aria-modal` — so the role asserts a modality the implementation does not
+ *    provide, which is an ARIA lie rather than a missing nicety. Removing tabster means
+ *    removing its Modalizer and Restorer, and whatever they were doing has to be done here.
+ */
+declare function ConfirmInline(props: ConfirmInlineProps): React$1.ReactElement | null;
+
+interface LiveAnnouncerProps {
+    /** Read at the next pause. Changing this to a new non-empty value announces it. */
+    polite?: string;
+    /** Interrupts. Failures only. */
+    assertive?: string;
+}
+/**
+ * The two live regions for a conversation surface.
+ *
+ * ★ The transcript itself is NOT a live region, and that is the point. A live region on the
+ *   streaming node queues every token for announcement — NVDA and JAWS re-read the growing
+ *   string and never finish. The streaming bubble carries `aria-busy`, the typing indicator's
+ *   own `role="status"` covers "responding", and this announces once per turn: the settled
+ *   answer (see `deriveAnnouncement` in ./core, which is where the rule lives).
+ *
+ * ★ `aria-atomic` so the whole message is read, not just the changed fragment.
+ */
+declare function LiveAnnouncer({ polite, assertive, }: LiveAnnouncerProps): React$1.ReactElement;
+
+/**
+ * Content available to assistive technology and not to sight.
+ *
+ * ★ NOT `display:none` and NOT `visibility:hidden` — both remove the node from the
+ *   accessibility tree, which is the opposite of the intent. The clip-rect recipe is the one
+ *   that keeps it announced.
+ */
+declare const useVisuallyHiddenStyles: () => Record<"root", string>;
+
+/**
+ * Put focus somewhere sensible when the focused element disappears.
+ *
+ * ★ Fluent's tabster ships a `Restorer` and a `Deloser` for exactly this, and the kit needs
+ *   its own because the affordances that own focus in a transcript are the in-tree ones. A
+ *   chat surface removes focusable nodes constantly — a message is deleted, an approval card
+ *   resolves, a conversation closes. When that happens the browser puts focus on `<body>`:
+ *   the keyboard user's Tab position resets to the top of the page and the screen reader
+ *   loses its place.
+ *
+ * ★ It reads `document.activeElement` rather than tracking what it believes had focus,
+ *   because the interesting case is the one where focus has ALREADY been lost.
+ */
+declare function useFocusRestore(containerRef: React$1.RefObject<HTMLElement>): () => void;
+
+interface RovingTabindexOptions {
+    orientation?: 'horizontal' | 'vertical';
+    loop?: boolean;
+    itemCount: number;
+    onActivate?: (index: number) => void;
+}
+interface RovingTabindex {
+    activeIndex: number;
+    setActiveIndex: (index: number) => void;
+    /** Spread onto each item. Exactly ONE item is tabbable at a time. */
+    getItemProps: (index: number) => {
+        tabIndex: 0 | -1;
+        'data-roving-item': true;
+        onFocus: () => void;
+        onKeyDown: (event: React$1.KeyboardEvent) => void;
+    };
+}
+/**
+ * One tab stop for a group, arrow keys within it — the WAI-ARIA roving tabindex.
+ *
+ * ★ Why this rather than Fluent's `Toolbar`: `react-toolbar` reaches
+ *   `useArrowNavigationGroup` → `getMover` → `core.attrHandlers.set`, which throws against a
+ *   Dynamics form's tabster (8.2.0, no `attrHandlers`) and unmounts the React tree. For a row
+ *   of buttons the ARIA pattern is ~40 lines, so this is the cheap side of the split-by-cost
+ *   decision; `TabList` and `Tree` are the expensive side and the kit uses Fluent's.
+ *
+ * ★ Without a roving index a transcript of 20 messages × 4 hover actions is 80 tab stops.
+ */
+declare function useRovingTabindex(options: RovingTabindexOptions): RovingTabindex;
+
+interface StickyScroll {
+    /** Put on the scrolling element. */
+    onScroll: () => void;
+    /** Call to jump to the bottom regardless (e.g. a "jump to latest" button). */
+    scrollToBottom: () => void;
+    /** False once the reader scrolls up — drives a "jump to latest" affordance. */
+    isPinned: boolean;
+}
+/**
+ * Keep a transcript pinned to the bottom — but only while the reader is already there.
+ *
+ * ★★ THIS CARRIES A MEASURED DEFECT FORWARD. apps/form-builder's ChatPane once keyed its
+ *    scroll effect on the streaming message's CONTENT LENGTH, which queued a smooth
+ *    `scrollTo` per token — often 10+ per second — and jittered the viewport. Its fix was to
+ *    key on message COUNT and use `behavior: 'auto'`; both are reproduced here.
+ *
+ * ★★ AND IT ADDS THE HALF THAT WAS STILL MISSING. Sticking unconditionally means a reader who
+ *    scrolls up to re-read something mid-stream is yanked back to the bottom on the next
+ *    append. `wasPinnedRef` is sampled from SCROLL EVENTS, so it reflects where the reader
+ *    was before the append, not after.
+ *
+ * ★ `behavior: 'auto'`, never `'smooth'`: a queued smooth scroll is what produced the
+ *   jitter, and an involuntary animation is a WCAG 2.2.2 hazard besides.
+ */
+declare function useStickyScroll(ref: React$1.RefObject<HTMLElement>, messageCount: number): StickyScroll;
+
+interface UseConversationOptions {
+    service: IAgentService;
+    seed?: readonly AgentMessage[];
+    grounding?: Record<string, unknown>;
+    conversationId?: string;
+    /** Ids are injected so tests and Storybook are deterministic. */
+    createId?: () => string;
+}
+interface Conversation {
+    state: ConversationState;
+    announcement: Announcement;
+    busy: boolean;
+    send: (text: string, attachments?: AgentAttachment[]) => Promise<void>;
+    cancel: () => void;
+}
+/**
+ * Drive an `IAgentService` into a `ConversationState`.
+ *
+ * ★ The reducer and the announcement rule are both PURE and live in ./core — this hook only
+ *   owns the effectful parts: the abort controller, the iteration, and holding the previous
+ *   state so a transition can be detected. That split is what lets the interesting rules be
+ *   tested without a DOM.
+ *
+ * ★ `send()` NEVER throws. A transport that throws mid-stream (which an AsyncIterable can do,
+ *   and a Promise-shaped seam cannot) is converted into terminal state, because the
+ *   alternative is an unmounted tree — the React-layer analogue of the tabster crash.
+ */
+declare function useConversation(options: UseConversationOptions): Conversation;
+
+export { ActionCard, type ActionCardProps, ActionResult, type ActionResultProps, AgentAppShell, type AgentAppShellProps, AgentAttachment, AgentAvailability, AgentAvatar, type AgentAvatarProps, AgentCitation, type AgentDescriptor, AgentFailure, AgentMessage, AgentOpsPanel, type AgentOpsPanelProps, AgentParticipant, AgentPicker, type AgentPickerProps, type AgentRunRecord, AgentRunStatus, AgentSource, AgentStatusBadge, type AgentStatusBadgeProps, AgentToolCall, AgentUsage, Announcement, AnswerWithCitations, type AnswerWithCitationsProps, AppRail, type AppRailProps, ApprovalCard, type ApprovalCardProps, AvailabilityBanner, type AvailabilityBannerProps, CitationChip, type CitationChipProps, CitationList, type CitationListProps, Composer, type ComposerProps, ConfirmInline, type ConfirmInlineProps, type Conversation, ConversationHeader, type ConversationHeaderProps, ConversationList, ConversationListItem, type ConversationListItemProps, type ConversationListProps, ConversationState, type ConversationSummary, type ConversationTab, DayDivider, DayDividerLabel, type DayDividerProps, EmptyConversation, type EmptyConversationProps, GlobalSearchBar, type GlobalSearchBarProps, GroundingPanel, type GroundingPanelProps, type HeaderAction, IAgentService, LiveAnnouncer, type LiveAnnouncerProps, MessageActions, type MessageActionsProps, MessageBubble, type MessageBubbleProps, MessageList, type MessageListProps, ModelBadge, type ModelBadgeProps, ParameterReview, type ParameterReviewProps, type PresenceState, ProviderAttribution, type ProviderAttributionProps, type RailItem, RightPane, type RightPaneProps, type RovingTabindex, type RovingTabindexOptions, RunHistoryPanel, type RunHistoryPanelProps, RunTimeline, type RunTimelineProps, SourceCard, type SourceCardProps, type StickyScroll, StreamingText, type StreamingTextProps, SuggestedPrompts, type SuggestedPromptsProps, SystemNotice, type SystemNoticeProps, ThrottleNotice, type ThrottleNoticeProps, ToolCallCard, type ToolCallCardProps, TypingIndicator, type TypingIndicatorProps, UsageMeter, type UsageMeterProps, type UseConversationOptions, conversationAccessibleName, formatDayLabel, messageAttribution, runStatusLabel, useConversation, useFocusRestore, useRovingTabindex, useStickyScroll, useVisuallyHiddenStyles };