npm - @cabbage0320/agent-plugin - Versions diffs - 1.0.0 → 1.0.1 - Mend

@cabbage0320/agent-plugin 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/dist/hooks/useSpeechRecognition.d.ts +12 -0
package/dist/index.d.ts +49 -0
package/dist/lib/utils.d.ts +8 -0
package/dist/widget/AskUserCard.d.ts +14 -0
package/dist/widget/ChatHeader.d.ts +5 -0
package/dist/widget/ChatInput.d.ts +18 -0
package/dist/widget/ConfirmCloseOverlay.d.ts +8 -0
package/dist/widget/Launcher.d.ts +7 -0
package/dist/widget/MessageItem.d.ts +30 -0
package/dist/widget/MessageList.d.ts +34 -0
package/dist/widget/ReasoningPanel.d.ts +10 -0
package/dist/widget/RetryOverlay.d.ts +7 -0
package/dist/widget/ToolCallBlock.d.ts +11 -0
package/dist/widget/TypingDots.d.ts +2 -0
package/dist/widget/constants.d.ts +22 -0
package/dist/widget/index.d.ts +7 -0
package/dist/widget/markdown.d.ts +13 -0
package/dist/widget/types.d.ts +65 -0
package/dist/widget/utils.d.ts +33 -0
package/package.json +3 -2

package/dist/hooks/useSpeechRecognition.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+export interface UseSpeechRecognitionOptions {
+    lang?: string;
+    onTranscript?: (text: string) => void;
+}
+export interface UseSpeechRecognitionReturn {
+    isSupported: boolean;
+    isListening: boolean;
+    start: (currentText: string) => void;
+    stop: () => void;
+    abortQuietly: () => void;
+}
+export declare function useSpeechRecognition({ lang, onTranscript, }?: UseSpeechRecognitionOptions): UseSpeechRecognitionReturn;

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,49 @@
+import type { AiChatWidgetProps } from "./widget";
+export interface ChatOptions {
+    /** Base URL of the server hosting the API (e.g. "https://api.example.com"). */
+    serverUrl: string;
+    /** Agent UUID to scope the conversation to. */
+    agentId: string;
+    /**
+     * Optional container selector or element. If omitted, a dedicated div is
+     * appended to <body>. The widget always renders inside a Shadow DOM rooted
+     * at this element, so host-page styles never affect it.
+     */
+    container?: string | HTMLElement;
+}
+/**
+ * Mount the AI chat widget onto the page. Safe to call multiple times — a
+ * second call will unmount the previous instance first.
+ *
+ * Returns a Promise that resolves once the widget is mounted. The Promise
+ * is also resolved (without mounting) if a subsequent `destroy()` cancels
+ * the pending mount.
+ *
+ * The widget is rendered inside a **Shadow DOM** so that:
+ * - Host-page CSS (resets, frameworks, etc.) cannot leak in.
+ * - Widget CSS cannot leak out.
+ * - No `<link>` tag is required — styles are inlined into the JS bundle.
+ *
+ * This function is SSR-safe to import: it only touches browser APIs when
+ * actually invoked (which should happen inside a `useEffect` or other
+ * client-only context).
+ *
+ * @example
+ * // Via script tag (UMD build) — no separate CSS needed:
+ * <script src="agent-plugin.umd.js"></script>
+ * <script>AgentPlugin.init({ serverUrl: "https://api.example.com", agentId: "abc-123" })</script>
+ *
+ * @example
+ * // Via ES module import (Next.js / React):
+ * import { init } from "agent-plugin";
+ * useEffect(() => { init({ serverUrl: "...", agentId: "..." }); }, []);
+ */
+export declare function init(options: ChatOptions): Promise<void>;
+/**
+ * Unmount the widget and remove the injected host element (including its
+ * shadow root). Useful for SPA route changes or when the widget is no longer
+ * needed. Also cancels any pending `init()` whose dynamic imports haven't
+ * resolved yet.
+ */
+export declare function destroy(): void;
+export type { AiChatWidgetProps };

package/dist/lib/utils.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+/**
+ * Simple class name combiner — joins truthy string values with spaces.
+ * No external dependencies (replaces the previous clsx + tailwind-merge combo,
+ * which is unnecessary now that the widget uses hand-written semantic CSS
+ * instead of Tailwind utility classes).
+ */
+export type ClassValue = string | false | null | undefined;
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/widget/AskUserCard.d.ts ADDED Viewed

@@ -0,0 +1,14 @@
+import type { AskUserInput, AskUserOutput } from "./types";
+export interface AskUserCardProps {
+    toolCallId: string;
+    state: string;
+    input?: AskUserInput;
+    output?: AskUserOutput;
+    errorText?: string;
+    interactive: boolean;
+    onSubmit: (toolCallId: string, output: AskUserOutput) => void;
+}
+/**
+ * Interactive card for the local `ask_user` tool.
+ */
+export declare function AskUserCard({ toolCallId, state, input, output, errorText, interactive, onSubmit, }: AskUserCardProps): import("react").JSX.Element;

package/dist/widget/ChatHeader.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+/** Top bar of the chat panel: title + new-conversation / close actions. */
+export declare function ChatHeader({ onNewConversation, onClose, }: {
+    onNewConversation: () => void;
+    onClose: () => void;
+}): import("react").JSX.Element;

package/dist/widget/ChatInput.d.ts ADDED Viewed

@@ -0,0 +1,18 @@
+/** A selectable skill shown in the @ mention picker. */
+export interface ChatInputSkill {
+    uuid: string;
+    name: string;
+    description: string | null;
+}
+/** Composer at the bottom of the chat panel. */
+export declare function ChatInput({ value, onChange, onSend, onStop, isBusy, skills, activeSkillIds, onAddSkill, onRemoveSkill, }: {
+    value: string;
+    onChange: (v: string) => void;
+    onSend: () => void;
+    onStop: () => void;
+    isBusy: boolean;
+    skills: ChatInputSkill[];
+    activeSkillIds: string[];
+    onAddSkill: (skill: ChatInputSkill) => void;
+    onRemoveSkill: (uuid: string) => void;
+}): import("react").JSX.Element;

package/dist/widget/ConfirmCloseOverlay.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+/** Modal asking what to do when closing while a reply is still streaming. */
+export declare function ConfirmCloseOverlay({ onBackgroundClose, onStopAndClose, onCancel, }: {
+    /** Keep the stream running in the background and close the panel. */
+    onBackgroundClose: () => void;
+    /** Stop the stream and close the panel. */
+    onStopAndClose: () => void;
+    onCancel: () => void;
+}): import("react").JSX.Element;

package/dist/widget/Launcher.d.ts ADDED Viewed

@@ -0,0 +1,7 @@
+/** Collapsed, edge-docked launcher button (with an optional first-visit hint). */
+export declare function Launcher({ onOpen, showHint, backgroundRunning, }: {
+    onOpen: () => void;
+    showHint: boolean;
+    /** Whether a background stream is still running after the panel was closed. */
+    backgroundRunning: boolean;
+}): import("react").JSX.Element;

package/dist/widget/MessageItem.d.ts ADDED Viewed

@@ -0,0 +1,30 @@
+import type { UIMessage } from "ai";
+import type { AskUserOutput } from "./types";
+export interface MessageItemProps {
+    message: UIMessage;
+    isLast: boolean;
+    isBusy: boolean;
+    copied: boolean;
+    onCopy: (message: UIMessage) => void;
+    onRetry: (message: UIMessage) => void;
+    /** Begin inline editing of a user message. */
+    onEdit: (message: UIMessage) => void;
+    /** Submit the edited text; the parent truncates + re-sends. */
+    onEditSubmit: (message: UIMessage, newText: string) => void;
+    /** Cancel editing. */
+    onEditCancel: () => void;
+    /** Id of the message currently being edited (null = none). */
+    editingId: string | null;
+    disableRetry: boolean;
+    onAskUserSubmit: (toolCallId: string, output: AskUserOutput) => void;
+}
+/**
+ * Renders a single chat message.
+ *
+ * User messages are plain bubbles. Assistant messages walk their parts in
+ * document order (see `getMessageBlocks`) so each reasoning segment, tool call
+ * and answer keeps its own block. Tool calls that are the local `ask_user`
+ * tool are rendered interactively via `AskUserCard`; every other tool gets the
+ * compact `ToolCallBlock` status line.
+ */
+export declare function MessageItem({ message, isLast, isBusy, copied, onCopy, onRetry, onEdit, onEditSubmit, onEditCancel, editingId, disableRetry, onAskUserSubmit, }: MessageItemProps): import("react").JSX.Element;

package/dist/widget/MessageList.d.ts ADDED Viewed

@@ -0,0 +1,34 @@
+import type { RefObject } from "react";
+import type { UIMessage } from "ai";
+import type { AskUserOutput } from "./types";
+export interface MessageListProps {
+    /** Visible (non-empty) messages to render. */
+    messages: UIMessage[];
+    /** The last message in the thread (used for truncation/hint logic). */
+    lastMessage: UIMessage | undefined;
+    isBusy: boolean;
+    showThinking: boolean;
+    error: Error | undefined;
+    copiedId: string | null;
+    /** Id of the message currently being edited (null = none). */
+    editingId: string | null;
+    scrollRef: RefObject<HTMLDivElement | null>;
+    onScroll: () => void;
+    onCopy: (message: UIMessage) => void;
+    onRetry: (message: UIMessage) => void;
+    onEdit: (message: UIMessage) => void;
+    onEditSubmit: (message: UIMessage, newText: string) => void;
+    onEditCancel: () => void;
+    onAskUserSubmit: (toolCallId: string, output: AskUserOutput) => void;
+    onContinue: () => void;
+    /** Greeting text (markdown) shown as the first assistant bubble. Falls back
+     * to a default when the agent has none configured. */
+    greeting: string;
+}
+/**
+ * Scrollable message area: greeting bubble, the message thread, the
+ * "cut-off by tool limit" continuation hint, the typing indicator and the
+ * error banner. Auto-scroll behaviour is driven by the parent via `scrollRef`
+ * + `onScroll` so the stickiness state stays co-located with the send logic.
+ */
+export declare function MessageList({ messages, lastMessage, isBusy, showThinking, error, copiedId, editingId, scrollRef, onScroll, onCopy, onRetry, onEdit, onEditSubmit, onEditCancel, onAskUserSubmit, onContinue, greeting, }: MessageListProps): import("react").JSX.Element;

package/dist/widget/ReasoningPanel.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+/**
+ * Collapsible "thinking" panel for an assistant message's reasoning stream.
+ * Compact by design: a single toggle row; expands to show the reasoning text.
+ * Auto-expands while actively streaming (no text yet), collapses once the
+ * answer has arrived.
+ */
+export declare function ReasoningPanel({ text, streaming, }: {
+    text: string;
+    streaming: boolean;
+}): import("react").JSX.Element;

package/dist/widget/RetryOverlay.d.ts ADDED Viewed

@@ -0,0 +1,7 @@
+import type { UIMessage } from "ai";
+/** Confirmation modal before retrying (re-sending) a user message. */
+export declare function RetryOverlay({ target, onConfirm, onCancel, }: {
+    target: UIMessage | null;
+    onConfirm: () => void;
+    onCancel: () => void;
+}): import("react").JSX.Element | null;

package/dist/widget/ToolCallBlock.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+import type { ToolInvocation } from "./types";
+/**
+ * Compact "called tool X" status line for a (non-interactive) tool invocation.
+ * Shows the tool name, a spinner while running, and a human-readable state.
+ *
+ * The interactive `ask_user` tool is rendered separately by `AskUserCard`;
+ * this component is for everything else (server-side / MCP tools).
+ */
+export declare function ToolCallBlock({ tool }: {
+    tool: ToolInvocation;
+}): import("react").JSX.Element;

package/dist/widget/TypingDots.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ /** Three-dot bouncing "typing" bubble, shown while the assistant works. */
2	+ export declare function TypingDots(): import("react").JSX.Element;

package/dist/widget/constants.d.ts ADDED Viewed

@@ -0,0 +1,22 @@
+/**
+ * Shared constants for the AI chat widget.
+ *
+ * Kept in a dedicated module so every sub-component references the same storage
+ * keys / greeting text without re-declaring them (which previously led to
+ * subtle drift across the single-file implementation).
+ */
+/** localStorage key for the stable per-browser guest id. */
+export declare const GUEST_ID_KEY = "ai_chat_guest_id";
+/** localStorage key for the current conversation id. */
+export declare const CONVERSATION_ID_KEY = "ai_chat_conversation_id";
+/** Persisted open/closed state of the panel, so it survives a page refresh. */
+export declare const PANEL_OPEN_KEY = "ai_chat_panel_open";
+/** First-visit hint bubble on the launcher button. */
+export declare const LAUNCHER_HINT_DISMISSED_KEY = "ai_chat_launcher_hint_dismissed";
+/**
+ * Initial greeting shown as an assistant bubble before any real messages exist.
+ * Purely presentational — never sent to the server or stored in history.
+ */
+export declare const GREETING = "\u4F60\u597D\uFF0C\u6211\u662F\u672C\u7AD9\u7684 AI \u52A9\u624B\uFF0C\u6709\u4EC0\u4E48\u53EF\u4EE5\u5E2E\u4F60\u7684\u5417\uFF1F";
+/** Name of the local, always-available "ask the user" tool. */
+export declare const ASK_USER_TOOL = "ask_user";

package/dist/widget/index.d.ts ADDED Viewed

@@ -0,0 +1,7 @@
+export interface AiChatWidgetProps {
+    /** Base URL of the server hosting the API (no trailing slash). */
+    serverUrl: string;
+    /** Agent UUID to scope the conversation to. */
+    agentId: string;
+}
+export declare function AiChatWidget({ serverUrl, agentId }: AiChatWidgetProps): import("react").JSX.Element;

package/dist/widget/markdown.d.ts ADDED Viewed

@@ -0,0 +1,13 @@
+import type { ComponentPropsWithoutRef } from "react";
+/**
+ * Custom markdown renderers. All links open in a new tab (safely) and get a
+ * trailing external-link icon so it's clear they navigate away.
+ */
+export declare const markdownComponents: {
+    a: ({ children, node: _node, ...props }: ComponentPropsWithoutRef<"a"> & {
+        node?: unknown;
+    }) => import("react").JSX.Element;
+    table: ({ children, node: _node, ...props }: ComponentPropsWithoutRef<"table"> & {
+        node?: unknown;
+    }) => import("react").JSX.Element;
+};

package/dist/widget/types.d.ts ADDED Viewed

@@ -0,0 +1,65 @@
+/**
+ * A tool invocation surfaced from a UIMessage's parts, for inline display.
+ *
+ * Carries the full part payload (input/output/error) so specialized renderers
+ * — such as the `ask_user` card — can build an interactive UI straight from the
+ * block data instead of re-walking the message parts.
+ */
+export interface ToolInvocation {
+    key: string;
+    /** Stable id used to report a result back via `addToolOutput`. */
+    toolCallId: string;
+    toolName: string;
+    /** "input-streaming" | "input-available" | "output-available" | "output-error" */
+    state: string;
+    /** Raw tool input (args the model supplied). */
+    input?: unknown;
+    /** Raw tool output (result, once available). */
+    output?: unknown;
+    /** Error text when `state === "output-error"`. */
+    errorText?: string;
+}
+/**
+ * An assistant message can interleave several kinds of parts across steps:
+ * reasoning -> tool call -> reasoning -> answer text. Walk them in document
+ * order and collapse only *consecutive* runs into a single block, so each
+ * distinct thinking segment renders as its own panel (rather than all
+ * reasoning being merged into one block at the top).
+ */
+export type MessageBlock = {
+    kind: "reasoning";
+    key: string;
+    text: string;
+    trailing: boolean;
+} | {
+    kind: "tool";
+    key: string;
+    tool: ToolInvocation;
+} | {
+    kind: "text";
+    key: string;
+    text: string;
+};
+export type AskUserQuestionType = "single" | "multiple" | "text" | "boolean";
+/** Input the model provides when calling the `ask_user` tool. */
+export interface AskUserInput {
+    /** The question to present to the user. */
+    question: string;
+    /** Kind of answer expected: single-choice, multiple-choice, free text, or yes/no. */
+    type: AskUserQuestionType;
+    /** Candidate options for `single`/`multiple` (ignored for `text` and `boolean`). */
+    options?: string[];
+    /** Optional extra context shown beneath the question. */
+    description?: string;
+}
+/**
+ * Result reported back to the model.
+ *
+ * `selected` always holds the real answers the user gave (normalized to an
+ * array). When the user picked the client-side "其他" affordance, `otherText`
+ * carries their manual input and `selected` contains the literal `"其他"`.
+ */
+export interface AskUserOutput {
+    selected: string[];
+    otherText?: string;
+}

package/dist/widget/utils.d.ts ADDED Viewed

@@ -0,0 +1,33 @@
+import type { UIMessage } from "ai";
+import type { MessageBlock, ToolInvocation } from "./types";
+/** Stable per-browser guest id for anonymous conversation grouping. */
+export declare function getGuestId(): string;
+/** Read the persisted conversation id (or null) from localStorage. */
+export declare function getConversationId(): string | null;
+/** Extract concatenated text from a UIMessage's parts. */
+export declare function renderText(message: UIMessage): string;
+/** Extract concatenated reasoning ("thinking") text from a UIMessage's parts. */
+export declare function renderReasoning(message: UIMessage): string;
+/**
+ * Tool parts in AI SDK v7 are typed as `tool-<name>` (static tools) or
+ * `dynamic-tool` (e.g. MCP tools discovered at runtime). Pull them out so the
+ * UI can show a compact "called tool X" status line separate from chat bubbles.
+ */
+export declare function getToolInvocations(message: UIMessage): ToolInvocation[];
+export declare function getMessageBlocks(message: UIMessage): MessageBlock[];
+/**
+ * Whether reasoning is the *trailing* part of the message — i.e. the model is
+ * currently emitting reasoning and hasn't yet moved on to a tool call or the
+ * final answer text. Used to keep the thinking panel expanded only while the
+ * reasoning is actively streaming, then auto-collapse once it ends.
+ */
+export declare function isReasoningActive(message: UIMessage): boolean;
+/**
+ * Whether an assistant message was cut off by the max-tool-steps limit: its
+ * final part is a *completed* tool call (output available/errored) with no
+ * answer text after it. Such a message never produced a reply, so the UI shows
+ * a "继续" affordance. Works for both live and restored messages.
+ */
+export declare function isTruncatedByToolLimit(message: UIMessage): boolean;
+/** Human-readable Chinese status for a tool invocation state. */
+export declare function toolStatusLabel(state: string): string;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cabbage0320/agent-plugin",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Embeddable AI chat widget SDK for any website.",
   "type": "module",
   "main": "dist/agent-plugin.umd.js",
@@ -10,7 +10,8 @@
     "dist"
   ],
   "scripts": {
-    "build": "rollup -c",
+    "build": "rollup -c && tsc",
+    "build:types": "tsc",
     "dev": "rollup -c -w"
   },
   "dependencies": {