@openhex-ai/agent-sdk 0.0.1 → 0.1.0

package/dist/react/index.d.ts

@@ -0,0 +1,277 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { O as OpenhexClient, c as AgentChatClient, C as ChatStreamRecord } from '../client-1lMkhPMb.js';
+import '../tools-DWFaPtFE.js';
+import 'zod';
+
+/**
+ * Public types for the React chat layer (`@openhex-ai/agent-sdk/react`).
+ *
+ * These describe the props of {@link useOpenhexChat}, {@link ChatBox} and
+ * {@link ChatWidget}. They deliberately stay framework-thin: a message is a
+ * flat, render-ready shape, and the connection options map straight onto the
+ * underlying {@link AgentChatClient}.
+ */
+
+/** Role of a rendered chat bubble. */
+type ChatRole = 'user' | 'assistant' | 'system';
+/** A tool call the agent made during a turn (surfaced for optional display). */
+interface ChatToolCall {
+    id?: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/**
+ * A single, render-ready chat message. This is the flattened view the hook
+ * maintains — the raw stream records are aggregated into `text` so the UI
+ * never has to reach into `record.raw`.
+ */
+interface ChatMessage {
+    /** Stable client-side id (used as the React key). */
+    id: string;
+    role: ChatRole;
+    /** Aggregated text of the message so far. */
+    text: string;
+    /** Epoch millis when the bubble was created. */
+    createdAt: number;
+    /** True while the assistant reply is still streaming in. */
+    streaming?: boolean;
+    /** True for an assistant bubble that has been sent but has no text yet. */
+    pending?: boolean;
+    /** True when the turn failed (network / server / idle timeout). */
+    error?: boolean;
+    /** Tool calls observed during the turn, if any. */
+    toolCalls?: ChatToolCall[];
+}
+/** Connection status of the underlying stream. */
+type ChatStatus = 'idle' | 'connecting' | 'streaming' | 'error';
+/**
+ * How the hook reaches the platform. Provide EITHER a ready-made `client`
+ * (full control, e.g. an `OpenhexClient` from your own backend proxy), OR
+ * inline connection fields.
+ *
+ * Browser-safe auth: never ship a `mysta_…` API key to the browser. Mint a
+ * short-lived member **session token** on your backend
+ * (`client.workspaces.mintSession(...)`) and hand it to the widget via
+ * `token` (static) or `getToken` (refreshable — called before every request,
+ * so it can silently rotate an expiring token).
+ */
+interface OpenhexChatConnection {
+    /**
+     * A pre-built client. When set, all other connection fields are ignored.
+     * Accepts an {@link OpenhexClient} or a bare {@link AgentChatClient}.
+     */
+    client?: OpenhexClient | AgentChatClient;
+    /** Platform API base URL. Defaults to the SDK's production default. */
+    baseUrl?: string;
+    /** Static bearer token (member session JWT). Use `getToken` to refresh. */
+    token?: string;
+    /**
+     * Returns a fresh bearer token before each request. Preferred in the
+     * browser: lets you refresh an expiring session without re-mounting.
+     */
+    getToken?: () => string | Promise<string>;
+    /** `X-Login-Type` header (matches the web/app clients). */
+    loginType?: string;
+    /** Service-account id to impersonate via `X-Act-As` (caller must own it). */
+    actAs?: string;
+    /** Override the global fetch (testing / custom runtimes). */
+    fetch?: typeof fetch;
+}
+/** Options for {@link useOpenhexChat}. */
+interface UseOpenhexChatOptions extends OpenhexChatConnection {
+    /**
+     * Agent to route NEW conversations to. Required unless `conversationId`
+     * (resume) is given or the supplied `client` already has a default agent.
+     */
+    agentId?: string;
+    /** Resume an existing conversation instead of creating one. */
+    conversationId?: string;
+    /** Display name to label the user in the conversation log. */
+    senderName?: string;
+    /** Avatar URL stored alongside the user's messages. */
+    senderAvatar?: string;
+    /**
+     * Load prior history when `conversationId` is provided (default true).
+     * Ignored for brand-new conversations.
+     */
+    loadHistory?: boolean;
+    /** Abort a turn if no event arrives for this long (ms). Default 180_000. */
+    idleTimeoutMs?: number;
+    /** Called when a turn ends (success). Receives the finished assistant message. */
+    onTurnComplete?: (message: ChatMessage) => void;
+    /** Called on any turn error (network / server / idle timeout). */
+    onError?: (error: Error) => void;
+}
+/** Return value of {@link useOpenhexChat}. */
+interface UseOpenhexChatResult {
+    /** The conversation so far, oldest first. */
+    messages: ChatMessage[];
+    /** Coarse connection status. */
+    status: ChatStatus;
+    /** The last error, cleared on the next successful send. */
+    error: Error | null;
+    /** The conversation id, once the first message has been sent. */
+    conversationId: string | undefined;
+    /** True while an agent turn is in flight. */
+    isResponding: boolean;
+    /** Send a user message and stream the reply into `messages`. */
+    send: (text: string) => Promise<void>;
+    /** Interrupt the in-flight turn (server-side + stops streaming). */
+    interrupt: () => void;
+    /** Resend the last user message after an error. */
+    retry: () => void;
+    /** Clear all messages and forget the conversation id. */
+    clear: () => void;
+}
+/** Color theme for the chat components. `auto` follows `prefers-color-scheme`. */
+type ChatTheme = 'light' | 'dark' | 'auto';
+/** Presentation props shared by {@link ChatBox} and {@link ChatWidget}. */
+interface ChatBoxProps extends UseOpenhexChatOptions {
+    /** Header title (agent name). Omit the header entirely with `header={false}`. */
+    title?: string;
+    /** Header subtitle / status line. */
+    subtitle?: string;
+    /** Composer placeholder text. */
+    placeholder?: string;
+    /** First assistant bubble shown before any turn (display-only, not sent). */
+    greeting?: string;
+    /** Avatar URL shown in the header and next to the agent. */
+    avatarUrl?: string;
+    /** Color theme. Default `light`. */
+    theme?: ChatTheme;
+    /** Accent color (buttons, user bubbles, links). Any CSS color. */
+    accentColor?: string;
+    /** Explicit height (number → px). Defaults to filling the parent. */
+    height?: number | string;
+    /** Explicit width (number → px). */
+    width?: number | string;
+    /** Extra class on the root element. */
+    className?: string;
+    /** Replace the header node, or hide it with `false`. */
+    header?: ReactNode | false;
+    /** Node shown when there are no messages (overrides `greeting`). */
+    emptyState?: ReactNode;
+    /** Small print under the composer. Set `false` to hide. */
+    footer?: ReactNode | false;
+    /** Disable input (read-only view). */
+    disabled?: boolean;
+    /** Inject the bundled stylesheet (default true). Set false to self-style. */
+    injectStyles?: boolean;
+    /** Show the tool calls the agent made under each reply (default false). */
+    showToolCalls?: boolean;
+}
+/** Props for the floating {@link ChatWidget}. */
+interface ChatWidgetProps extends ChatBoxProps {
+    /** Corner to anchor the launcher + panel. Default `bottom-right`. */
+    position?: 'bottom-right' | 'bottom-left';
+    /** Replace the launcher button's icon. */
+    launcherIcon?: ReactNode;
+    /** Accessible label for the launcher button. Default "Open chat". */
+    launcherLabel?: string;
+    /** Start open (uncontrolled). Default false. */
+    defaultOpen?: boolean;
+    /** Controlled open state. Pair with {@link onOpenChange}. */
+    open?: boolean;
+    /** Called when the open state should change (controlled or uncontrolled). */
+    onOpenChange?: (open: boolean) => void;
+}
+
+declare function ChatWidget(props: ChatWidgetProps): react_jsx_runtime.JSX.Element;
+
+declare function ChatBox(props: ChatBoxProps): react_jsx_runtime.JSX.Element;
+
+declare function useOpenhexChat(options: UseOpenhexChatOptions): UseOpenhexChatResult;
+
+/** Render a message body as a lightweight, safe Markdown subset. */
+declare function Markdown({ text }: {
+    text: string;
+}): react_jsx_runtime.JSX.Element;
+
+/** Fold records (oldest first) into chat bubbles, dropping empty ones. */
+declare function foldRecords(records: ChatStreamRecord[], idPrefix?: string): ChatMessage[];
+
+/**
+ * Browser-safe client resolution for the React chat layer.
+ *
+ * Turns the loose {@link OpenhexChatConnection} props into a concrete
+ * {@link AgentChatClient}. The important bit is `getToken`: rather than
+ * baking a token into the client at construction (the core `HttpClient`
+ * reads `apiKey` once), we wrap `fetch` so a fresh token is injected on the
+ * `Authorization` header of every request. That lets a browser widget rotate
+ * an expiring member-session JWT without re-mounting.
+ */
+
+/**
+ * Resolve the {@link OpenhexChatConnection} props into an
+ * {@link AgentChatClient}. Throws if neither a client nor any credential is
+ * provided.
+ */
+declare function resolveChatClient(conn: OpenhexChatConnection): AgentChatClient;
+
+/**
+ * A tiny, dependency-free, XSS-safe Markdown subset for chat bubbles.
+ *
+ * We deliberately do NOT pull in `react-markdown` & friends (the internal
+ * webapp does) — an embeddable widget must stay light and safe. This parses a
+ * useful subset into a plain data tree; the renderer maps it to React
+ * elements, so every piece of text goes through React's escaping and no HTML
+ * is ever injected. Link hrefs are sanitized to http/https/mailto.
+ *
+ * Supported: fenced code blocks, paragraphs, `inline code`, **bold**,
+ * *italic* / _italic_, [links](url), and bare URL autolinking.
+ */
+/** An inline span inside a paragraph. */
+type Span = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'code';
+    text: string;
+} | {
+    type: 'bold';
+    text: string;
+} | {
+    type: 'italic';
+    text: string;
+} | {
+    type: 'link';
+    text: string;
+    href: string;
+};
+/** A block-level node. */
+type Block = {
+    type: 'code';
+    text: string;
+    lang?: string;
+} | {
+    type: 'heading';
+    level: number;
+    spans: Span[];
+} | {
+    type: 'paragraph';
+    spans: Span[];
+} | {
+    type: 'list';
+    ordered: boolean;
+    start: number;
+    items: Span[][];
+} | {
+    type: 'blockquote';
+    spans: Span[];
+} | {
+    type: 'hr';
+};
+/** Only allow safe URL schemes; everything else becomes plain text. */
+declare function sanitizeHref(href: string): string | null;
+/** Parse a single line/segment of text into inline spans. */
+declare function parseInline(input: string): Span[];
+/** Parse a whole message into block-level nodes. */
+declare function parseMarkdown(input: string): Block[];
+
+declare const STYLE_ELEMENT_ID = "ohx-chat-styles";
+declare const CHAT_CSS = "\n.ohx-root {\n  --ohx-accent: #4f46e5;\n  --ohx-accent-contrast: #ffffff;\n  --ohx-bg: #ffffff;\n  --ohx-surface: #f7f7f8;\n  --ohx-fg: #1f2328;\n  --ohx-muted: #6b7280;\n  --ohx-border: #e5e7eb;\n  --ohx-user-bg: var(--ohx-accent);\n  --ohx-user-fg: var(--ohx-accent-contrast);\n  --ohx-assistant-bg: #f1f2f4;\n  --ohx-assistant-fg: #1f2328;\n  --ohx-radius: 16px;\n  --ohx-font: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, \"PingFang SC\", \"Microsoft YaHei\", sans-serif;\n  display: flex;\n  flex-direction: column;\n  box-sizing: border-box;\n  background: var(--ohx-bg);\n  color: var(--ohx-fg);\n  font-family: var(--ohx-font);\n  font-size: 14px;\n  line-height: 1.5;\n  border: 1px solid var(--ohx-border);\n  border-radius: var(--ohx-radius);\n  overflow: hidden;\n  min-height: 0;\n}\n.ohx-root[data-theme=\"dark\"] {\n  --ohx-bg: #1b1c1f;\n  --ohx-surface: #242629;\n  --ohx-fg: #e8eaed;\n  --ohx-muted: #9aa0a6;\n  --ohx-border: #34363b;\n  --ohx-assistant-bg: #2a2c30;\n  --ohx-assistant-fg: #e8eaed;\n}\n.ohx-root *, .ohx-root *::before, .ohx-root *::after { box-sizing: border-box; }\n\n.ohx-header {\n  display: flex;\n  align-items: center;\n  gap: 10px;\n  padding: 12px 14px;\n  border-bottom: 1px solid var(--ohx-border);\n  background: var(--ohx-bg);\n  flex: none;\n}\n.ohx-avatar {\n  width: 34px; height: 34px; border-radius: 50%;\n  object-fit: cover; flex: none;\n  background: var(--ohx-surface);\n}\n.ohx-header-text { display: flex; flex-direction: column; min-width: 0; flex: 1; }\n.ohx-title { font-weight: 600; font-size: 14px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.ohx-subtitle { font-size: 12px; color: var(--ohx-muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.ohx-icon-btn {\n  display: inline-flex; align-items: center; justify-content: center;\n  width: 30px; height: 30px; border: none; border-radius: 8px;\n  background: transparent; color: var(--ohx-muted); cursor: pointer;\n}\n.ohx-icon-btn:hover { background: var(--ohx-surface); color: var(--ohx-fg); }\n\n.ohx-messages {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow-y: auto;\n  padding: 16px;\n  display: flex;\n  flex-direction: column;\n  gap: 10px;\n  background: var(--ohx-bg);\n  scroll-behavior: smooth;\n}\n.ohx-empty {\n  margin: auto; text-align: center; color: var(--ohx-muted);\n  font-size: 13px; padding: 24px; max-width: 80%;\n}\n\n.ohx-row { display: flex; width: 100%; }\n.ohx-row.user { justify-content: flex-end; }\n.ohx-row.assistant, .ohx-row.system { justify-content: flex-start; }\n.ohx-bubble {\n  max-width: 82%;\n  padding: 9px 13px;\n  border-radius: 14px;\n  word-break: break-word;\n  overflow-wrap: anywhere;\n}\n.ohx-row.user .ohx-bubble {\n  background: var(--ohx-user-bg); color: var(--ohx-user-fg);\n  border-bottom-right-radius: 4px;\n}\n.ohx-row.assistant .ohx-bubble {\n  background: var(--ohx-assistant-bg); color: var(--ohx-assistant-fg);\n  border-bottom-left-radius: 4px;\n}\n.ohx-bubble.error { border: 1px solid #ef4444; }\n.ohx-bubble .ohx-p { margin: 0 0 6px; }\n.ohx-bubble .ohx-p:last-child { margin-bottom: 0; }\n.ohx-bubble a { color: inherit; text-decoration: underline; }\n.ohx-row.assistant .ohx-bubble a { color: var(--ohx-accent); }\n.ohx-bubble > :first-child { margin-top: 0; }\n.ohx-bubble > :last-child { margin-bottom: 0; }\n.ohx-bubble .ohx-h { font-weight: 600; line-height: 1.3; margin: 12px 0 6px; }\n.ohx-bubble .ohx-h1 { font-size: 1.3em; }\n.ohx-bubble .ohx-h2 { font-size: 1.18em; }\n.ohx-bubble .ohx-h3 { font-size: 1.08em; }\n.ohx-bubble .ohx-h4, .ohx-bubble .ohx-h5, .ohx-bubble .ohx-h6 { font-size: 1em; }\n.ohx-bubble .ohx-ul, .ohx-bubble .ohx-ol { margin: 6px 0; padding-left: 1.35em; }\n.ohx-bubble .ohx-ul { list-style: disc; }\n.ohx-bubble .ohx-ol { list-style: decimal; }\n.ohx-bubble .ohx-ul li, .ohx-bubble .ohx-ol li { margin: 3px 0; }\n.ohx-bubble .ohx-ul li::marker, .ohx-bubble .ohx-ol li::marker { color: var(--ohx-muted); }\n.ohx-bubble .ohx-hr { border: none; border-top: 1px solid var(--ohx-border); margin: 12px 0; }\n.ohx-bubble .ohx-quote {\n  margin: 6px 0; padding: 2px 0 2px 12px;\n  border-left: 3px solid var(--ohx-border); color: var(--ohx-muted);\n}\n.ohx-code {\n  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;\n  font-size: 0.9em; background: rgba(127,127,127,0.16);\n  padding: 1px 5px; border-radius: 5px;\n}\n.ohx-pre {\n  margin: 6px 0; padding: 10px 12px; border-radius: 10px;\n  background: rgba(127,127,127,0.14); overflow-x: auto;\n}\n.ohx-pre code {\n  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;\n  font-size: 0.86em; white-space: pre; background: none; padding: 0;\n}\n.ohx-tools { margin-top: 6px; display: flex; flex-wrap: wrap; gap: 4px; }\n.ohx-tool {\n  font-size: 11px; color: var(--ohx-muted);\n  background: rgba(127,127,127,0.12); border-radius: 6px; padding: 2px 7px;\n  font-family: ui-monospace, monospace;\n}\n\n.ohx-typing { display: inline-flex; gap: 4px; padding: 3px 2px; align-items: center; }\n.ohx-typing span {\n  width: 6px; height: 6px; border-radius: 50%;\n  background: var(--ohx-muted); opacity: 0.5;\n  animation: ohx-blink 1.2s infinite ease-in-out both;\n}\n.ohx-typing span:nth-child(2) { animation-delay: 0.18s; }\n.ohx-typing span:nth-child(3) { animation-delay: 0.36s; }\n@keyframes ohx-blink { 0%, 80%, 100% { transform: scale(0.7); opacity: 0.3; } 40% { transform: scale(1); opacity: 0.9; } }\n\n.ohx-error-bar {\n  display: flex; align-items: center; justify-content: space-between; gap: 8px;\n  margin: 0 16px 8px; padding: 8px 12px; font-size: 12px;\n  color: #b91c1c; background: rgba(239,68,68,0.1);\n  border: 1px solid rgba(239,68,68,0.3); border-radius: 8px;\n}\n.ohx-root[data-theme=\"dark\"] .ohx-error-bar { color: #fca5a5; }\n.ohx-retry {\n  border: none; background: transparent; color: inherit; cursor: pointer;\n  text-decoration: underline; font-weight: 600; font-size: 12px; white-space: nowrap;\n}\n\n.ohx-composer {\n  display: flex; align-items: flex-end; gap: 8px;\n  padding: 10px 12px; border-top: 1px solid var(--ohx-border);\n  background: var(--ohx-bg); flex: none;\n}\n.ohx-textarea {\n  flex: 1; resize: none; border: 1px solid var(--ohx-border);\n  border-radius: 12px; padding: 9px 12px; max-height: 140px;\n  font-family: inherit; font-size: 14px; line-height: 1.4;\n  color: var(--ohx-fg); background: var(--ohx-surface); outline: none;\n}\n.ohx-textarea:focus { border-color: var(--ohx-accent); }\n.ohx-textarea::placeholder { color: var(--ohx-muted); }\n.ohx-send {\n  display: inline-flex; align-items: center; justify-content: center;\n  width: 38px; height: 38px; flex: none; border: none; border-radius: 12px;\n  background: var(--ohx-accent); color: var(--ohx-accent-contrast); cursor: pointer;\n  transition: opacity 0.15s;\n}\n.ohx-send:disabled { opacity: 0.45; cursor: not-allowed; }\n.ohx-send.stop { background: var(--ohx-surface); color: var(--ohx-fg); border: 1px solid var(--ohx-border); }\n.ohx-footer {\n  text-align: center; font-size: 10px; color: var(--ohx-muted);\n  padding: 0 0 8px; background: var(--ohx-bg); flex: none;\n}\n.ohx-footer a { color: var(--ohx-muted); }\n\n/* ---- Floating widget ---- */\n.ohx-launcher {\n  position: fixed; z-index: 2147483000;\n  width: 56px; height: 56px; border-radius: 50%; border: none;\n  background: var(--ohx-accent, #4f46e5); color: #fff; cursor: pointer;\n  box-shadow: 0 6px 24px rgba(0,0,0,0.22);\n  display: inline-flex; align-items: center; justify-content: center;\n  transition: transform 0.15s;\n}\n.ohx-launcher:hover { transform: scale(1.06); }\n.ohx-launcher.bottom-right { right: 20px; bottom: 20px; }\n.ohx-launcher.bottom-left { left: 20px; bottom: 20px; }\n.ohx-panel {\n  position: fixed; z-index: 2147483000;\n  width: 380px; height: min(620px, calc(100vh - 110px));\n  box-shadow: 0 12px 40px rgba(0,0,0,0.24);\n  border-radius: 18px;\n  overflow: hidden;\n  animation: ohx-pop 0.16s ease-out;\n}\n.ohx-panel.bottom-right { right: 20px; bottom: 88px; }\n.ohx-panel.bottom-left { left: 20px; bottom: 88px; }\n/* Inside a panel the wrapper owns the shape + shadow, so the ChatBox fills\n   it squared (no double border / radius). */\n.ohx-root.ohx-panel-inner { border: none; border-radius: 0; height: 100%; width: 100%; }\n@keyframes ohx-pop { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: translateY(0); } }\n\n@media (max-width: 480px) {\n  .ohx-panel {\n    right: 0; left: 0; bottom: 0; top: 0;\n    width: 100vw; height: 100vh; height: 100dvh;\n    border-radius: 0;\n  }\n  .ohx-launcher.open-hidden { display: none; }\n}\n";
+/** Inject the stylesheet once (idempotent). Pass `enabled=false` to skip. */
+declare function useInjectStyles(enabled: boolean): void;
+
+export { type Block, CHAT_CSS, ChatBox, type ChatBoxProps, type ChatMessage, type ChatRole, type ChatStatus, type ChatTheme, type ChatToolCall, ChatWidget, type ChatWidgetProps, Markdown, type OpenhexChatConnection, STYLE_ELEMENT_ID, type Span, type UseOpenhexChatOptions, type UseOpenhexChatResult, foldRecords, parseInline, parseMarkdown, resolveChatClient, sanitizeHref, useInjectStyles, useOpenhexChat };