@aphrody/m3-ai 3.3.2 → 3.3.5

package/src/index.ts

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: Apache-2.0 AND MIT
+// Derived from SpaceUI (packages/aphrody-spaceui/packages/ai/src/index.ts), MIT, rebuilt on Material Design 3.
+// @aphrody/m3-ai - AI agent interaction components on Material Design 3
+
+// Types
+export type {
+  ToolCallStatus,
+  ToolCallPair,
+  ActionContent,
+  TranscriptStep,
+  TranscriptItem,
+  TaskInfo,
+  MemoryInfo,
+  CronJobInfo,
+  AgentInfo,
+  ModelOption,
+  TaskStatus,
+  TaskPriority,
+  Subtask,
+  Task,
+} from "./types";
+
+export {
+  pairTranscriptSteps,
+  tryParseJson,
+  isErrorResult,
+  TASK_STATUS_ORDER,
+  TASK_STATUS_LABEL,
+  TASK_PRIORITY_LABEL,
+} from "./types";
+
+// Components
+export { ToolCall } from "./ToolCall";
+export type { ToolCallProps } from "./ToolCall";
+export {
+  Markdown,
+  CodeBlock,
+  InlineMath,
+  BlockMath,
+  externalLinkProps,
+  isExternalHref,
+} from "./Markdown";
+export type {
+  MarkdownProps,
+  CodeBlockProps,
+  InlineMathProps,
+  BlockMathProps,
+  MarkdownLinkHandler,
+  MarkdownLinkRenderer,
+} from "./Markdown";
+export { MessageBubble } from "./MessageBubble";
+export type { MessageBubbleProps } from "./MessageBubble";
+export { InlineWorkerCard } from "./InlineWorkerCard";
+export type { InlineWorkerCardProps } from "./InlineWorkerCard";
+export { InlineBranchCard } from "./InlineBranchCard";
+export type { InlineBranchCardProps } from "./InlineBranchCard";
+export { ModelSelector, ModelOptionList, groupModelsByProvider } from "./ModelSelector";
+export type { ModelSelectorProps, ModelOptionListProps } from "./ModelSelector";
+export { ChatComposer } from "./ChatComposer";
+export type { ChatComposerProps } from "./ChatComposer";
+
+// Google & Gemini Desktop / Web benchmark components
+export { GoogleSpotlightBar } from "./GoogleSpotlightBar";
+export type { GoogleSpotlightBarProps } from "./GoogleSpotlightBar";
+export { GeminiAccountMenu, ComposerMoreUploadsMenu } from "./GeminiAccountMenu";
+export type {
+  GeminiAccountMenuProps,
+  ComposerMoreUploadsMenuProps,
+  MenuItem,
+} from "./GeminiAccountMenu";
+export { GeminiPersonalContextEdit } from "./GeminiPersonalContextEdit";
+export type { GeminiPersonalContextEditProps } from "./GeminiPersonalContextEdit";
+
+// Task components
+export { TaskStatusIcon } from "./TaskStatusIcon";
+export type { TaskStatusIconProps } from "./TaskStatusIcon";
+export { TaskPriorityIcon } from "./TaskPriorityIcon";
+export type { TaskPriorityIconProps } from "./TaskPriorityIcon";
+export { TaskRow } from "./TaskRow";
+export type { TaskRowProps } from "./TaskRow";
+export { TaskList } from "./TaskList";
+export type { TaskListProps } from "./TaskList";
+export { TaskDetail } from "./TaskDetail";
+export type { TaskDetailProps } from "./TaskDetail";
+export { TaskCreateForm } from "./TaskCreateForm";
+export type { TaskCreateFormProps, TaskCreateFormData } from "./TaskCreateForm";
+
+// AG-UI Protocol & Agent-to-User (A2U) Bridge
+export { EventType } from "@aphrody/ag-ui";
+export {
+  AgUiEventAccumulator,
+  agUiEventsToTranscriptSteps,
+  agUiEventsToTranscriptItems,
+  coordEnvelopeToAgUiEvent,
+  agUiEventToCoordEnvelope,
+} from "./AgUiEventStream";
+export type {
+  CoordEnvelope,
+  EnvelopeKind,
+  SubagentTrace,
+  AgUiStreamState,
+} from "./AgUiEventStream";
+
+// Aphrody A2A (Agent-to-Agent) Fleet UI
+export { A2APeerInspector } from "./A2APeerInspector";
+export type { A2APeerInspectorProps, AgentPeer, SendEnvelopePayload } from "./A2APeerInspector";
+export { A2ATaskTimeline } from "./A2ATaskTimeline";
+export type { A2ATaskTimelineProps, TimelineStep } from "./A2ATaskTimeline";
+
+// MCP-UI Generative Card
+export { McpAppCard } from "./McpAppCard";
+export type { McpAppCardProps } from "./McpAppCard";
+
+// Local chat: injectable labels, OpenAI-compatible streaming, conversations, grounding, memory
+export {
+  chatLabelsEn,
+  chatLabelsFr,
+  chatLabelsJa,
+  chatLabelsByLang,
+  defaultChatLabels,
+  resolveChatLabels,
+  formatLabel,
+} from "./chatLabels";
+export type { ChatLabels } from "./chatLabels";
+export {
+  ChatStreamError,
+  accumulateToolCall,
+  chatCompletionsUrl,
+  chatReducer,
+  createSseParser,
+  initialChatState,
+  isUnavailableStatus,
+  newMessageId,
+  parseChatCompletionChunk,
+  streamChatCompletion,
+  toOpenAIMessages,
+} from "./openaiChatStream";
+export type {
+  ChatAction,
+  ChatMessage,
+  ChatRole,
+  ChatState,
+  ChatStatus,
+  ChatStreamErrorKind,
+  ChatStreamEvent,
+  OpenAIToolCall,
+  StreamChatOptions,
+} from "./openaiChatStream";
+export { useOpenAIChat } from "./useOpenAIChat";
+export type { UseOpenAIChatOptions, UseOpenAIChatResult } from "./useOpenAIChat";
+export { ConversationList, filterConversations } from "./ConversationList";
+export type { ConversationListProps, ConversationSummary } from "./ConversationList";
+export { ModelUnavailable, clampProgress } from "./ModelUnavailable";
+export type { ModelAvailabilityPhase, ModelUnavailableProps } from "./ModelUnavailable";
+export {
+  CitationChip,
+  CitationList,
+  CitedMarkdown,
+  RefusalNotice,
+  citedNumbers,
+  linkCitationMarkers,
+} from "./citations";
+export type {
+  Citation,
+  CitationChipProps,
+  CitationListProps,
+  CitedMarkdownProps,
+  RefusalNoticeProps,
+} from "./citations";
+export { MemoryPanel } from "./MemoryPanel";
+export type { MemoryItem, MemoryPanelProps } from "./MemoryPanel";
+export { ChatIcon, chatIconNames } from "./chatIcons";
+export type { ChatIconName, ChatIconProps } from "./chatIcons";

package/src/internal.tsx

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: Apache-2.0
+// Shared Material Design 3 building blocks for @aphrody/m3-ai (internal, not exported).
+
+import { m3Durations, m3Easings } from "@aphrody/m3-motion";
+import { clsx } from "clsx";
+import type { ReactNode } from "react";
+
+/** The M3 focus indicator (contract: docs/design/SPACEUI-M3-FUSION.md, "States"). */
+export const focusRing =
+  "outline-none focus-visible:outline-3 focus-visible:outline-secondary focus-visible:outline-offset-2";
+
+/** Expand / collapse: enter on emphasized decelerate, exit on emphasized accelerate. */
+export const expandMotion = {
+  initial: { height: 0, opacity: 0 },
+  animate: {
+    height: "auto",
+    opacity: 1,
+    transition: { duration: m3Durations.medium2, ease: m3Easings.emphasizedDecelerate },
+  },
+  exit: {
+    height: 0,
+    opacity: 0,
+    transition: { duration: m3Durations.short4, ease: m3Easings.emphasizedAccelerate },
+  },
+} as const;
+
+/**
+ * Indeterminate M3 circular progress indicator (active indicator on `primary` or the current
+ * color, 4 dp track gap omitted at small sizes). Replaces the upstream Grid loader.
+ */
+export function CircularIndicator({
+  size = 16,
+  className,
+  label = "Loading",
+}: {
+  size?: number;
+  className?: string;
+  label?: string;
+}) {
+  const stroke = size <= 16 ? 2 : size <= 24 ? 3 : 4;
+  const r = (size - stroke) / 2;
+  const c = 2 * Math.PI * r;
+  return (
+    <span
+      // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- M3 circular indeterminate indicator is an animated SVG arc; a native <progress> cannot render it.
+      role="progressbar"
+      aria-label={label}
+      className={clsx("m3-circular-indicator inline-flex shrink-0 text-primary", className)}
+      style={{ width: size, height: size }}
+    >
+      <svg
+        width={size}
+        height={size}
+        viewBox={`0 0 ${size} ${size}`}
+        className="animate-spin"
+        aria-hidden="true"
+      >
+        <circle
+          cx={size / 2}
+          cy={size / 2}
+          r={r}
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={stroke}
+          strokeLinecap="round"
+          strokeDasharray={`${c * 0.7} ${c}`}
+        />
+      </svg>
+    </span>
+  );
+}
+
+export type ChipTone = "primary" | "success" | "error" | "warning" | "neutral";
+
+const chipTones: Record<ChipTone, string> = {
+  primary: "bg-primary-container text-on-primary-container",
+  success: "bg-success-container text-on-success-container",
+  error: "bg-error-container text-on-error-container",
+  warning: "bg-warning-container text-on-warning-container",
+  neutral: "border border-outline-variant text-on-surface-variant",
+};
+
+/** Non-interactive M3 assist chip used as a status label (dense, `rounded-small`). */
+export function StatusChip({
+  tone,
+  icon,
+  children,
+  className,
+}: {
+  tone: ChipTone;
+  icon?: ReactNode;
+  children: ReactNode;
+  className?: string;
+}) {
+  return (
+    <span
+      className={clsx(
+        "inline-flex h-6 shrink-0 items-center gap-1 rounded-small px-2 text-label-medium",
+        chipTones[tone],
+        className,
+      )}
+    >
+      {icon}
+      {children}
+    </span>
+  );
+}

package/src/openaiChatStream.ts

@@ -0,0 +1,400 @@
+// SPDX-License-Identifier: Apache-2.0
+// Streaming client of an OpenAI-compatible `/v1/chat/completions` endpoint (llama-server,
+// vLLM, the Aphrody gateway...): SSE framing, chunk decoding, tool-call accumulation, a pure
+// reducer for the conversation state, and typed errors that tell "model unavailable" apart.
+// Pure module: no React, no DOM; `fetch` is injectable.
+
+import type { Citation } from "./citations";
+
+export type ChatRole = "system" | "user" | "assistant" | "tool";
+
+/** One complete tool call, as OpenAI returns it once every delta is merged. */
+export interface OpenAIToolCall {
+  id: string;
+  type: "function";
+  function: { name: string; arguments: string };
+}
+
+/** One message of the conversation, in the shape the chat components render. */
+export interface ChatMessage {
+  id: string;
+  role: ChatRole;
+  content: string;
+  /** `reasoning_content` deltas (reasoning models), kept apart from the answer. */
+  reasoning?: string;
+  toolCalls?: OpenAIToolCall[];
+  /** For a `tool` message: the call it answers. */
+  toolCallId?: string;
+  finishReason?: string | null;
+  /** Grounded answer: the numbered passages `[n]` the text refers to. */
+  citations?: Citation[];
+  /** The backend refused to answer (out of the sources' scope). */
+  refusal?: boolean;
+}
+
+/** What one SSE chunk contributes. */
+export type ChatStreamEvent =
+  | { type: "content"; text: string }
+  | { type: "reasoning"; text: string }
+  | {
+      type: "tool_call_delta";
+      index: number;
+      id?: string;
+      name?: string;
+      arguments?: string;
+    }
+  | { type: "citations"; citations: Citation[] }
+  | { type: "refusal"; text?: string }
+  | { type: "finish"; reason: string }
+  | { type: "done" };
+
+export type ChatStreamErrorKind = "network" | "http" | "aborted" | "parse" | "stream";
+
+/** Typed failure of a chat request. `unavailable` marks a model that cannot answer right now. */
+export class ChatStreamError extends Error {
+  readonly kind: ChatStreamErrorKind;
+  readonly status?: number;
+  readonly unavailable: boolean;
+
+  constructor(
+    kind: ChatStreamErrorKind,
+    message: string,
+    options: { status?: number; cause?: unknown } = {},
+  ) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "ChatStreamError";
+    this.kind = kind;
+    this.status = options.status;
+    this.unavailable = kind === "network" || isUnavailableStatus(options.status);
+  }
+}
+
+/** HTTP statuses that mean "no model to answer" rather than "bad request". */
+export function isUnavailableStatus(status: number | undefined): boolean {
+  return status === 404 || status === 502 || status === 503 || status === 504;
+}
+
+/**
+ * Incremental SSE parser: feed it decoded text in arbitrary pieces, it calls `onData` with the
+ * payload of every complete event (multi-line `data:` fields joined by `\n`). Comments and
+ * other fields are ignored.
+ */
+export function createSseParser(onData: (data: string) => void): {
+  push(chunk: string): void;
+  flush(): void;
+} {
+  let buffer = "";
+  let data: string[] = [];
+  const dispatch = () => {
+    if (data.length > 0) onData(data.join("\n"));
+    data = [];
+  };
+  const line = (raw: string) => {
+    const text = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    if (text === "") return dispatch();
+    if (text.startsWith(":")) return;
+    const colon = text.indexOf(":");
+    const field = colon === -1 ? text : text.slice(0, colon);
+    let value = colon === -1 ? "" : text.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "data") data.push(value);
+  };
+  return {
+    push(chunk) {
+      buffer += chunk;
+      let newline = buffer.indexOf("\n");
+      while (newline !== -1) {
+        line(buffer.slice(0, newline));
+        buffer = buffer.slice(newline + 1);
+        newline = buffer.indexOf("\n");
+      }
+    },
+    flush() {
+      if (buffer.length > 0) line(buffer);
+      buffer = "";
+      dispatch();
+    },
+  };
+}
+
+interface RawChunk {
+  choices?: {
+    delta?: {
+      content?: string | null;
+      reasoning_content?: string | null;
+      refusal?: string | null;
+      tool_calls?: {
+        index?: number;
+        id?: string;
+        function?: { name?: string; arguments?: string };
+      }[];
+    };
+    finish_reason?: string | null;
+  }[];
+  citations?: Citation[];
+  refusal?: boolean;
+  error?: { message?: string } | string;
+}
+
+/**
+ * Decode one `data:` payload of a chat-completions stream into events. `[DONE]` yields `done`.
+ * A payload carrying `error` throws a `stream` error; malformed JSON throws a `parse` error.
+ * Top-level `citations` / `refusal: true` (grounded backends such as Shenron) are passed on.
+ */
+export function parseChatCompletionChunk(payload: string): ChatStreamEvent[] {
+  const trimmed = payload.trim();
+  if (trimmed === "") return [];
+  if (trimmed === "[DONE]") return [{ type: "done" }];
+  let chunk: RawChunk;
+  try {
+    chunk = JSON.parse(trimmed) as RawChunk;
+  } catch (cause) {
+    throw new ChatStreamError("parse", "invalid chat-completions chunk", { cause });
+  }
+  if (chunk.error) {
+    const message = typeof chunk.error === "string" ? chunk.error : chunk.error.message;
+    throw new ChatStreamError("stream", message || "stream error");
+  }
+  const events: ChatStreamEvent[] = [];
+  for (const choice of chunk.choices ?? []) {
+    const delta = choice.delta;
+    if (delta?.reasoning_content) events.push({ type: "reasoning", text: delta.reasoning_content });
+    if (delta?.content) events.push({ type: "content", text: delta.content });
+    if (delta?.refusal) events.push({ type: "refusal", text: delta.refusal });
+    for (const call of delta?.tool_calls ?? []) {
+      events.push({
+        type: "tool_call_delta",
+        index: call.index ?? 0,
+        id: call.id,
+        name: call.function?.name,
+        arguments: call.function?.arguments,
+      });
+    }
+    if (choice.finish_reason) events.push({ type: "finish", reason: choice.finish_reason });
+  }
+  if (Array.isArray(chunk.citations))
+    events.push({ type: "citations", citations: chunk.citations });
+  if (chunk.refusal === true) events.push({ type: "refusal" });
+  return events;
+}
+
+/** Merge a tool-call delta into the calls accumulated so far (returns a new array). */
+export function accumulateToolCall(
+  calls: readonly OpenAIToolCall[],
+  delta: Extract<ChatStreamEvent, { type: "tool_call_delta" }>,
+): OpenAIToolCall[] {
+  const next = calls.slice();
+  const current = next[delta.index] ?? {
+    id: "",
+    type: "function" as const,
+    function: { name: "", arguments: "" },
+  };
+  next[delta.index] = {
+    id: delta.id ?? current.id,
+    type: "function",
+    function: {
+      name: current.function.name + (delta.name ?? ""),
+      arguments: current.function.arguments + (delta.arguments ?? ""),
+    },
+  };
+  return next;
+}
+
+/** The request body messages, in the OpenAI wire shape. */
+export function toOpenAIMessages(messages: readonly ChatMessage[]): Record<string, unknown>[] {
+  return messages.map((message) => {
+    const wire: Record<string, unknown> = { role: message.role, content: message.content };
+    if (message.toolCalls?.length) wire.tool_calls = message.toolCalls;
+    if (message.toolCallId) wire.tool_call_id = message.toolCallId;
+    return wire;
+  });
+}
+
+export interface StreamChatOptions {
+  /** API root including `/v1` (e.g. `http://127.0.0.1:8080/v1`). */
+  baseUrl: string;
+  model?: string;
+  messages: readonly ChatMessage[];
+  /** Extra body fields (`temperature`, `tools`, `max_tokens`...). */
+  body?: Record<string, unknown>;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+  fetch?: typeof fetch;
+}
+
+/** `<baseUrl>/chat/completions`, tolerant of a trailing slash. */
+export function chatCompletionsUrl(baseUrl: string): string {
+  return `${baseUrl.replace(/\/+$/, "")}/chat/completions`;
+}
+
+/**
+ * POST a streaming chat completion and yield its events until `[DONE]` or the end of the body.
+ *
+ * Throws `ChatStreamError`: `network` (fetch rejected: server down), `http` (non-2xx status;
+ * `unavailable` for 404/502/503/504), `aborted` (the signal fired), `parse` / `stream`.
+ */
+export async function* streamChatCompletion(
+  options: StreamChatOptions,
+): AsyncGenerator<ChatStreamEvent, void, undefined> {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  let response: Response;
+  try {
+    response = await doFetch(chatCompletionsUrl(options.baseUrl), {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "text/event-stream",
+        ...options.headers,
+      },
+      body: JSON.stringify({
+        ...options.body,
+        ...(options.model ? { model: options.model } : {}),
+        messages: toOpenAIMessages(options.messages),
+        stream: true,
+      }),
+      signal: options.signal,
+    });
+  } catch (cause) {
+    if (options.signal?.aborted) throw new ChatStreamError("aborted", "request aborted", { cause });
+    throw new ChatStreamError("network", "chat endpoint unreachable", { cause });
+  }
+  if (!response.ok) {
+    let detail = "";
+    try {
+      detail = (await response.text()).slice(0, 500);
+    } catch {
+      // body unreadable: the status alone is reported
+    }
+    throw new ChatStreamError("http", detail || `HTTP ${response.status}`, {
+      status: response.status,
+    });
+  }
+  if (!response.body) throw new ChatStreamError("stream", "response has no body");
+
+  const queue: string[] = [];
+  const parser = createSseParser((data) => queue.push(data));
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  try {
+    for (;;) {
+      let result: Awaited<ReturnType<typeof reader.read>>;
+      try {
+        // oxlint-disable-next-line no-await-in-loop -- SSE chunks are read in order, one at a time.
+        result = await reader.read();
+      } catch (cause) {
+        if (options.signal?.aborted)
+          throw new ChatStreamError("aborted", "request aborted", { cause });
+        throw new ChatStreamError("stream", "stream interrupted", { cause });
+      }
+      if (result.done) {
+        parser.push(decoder.decode());
+        parser.flush();
+      } else {
+        parser.push(decoder.decode(result.value, { stream: true }));
+      }
+      while (queue.length > 0) {
+        for (const event of parseChatCompletionChunk(queue.shift()!)) {
+          yield event;
+          if (event.type === "done") return;
+        }
+      }
+      if (result.done) return;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// ── Conversation state ─────────────────────────────────────────────────────────────────────
+
+export type ChatStatus = "idle" | "streaming" | "error" | "unavailable";
+
+export interface ChatState {
+  messages: ChatMessage[];
+  status: ChatStatus;
+  error: ChatStreamError | null;
+}
+
+export type ChatAction =
+  | { type: "start"; user: ChatMessage; assistantId: string }
+  | { type: "event"; assistantId: string; event: ChatStreamEvent }
+  | { type: "finish" }
+  | { type: "fail"; error: ChatStreamError }
+  | { type: "stop" }
+  | { type: "reset"; messages?: ChatMessage[] }
+  | { type: "set"; messages: ChatMessage[] };
+
+export function initialChatState(messages: ChatMessage[] = []): ChatState {
+  return { messages, status: "idle", error: null };
+}
+
+function applyEvent(message: ChatMessage, event: ChatStreamEvent): ChatMessage {
+  switch (event.type) {
+    case "content":
+      return { ...message, content: message.content + event.text };
+    case "reasoning":
+      return { ...message, reasoning: (message.reasoning ?? "") + event.text };
+    case "tool_call_delta":
+      return { ...message, toolCalls: accumulateToolCall(message.toolCalls ?? [], event) };
+    case "citations":
+      return { ...message, citations: event.citations };
+    case "refusal":
+      return { ...message, refusal: true };
+    case "finish":
+      return { ...message, finishReason: event.reason };
+    case "done":
+      return message;
+  }
+}
+
+/** Pure reducer of a streamed conversation (the state behind `useOpenAIChat`). */
+export function chatReducer(state: ChatState, action: ChatAction): ChatState {
+  switch (action.type) {
+    case "start":
+      return {
+        status: "streaming",
+        error: null,
+        messages: [
+          ...state.messages,
+          action.user,
+          { id: action.assistantId, role: "assistant", content: "" },
+        ],
+      };
+    case "event":
+      return {
+        ...state,
+        messages: state.messages.map((message) =>
+          message.id === action.assistantId ? applyEvent(message, action.event) : message,
+        ),
+      };
+    case "finish":
+    case "stop":
+      return { ...state, status: "idle" };
+    case "fail": {
+      // An empty assistant turn left by a failed request is dropped.
+      const last = state.messages.at(-1);
+      const messages =
+        last && last.role === "assistant" && !last.content && !last.toolCalls?.length
+          ? state.messages.slice(0, -1)
+          : state.messages;
+      return {
+        messages,
+        status: action.error.unavailable ? "unavailable" : "error",
+        error: action.error,
+      };
+    }
+    case "reset":
+      return initialChatState(action.messages ?? []);
+    case "set":
+      return { ...state, messages: action.messages };
+  }
+}
+
+let counter = 0;
+/** Message id: `crypto.randomUUID` when present, else a process-local counter. */
+export function newMessageId(): string {
+  const uuid = globalThis.crypto?.randomUUID?.();
+  if (uuid) return uuid;
+  counter += 1;
+  return `msg-${Date.now().toString(36)}-${counter}`;
+}