@tetherto/mdk-ui-agent 0.0.0 → 0.12.1

package/src/components/message-list.tsx

@@ -0,0 +1,164 @@
+import type { JSX } from 'react'
+import { useCallback, useEffect, useRef } from 'react'
+
+import type { ChatMessage } from '../core/conversation-store'
+import type { ToolLabels } from '../core/tool-label'
+import type { AgentTurnState, PendingApproval } from '../core/turn'
+import { MESSAGE_ROLE } from '../core/conversation-store'
+import { TURN_STATUS } from '../core/turn'
+import { AssistantMessage } from './assistant-message'
+import { SystemMessage } from './system-message'
+import { UserMessage } from './user-message'
+
+/** How close to the bottom still counts as "following along", in pixels. */
+const PIN_THRESHOLD_PX = 48
+
+/**
+ * The operator message an assistant reply answers: the nearest user message above it.
+ *
+ * A turn can leave several assistant entries behind, so this is a scan rather than
+ * `messages[index - 1]`. Read only to tell a fleet question from a greeting.
+ */
+function precedingQuestion(messages: ChatMessage[], index: number): string {
+  for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
+    const message = messages[cursor]
+    if (message?.role === MESSAGE_ROLE.USER) return message.text
+  }
+  return ''
+}
+
+export type MessageListProps = {
+  messages: ChatMessage[]
+  live: AgentTurnState | null
+  toolLabels?: ToolLabels
+  pendingApproval: PendingApproval | null
+  isDecisionPending: boolean
+  onDecide: (approved: boolean) => void
+  /** Re-asks the last question. Offered on the newest failed turn only. */
+  onRetry?: VoidFunction
+}
+
+/**
+ * The transcript, pinned to the bottom while the operator is following along.
+ *
+ * There is no `ScrollArea` primitive in the devkit and `@radix-ui/react-scroll-area`
+ * is not a dependency, so this is a plain overflow container. The pinning rule
+ * matters more than the chrome: scrolling up to re-read an earlier answer must
+ * not be undone by the next token arriving.
+ */
+export const MessageList = ({
+  messages,
+  live,
+  toolLabels,
+  pendingApproval,
+  isDecisionPending,
+  onDecide,
+  onRetry,
+}: MessageListProps): JSX.Element => {
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const pinnedRef = useRef(true)
+
+  const handleScroll = useCallback(() => {
+    const node = scrollRef.current
+    if (!node) return
+    const distance = node.scrollHeight - node.scrollTop - node.clientHeight
+    pinnedRef.current = distance <= PIN_THRESHOLD_PX
+  }, [])
+
+  // Depends on the streamed length rather than the state object so it also fires
+  // while tokens land inside one unchanged turn.
+  const liveLength = live ? live.text.length + live.tools.length : 0
+
+  /**
+   * Whether a turn is open at all — not the same question as how much of it has arrived.
+   *
+   * `liveLength` is 0 both before a turn exists and at the instant one starts, so on its own it
+   * cannot see the transition. The assistant block (speaker label and thinking indicator) is
+   * appended in exactly that commit and went unscrolled: the operator was left looking at their
+   * own question with the reply below the fold, which reads as the panel ignoring them. It
+   * self-corrected on the first token or tool call, so the dead window was however long the
+   * model took to say anything — seconds locally, far longer on a thinking model.
+   */
+  const isLive = live !== null
+
+  /**
+   * A turn opening re-pins, whatever the operator had scrolled to.
+   *
+   * A turn only opens because they just sent something, and sending is an explicit request to
+   * see the answer — so this is not the "don't yank the view while they read" case the pinning
+   * rule protects. Without it, asking a question after scrolling up back through the transcript
+   * left both the question and its answer off-screen, with no indication either had happened.
+   */
+  useEffect(() => {
+    if (isLive) pinnedRef.current = true
+  }, [isLive])
+
+  useEffect(() => {
+    const node = scrollRef.current
+    if (!node || !pinnedRef.current) return
+    node.scrollTop = node.scrollHeight
+  }, [messages.length, liveLength, isLive, pendingApproval])
+
+  const isEmpty = messages.length === 0 && live === null
+  // Retrying an older turn would send it as the newest question, so only the last
+  // message is offered the affordance — and never while a turn is running.
+  const retryableId
+    = live === null && onRetry ? (messages.at(-1)?.error ? messages.at(-1)?.id : undefined) : undefined
+
+  return (
+    /* `aria-live` so an answer, and the approval prompt in particular, reaches a
+       screen reader as it arrives — nothing else moves focus into the transcript. */
+    <div
+      className="mdk-agent-messages"
+      ref={scrollRef}
+      aria-live="polite"
+      aria-busy={live !== null}
+      onScroll={handleScroll}
+    >
+      {isEmpty
+        ? (
+            <p className="mdk-agent-messages__empty">
+              Ask about your fleet — device status, telemetry, or an action to run.
+            </p>
+          )
+        : null}
+
+      {messages.map((message, index) => {
+        if (message.role === MESSAGE_ROLE.USER) {
+          return <UserMessage key={message.id} text={message.text} />
+        }
+        if (message.role === MESSAGE_ROLE.SYSTEM) {
+          return <SystemMessage key={message.id} text={message.text} />
+        }
+        return (
+          <AssistantMessage
+            key={message.id}
+            text={message.text}
+            question={precedingQuestion(messages, index)}
+            tools={message.tools}
+            error={message.error}
+            interrupted={message.interrupted}
+            toolLabels={toolLabels}
+            {...(message.id === retryableId && onRetry ? { onRetry } : {})}
+          />
+        )
+      })}
+
+      {live
+        ? (
+            <AssistantMessage
+              text={live.text}
+              question={precedingQuestion(messages, messages.length)}
+              tools={live.tools}
+              error={live.error}
+              streaming={live.status !== TURN_STATUS.COMPLETE && live.status !== TURN_STATUS.ERROR}
+              toolLabels={toolLabels}
+              approval={pendingApproval}
+              isDecisionPending={isDecisionPending}
+              onDecide={onDecide}
+            />
+          )
+        : null}
+    </div>
+  )
+}

package/src/components/no-tools-note.tsx

@@ -0,0 +1,33 @@
+import type { JSX } from 'react'
+
+import { InfoIcon } from './icons'
+
+/**
+ * Marks an answer that consulted nothing.
+ *
+ * The agent's premise is that it reads the fleet through tools rather than
+ * inventing it, so a turn that emitted no `tool_call` answered from the model's
+ * own weights and its conversation history — including, sometimes, a confident
+ * claim that a write was carried out when none was. That failure is not
+ * detectable from the text, but the absence of tool activity is a fact the UI
+ * holds exactly, so it is stated rather than left to be inferred from a missing
+ * chip.
+ *
+ * Still shown for benign cases — a decline, an answer the tools cannot cover —
+ * because "this answer did not consult the fleet" is true and useful there too.
+ * The one exception is small talk (`core/small-talk`): against "hey" there was
+ * never a tool to call, and marking every greeting turned the note into
+ * wallpaper.
+ *
+ * Rendered as a suffix on the existing `CO-PILOT` label rather than a sentence
+ * of its own: in a degraded session every answer carries it, and a repeated
+ * full-width line turned the transcript into a column of warnings. On the label
+ * row it costs no vertical space and still reads at a glance; the full sentence
+ * lives in the tooltip.
+ */
+export const NoToolsNote = (): JSX.Element => (
+  <span className="mdk-agent-no-tools" title="No tool was called for this answer — it came from the model alone, not from the fleet.">
+    <InfoIcon size={11} aria-hidden="true" />
+    no tools used
+  </span>
+)

package/src/components/panel-header.tsx

@@ -0,0 +1,86 @@
+import { Button } from '@tetherto/mdk-react-devkit/primitives'
+import type { JSX, ReactNode } from 'react'
+import { memo } from 'react'
+
+import { AGENT_LABELS } from '../branding'
+import { BackIcon, CloseIcon, ListLayoutIcon, MessagePlusIcon } from './icons'
+
+export const PANEL_VIEW = { CHAT: 'chat', CONVERSATIONS: 'conversations' } as const
+
+export type PanelView = (typeof PANEL_VIEW)[keyof typeof PANEL_VIEW]
+
+export type PanelHeaderProps = {
+  view: PanelView
+  title: string
+  /**
+   * The line under the title. Nothing on the gateway reports the model name or
+   * the tool count — the agent is built lazily on the first session and its MCP
+   * tools are never enumerated over HTTP — so the host supplies this or it stays
+   * empty.
+   */
+  status?: ReactNode
+  /** Disabled mid-turn: starting or switching conversation would strand the stream. */
+  actionsDisabled?: boolean
+  onNewConversation: VoidFunction
+  onToggleConversations: VoidFunction
+  onClose?: VoidFunction | undefined
+}
+
+const PanelHeaderView = ({
+  view,
+  title,
+  status,
+  actionsDisabled = false,
+  onNewConversation,
+  onToggleConversations,
+  onClose,
+}: PanelHeaderProps): JSX.Element => (
+  <header className="mdk-agent-header">
+    <div className="mdk-agent-header__titles">
+      <h2 className="mdk-agent-header__title">
+        {view === PANEL_VIEW.CONVERSATIONS
+          ? (
+              <Button
+                variant="icon"
+                className="mdk-agent-header__back"
+                aria-label={AGENT_LABELS.backToConversation}
+                icon={<BackIcon size={16} />}
+                onClick={onToggleConversations}
+              />
+            )
+          : null}
+        {title}
+      </h2>
+      {status ? <p className="mdk-agent-header__status">{status}</p> : null}
+    </div>
+
+    <div className="mdk-agent-header__actions">
+      <Button
+        variant="icon"
+        aria-label={AGENT_LABELS.newConversation}
+        disabled={actionsDisabled}
+        icon={<MessagePlusIcon size={16} />}
+        onClick={onNewConversation}
+      />
+      <Button
+        variant="icon"
+        aria-label={AGENT_LABELS.conversations}
+        aria-pressed={view === PANEL_VIEW.CONVERSATIONS}
+        icon={<ListLayoutIcon size={16} />}
+        onClick={onToggleConversations}
+      />
+      {onClose
+        ? (
+            <Button
+              variant="icon"
+              aria-label={AGENT_LABELS.close}
+              icon={<CloseIcon size={16} />}
+              onClick={onClose}
+            />
+          )
+        : null}
+    </div>
+  </header>
+)
+
+export const PanelHeader = memo(PanelHeaderView)

package/src/components/rehype-highlight-subset.ts

@@ -0,0 +1,84 @@
+/**
+ * Syntax highlighting for fenced code, restricted to the grammars this panel
+ * actually sees.
+ *
+ * `rehype-highlight` would do the same job, but it statically imports lowlight's
+ * `common` set — 37 grammars and most of highlight.js's bulk — so its
+ * `languages` option changes what gets *registered*, never what gets *bundled*.
+ * Measured against the generated shell, that was 179 kB raw / 55 kB gzip, more
+ * than doubling the panel's chunk to highlight languages a fleet co-pilot never
+ * emits. Registering three grammars directly costs a fraction of that.
+ *
+ * Anything outside the set still renders — unhighlighted, in the mono face the
+ * panel already uses.
+ */
+
+import bash from 'highlight.js/lib/languages/bash'
+import json from 'highlight.js/lib/languages/json'
+import yaml from 'highlight.js/lib/languages/yaml'
+import type { Element, ElementContent, Node, Parent, Root, Text } from 'hast'
+import { createLowlight } from 'lowlight'
+
+const lowlight = createLowlight({ bash, json, yaml })
+
+const LANGUAGE_PREFIX = 'language-'
+
+function isElement(node: Node): node is Element {
+  return node.type === 'element'
+}
+
+function isParent(node: Node): node is Parent {
+  return Array.isArray((node as Parent).children)
+}
+
+/** Concatenates the text under a node, which for a code block is its source. */
+function textOf(node: Node): string {
+  if (node.type === 'text') return (node as Text).value
+  if (!isParent(node)) return ''
+  return node.children.map((child) => textOf(child)).join('')
+}
+
+function languageOf(node: Element): string | null {
+  const className = node.properties?.className
+  const classes = Array.isArray(className) ? className.map(String) : []
+  const match = classes.find((name) => name.startsWith(LANGUAGE_PREFIX))
+  return match ? match.slice(LANGUAGE_PREFIX.length) : null
+}
+
+function highlightCodeBlock(node: Element): void {
+  const language = languageOf(node)
+  if (!language || !lowlight.registered(language)) return
+
+  try {
+    const result = lowlight.highlight(language, textOf(node))
+    // lowlight returns a Root, whose children are typed wider than a code
+    // element's. In practice it only ever emits elements and text.
+    node.children = result.children as ElementContent[]
+    node.properties = {
+      ...node.properties,
+      className: [...(Array.isArray(node.properties?.className) ? node.properties.className : []), 'hljs'],
+    }
+  } catch {
+    // A grammar that throws on odd input must not take the whole answer with it;
+    // the block simply stays unhighlighted.
+  }
+}
+
+function walk(node: Node): void {
+  if (!isParent(node)) return
+
+  for (const child of node.children) {
+    // Only `<pre><code>` — an inline `code` span is not a code block.
+    if (isElement(node) && node.tagName === 'pre' && isElement(child) && child.tagName === 'code') {
+      highlightCodeBlock(child)
+      continue
+    }
+    walk(child)
+  }
+}
+
+export function rehypeHighlightSubset() {
+  return (tree: Root): void => {
+    walk(tree)
+  }
+}

package/src/components/system-message.tsx

@@ -0,0 +1,19 @@
+import type { JSX } from 'react'
+import { memo } from 'react'
+
+export type SystemMessageProps = {
+  text: string
+}
+
+/**
+ * A note from the panel itself, not from the model.
+ *
+ * Used where the transcript would otherwise imply something untrue — most of all
+ * a re-minted session, where the conversation reads as continuous but the agent
+ * remembers none of it.
+ */
+const SystemMessageView = ({ text }: SystemMessageProps): JSX.Element => (
+  <p className="mdk-agent-system" role="note">{text}</p>
+)
+
+export const SystemMessage = memo(SystemMessageView)

package/src/components/tool-chip.tsx

@@ -0,0 +1,58 @@
+import type { JSX } from 'react'
+import { memo } from 'react'
+
+import type { ToolLabels } from '../core/tool-label'
+import type { ToolStep } from '../core/turn'
+import { formatDuration, toolLabel } from '../core/tool-label'
+import { TOOL_STATUS } from '../core/turn'
+import { CloseIcon, TickIcon, WarningIcon } from './icons'
+
+export type ToolChipProps = {
+  step: ToolStep
+  toolLabels?: ToolLabels
+}
+
+/**
+ * One tool call, as the small pill above an answer: `✓ Site status · 0.4s`.
+ *
+ * Showing tool activity is not decoration. Model routing is the weak point of
+ * the stack — a turn that answers without ever calling a tool is answering from
+ * the prompt, not from the fleet — so the chips are what make that visible
+ * instead of mysterious.
+ */
+const ToolChipView = ({ step, toolLabels }: ToolChipProps): JSX.Element => {
+  const duration = formatDuration(step.durationMs)
+  const label = toolLabel(step.name, toolLabels)
+
+  const detail
+    = step.status === TOOL_STATUS.AWAITING_APPROVAL
+      ? 'awaiting approval'
+      : step.status === TOOL_STATUS.RUNNING
+        ? 'running…'
+        : step.status === TOOL_STATUS.REJECTED
+          // Deliberately no duration: nothing ran, so there is nothing to time.
+          ? 'not run'
+          // The turn ended before the result came back, so whether it ran is unknown
+          // — and the elapsed time would measure the failure, not the tool.
+          : step.status === TOOL_STATUS.INTERRUPTED
+            ? 'no result'
+            : duration
+
+  return (
+    <span
+      className={`mdk-agent-tool-chip mdk-agent-tool-chip--${step.status}`}
+      title={step.contractViolation ?? step.text ?? label}
+    >
+      <span className="mdk-agent-tool-chip__icon" aria-hidden="true">
+        {step.status === TOOL_STATUS.OK ? <TickIcon size={12} /> : null}
+        {step.status === TOOL_STATUS.ERROR ? <WarningIcon size={12} /> : null}
+        {step.status === TOOL_STATUS.REJECTED ? <CloseIcon size={12} /> : null}
+        {step.status === TOOL_STATUS.INTERRUPTED ? <WarningIcon size={12} /> : null}
+      </span>
+      <span className="mdk-agent-tool-chip__label">{label}</span>
+      {detail ? <span className="mdk-agent-tool-chip__detail">{`· ${detail}`}</span> : null}
+    </span>
+  )
+}
+
+export const ToolChip = memo(ToolChipView)

package/src/components/user-message.tsx

@@ -0,0 +1,18 @@
+import type { JSX } from 'react'
+import { memo } from 'react'
+
+import { AGENT_LABELS } from '../branding'
+
+export type UserMessageProps = {
+  text: string
+}
+
+/** Right-aligned operator turn: an `OPERATOR` caption above a bordered bubble. */
+const UserMessageView = ({ text }: UserMessageProps): JSX.Element => (
+  <div className="mdk-agent-message mdk-agent-message--user">
+    <p className="mdk-agent-message__role">{AGENT_LABELS.operator}</p>
+    <div className="mdk-agent-message__bubble">{text}</div>
+  </div>
+)
+
+export const UserMessage = memo(UserMessageView)