@mast-ai/react-ui 0.1.0

package/dist/context.d.ts

@@ -0,0 +1,113 @@
+import type { ReactNode } from 'react';
+import { AgentRunner } from '@mast-ai/core';
+import type { AgentConfig, Message } from '@mast-ai/core';
+import { type OnApprovalRequired, type PendingApproval } from './approval';
+import type { ConversationEntry, IconMap } from './types';
+/**
+ * Props accepted by {@link AgentProvider}.
+ */
+export interface AgentProviderProps {
+    /** The {@link AgentRunner} that will execute agent runs. */
+    runner: AgentRunner;
+    /** The agent configuration used for every turn. */
+    agent: AgentConfig;
+    /** The subtree that should have access to {@link useAgent}. */
+    children: ReactNode;
+    /**
+     * Optional overrides for the bundled inline SVG icons. Any keys left
+     * unspecified fall back to the defaults exported from `./icons`. Distributed
+     * to descendants through a dedicated icon context so updates do not flow
+     * through the agent state context.
+     */
+    icons?: IconMap;
+    /**
+     * Called before executing any tool call whose effective `needsApproval`
+     * evaluates to `true`. Resolve with `true` to proceed, `false` to cancel
+     * (the runner receives a synthetic "user cancelled" result), a string to
+     * short-circuit execution with that string as the tool result, or
+     * {@link import('./approval').INLINE_APPROVAL} to defer to the inline
+     * approval queue exposed via `useAgent().pendingApprovals`.
+     *
+     * Not called when no tool requires approval, and not called when the prop
+     * is omitted — in which case `requiresApproval: true` tools execute silently.
+     */
+    onApprovalRequired?: OnApprovalRequired;
+    /**
+     * Runtime override of the per-tool approval policy. Bare names add approval
+     * even when the tool's own `requiresApproval` is `false`; names prefixed with
+     * `!` suppress approval even when `requiresApproval` is `true`.
+     *
+     * @example ['third_party_tool', '!safe_tool']
+     */
+    approvalOverride?: string[];
+    /**
+     * Seed `Conversation.history` with previously-saved messages so the LLM
+     * continues from where it left off. Read once when the provider mounts;
+     * later changes have no effect until `reset()` is called.
+     */
+    initialHistory?: Message[];
+    /**
+     * Seed the rendered entry list with previously-saved entries so existing
+     * turns render immediately on mount. Read once when the provider mounts.
+     */
+    initialEntries?: ConversationEntry[];
+    /**
+     * Called after each completed turn (i.e. after a `done` event) with the
+     * latest core message history and UI entry list. Use this to persist the
+     * conversation to localStorage, IndexedDB, a server, etc. Not invoked when
+     * a run is cancelled or errors before completion.
+     */
+    onConversationChange?: (history: Message[], entries: ConversationEntry[]) => void;
+}
+/**
+ * The value exposed by {@link useAgent}.
+ */
+export interface UseAgentReturn {
+    /** Ordered conversation entries, suitable for rendering. */
+    messages: ConversationEntry[];
+    /**
+     * Live mirror of the underlying `Conversation.history` — the raw core
+     * `Message[]` sent to the LLM. Updated after every completed turn. Read
+     * this to imperatively persist conversation state.
+     */
+    history: Message[];
+    /**
+     * Sends a user message and starts a new agent run. The first argument is
+     * the prompt delivered to the LLM. The optional second argument overrides
+     * what is rendered in the user bubble; when omitted, the prompt is shown.
+     */
+    sendMessage: (text: string, displayText?: string) => void;
+    /** Aborts the current run, if any. */
+    cancel: () => void;
+    /** `true` while a run is in progress. */
+    isRunning: boolean;
+    /**
+     * Aborts any in-flight run, clears the rendered conversation, and replaces
+     * the underlying {@link Conversation} with a fresh instance so the next
+     * `sendMessage` call starts with empty core history.
+     */
+    reset: () => void;
+    /**
+     * Tool calls awaiting an inline approval decision. Populated when
+     * `onApprovalRequired` resolves to `INLINE_APPROVAL` for a call. Each entry
+     * carries `approve()`, `reject()`, and `respondWith()` callbacks that
+     * resolve the underlying tool execution; the runner is paused until one is
+     * called.
+     */
+    pendingApprovals: PendingApproval[];
+}
+/**
+ * Wraps a subtree with agent context.
+ *
+ * Internally creates a {@link Conversation} via `runner.conversation(agent)`
+ * and drives it with {@link useAgentStream}. Children access the resulting
+ * state through {@link useAgent}.
+ */
+export declare function AgentProvider({ runner, agent, children, icons, onApprovalRequired, approvalOverride, initialHistory, initialEntries, onConversationChange, }: AgentProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Reads the current agent state from {@link AgentProvider}.
+ *
+ * Throws when called outside an `<AgentProvider>` so misuse is caught at the
+ * call site rather than producing silent runtime bugs.
+ */
+export declare function useAgent(): UseAgentReturn;

package/dist/hooks/useAgentStream.d.ts

@@ -0,0 +1,131 @@
+import type { Conversation, Message } from '@mast-ai/core';
+import type { ConversationEntry, ToolCallStatus } from '../types';
+/**
+ * Options accepted by {@link useAgentStream}.
+ */
+export interface UseAgentStreamOptions {
+    /**
+     * Initial UI entry list. Used to restore a previously-saved conversation
+     * so existing turns render immediately on mount. Read once when the hook
+     * first initialises; changes to this prop after mount are ignored.
+     */
+    initialEntries?: ConversationEntry[];
+    /**
+     * Called after a turn ends with the `done` event, with the freshly
+     * committed `entries` and `history`. Not called when a run is cancelled
+     * or errors before `done` is received.
+     */
+    onTurnComplete?: (entries: ConversationEntry[], history: Message[]) => void;
+}
+/**
+ * The value returned by {@link useAgentStream}.
+ */
+export interface UseAgentStreamReturn {
+    /**
+     * Ordered list of conversation entries built from the `AgentEvent` stream.
+     * Each `sendMessage` call appends one user entry and one assistant entry.
+     * Entries are updated in-place as events stream in; their `id` values are
+     * stable across renders.
+     */
+    entries: ConversationEntry[];
+    /**
+     * Live mirror of the underlying `Conversation.history`. Initialised from
+     * `conversation.history` and updated to `event.history` whenever a `done`
+     * event is observed. Use this to imperatively persist conversation state.
+     */
+    history: Message[];
+    /**
+     * `true` while the agent is generating a response; `false` otherwise.
+     * Reflects the overall run state rather than the individual entry's streaming
+     * flag, which may differ briefly at the boundaries of a run.
+     */
+    isRunning: boolean;
+    /**
+     * Sends a user message and starts a new agent run.
+     *
+     * Appends a user `ConversationEntry` and an empty streaming assistant
+     * `ConversationEntry`, then consumes the `AgentEvent` stream emitted by
+     * `conversation.runStream`. Calling `sendMessage` while a run is already in
+     * progress is a no-op (the caller should disable the input while `isRunning`
+     * is true).
+     *
+     * @param text - The prompt sent to the LLM via `Conversation.runStream`.
+     * @param displayText - Optional override for the text rendered in the user
+     *   bubble. When provided, the user `ConversationEntry.text` is set to this
+     *   value while `text` is still passed unchanged to the runner. An empty
+     *   string is treated as a deliberate override (it does not fall back to
+     *   `text`).
+     */
+    sendMessage: (text: string, displayText?: string) => void;
+    /**
+     * Aborts the current run.
+     *
+     * Signals the underlying `AbortController`, which causes the agent loop to
+     * stop and sets the last assistant entry's `isStreaming` flag to `false`.
+     * Has no effect when `isRunning` is false.
+     */
+    cancel: () => void;
+    /**
+     * Aborts any in-flight run and clears all conversation entries.
+     *
+     * Note that this only resets the UI rendering state owned by this hook. It
+     * does not clear the underlying `Conversation.history`; callers wanting to
+     * start a fresh conversation should also replace the `Conversation` instance.
+     */
+    reset: () => void;
+    /**
+     * Sets the `awaitingApproval` flag on the first matching streaming
+     * `ToolEventEntry` (by `name`) within the most recent assistant entry.
+     *
+     * Used by the approval proxy in `AgentProvider` to surface "awaiting human
+     * decision" as a first-class state on the entry, so renderers can show a
+     * pause indicator without correlating tool calls themselves.
+     */
+    setToolAwaitingApproval: (name: string, awaiting: boolean) => void;
+    /**
+     * Sets the `status` field on the first matching streaming `ToolEventEntry`
+     * (by `name`). Used by the approval proxy to mark a call as `'cancelled'`
+     * before the runner emits `tool_call_completed` so the eventual completion
+     * event preserves the cancellation rather than defaulting to `'success'`.
+     */
+    setToolStatus: (name: string, status: ToolCallStatus) => void;
+}
+/**
+ * Internal hook that drives the streaming state machine for a single
+ * `Conversation` instance.
+ *
+ * Subscribes to `AgentEvent`s emitted by `conversation.runStream` and
+ * maintains a `ConversationEntry[]` that reflects the current rendered state
+ * of the conversation. Sub-agent events are captured via `onToolEvent` and
+ * routed to the matching `ToolEventEntry` by tool name.
+ *
+ * This hook is consumed by `<AgentProvider>` and is not part of the public API.
+ * It is exported so that it can be used independently in advanced scenarios.
+ *
+ * ### State machine summary
+ *
+ * | Event | Action |
+ * |-------|--------|
+ * | `sendMessage(text)` | Append user entry; append assistant entry with `isStreaming: true` |
+ * | `text_delta` | Append delta to last assistant entry's `text` |
+ * | `thinking` | Append delta to last assistant entry's `thinking` |
+ * | `tool_call_started` | Push new `ToolEventEntry` with `isStreaming: true` |
+ * | `onToolEvent` → `thinking` | Append delta to matching `ToolEventEntry.subThinking` |
+ * | `onToolEvent` → `text_delta` | Append delta to matching `ToolEventEntry.subText` |
+ * | `onToolEvent` → `tool_call_started` | Push new nested `ToolEventEntry` onto parent's `nestedToolEvents` |
+ * | `onToolEvent` → `tool_call_completed` | Set `result` and `isStreaming: false` on matching nested entry |
+ * | `onToolEvent` → `done` | Ignored |
+ * | `tool_call_completed` | Set `result` and `isStreaming: false` on matching entry |
+ * | `done` | Set `text = output` and `isStreaming: false` on assistant entry |
+ * | Error / cancel | Set `isStreaming: false` on last assistant entry |
+ *
+ * @param conversation - A `Conversation` instance obtained from
+ *   `AgentRunner.conversation(agentConfig)`.
+ *
+ * @example
+ * ```tsx
+ * const conversation = useMemo(() => runner.conversation(agentConfig), [runner, agentConfig]);
+ * const { entries, sendMessage, cancel, isRunning } = useAgentStream(conversation);
+ * ```
+ */
+export declare function useAgentStream(conversation: Conversation, options?: UseAgentStreamOptions): UseAgentStreamReturn;

package/dist/icons.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import type { IconMap } from './types';
+/**
+ * Bundled defaults for every icon slot. Every key is populated, so callers
+ * receive a `Required<IconMap>` from {@link useIcons}.
+ */
+export declare const defaultIcons: Required<IconMap>;
+/**
+ * Internal provider used by `<AgentProvider>` to merge consumer overrides on
+ * top of the bundled defaults before publishing the resulting map.
+ */
+export declare function IconProvider({ icons, children }: {
+    icons?: IconMap;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Internal hook used by components that render an icon slot. Always returns
+ * a fully populated map, falling back to the bundled defaults for any slot
+ * the consumer did not override.
+ */
+export declare function useIcons(): Required<IconMap>;

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export type { ConversationEntry, ToolEventEntry, ToolCallStatus, IconMap } from './types';
+export { useAgentStream } from './hooks/useAgentStream';
+export type { UseAgentStreamOptions, UseAgentStreamReturn } from './hooks/useAgentStream';
+export { AgentProvider, useAgent } from './context';
+export type { AgentProviderProps, UseAgentReturn } from './context';
+export { INLINE_APPROVAL } from './approval';
+export type { OnApprovalRequired, PendingApproval } from './approval';
+export { InlineApproval } from './components/InlineApproval';
+export type { InlineApprovalProps } from './components/InlineApproval';
+export { ThinkingBlock } from './components/ThinkingBlock';
+export type { ThinkingBlockProps } from './components/ThinkingBlock';
+export { ToolCallBlock } from './components/ToolCallBlock';
+export type { ToolCallBlockProps } from './components/ToolCallBlock';
+export { UserMessage } from './components/UserMessage';
+export type { UserMessageProps } from './components/UserMessage';
+export { AssistantMessage } from './components/AssistantMessage';
+export type { AssistantMessageProps } from './components/AssistantMessage';
+export { ChatInput } from './components/ChatInput';
+export type { ChatInputProps } from './components/ChatInput';
+export { MessageItem } from './components/MessageItem';
+export type { MessageItemProps } from './components/MessageItem';
+export { MessageList } from './components/MessageList';
+export type { MessageListProps } from './components/MessageList';
+export { ConversationPanel } from './components/ConversationPanel';
+export type { ConversationPanelProps } from './components/ConversationPanel';
+export { useMentions } from './mentions/useMentions';
+export type { UseMentionsReturn } from './mentions/useMentions';
+export { buildInlineMentionPrompt, extractMentionQuery, removeMentionTrigger, } from './mentions/utils';
+export type { MentionItem, MentionSegment, MentionsConfig } from './mentions/types';