@tetherto/mdk-ui-agent 0.0.0 → 0.12.1

package/package.json

@@ -1 +1,105 @@
-{"name":"@tetherto/mdk-ui-agent","version":"0.0.0"}
+{
+  "name": "@tetherto/mdk-ui-agent",
+  "type": "module",
+  "version": "0.12.1",
+  "private": false,
+  "description": "Injectable operator Co-pilot chat UI for the MDK agent gateway plugin. Streams the six-event agent contract over SSE and renders it as a docked panel or a full-page route.",
+  "license": "Apache-2.0",
+  "sideEffects": [
+    "*.css",
+    "*.scss"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "default": "./dist/core/index.js"
+    },
+    "./chat-page": {
+      "types": "./dist/entries/chat-page.d.ts",
+      "import": "./dist/entries/chat-page.js",
+      "default": "./dist/entries/chat-page.js"
+    },
+    "./panel": {
+      "types": "./dist/components/co-pilot-panel.d.ts",
+      "import": "./dist/components/co-pilot-panel.js",
+      "default": "./dist/components/co-pilot-panel.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tetherto/mdk.git",
+    "directory": "ui/packages/ui-agent"
+  },
+  "publishConfig": {
+    "access": "public"
+  },  
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/specs",
+    "!src/**/test-utils"
+  ],
+  "scripts": {
+    "build": "npm run check:styles && npm run build:ts && npm run build:scss",
+    "prepublishOnly": "npm run build",
+    "build:ts": "rimraf dist tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "build:scss": "vite build",
+    "check:styles": "node scripts/check-style-forwards.mjs",
+    "clean": "rimraf dist node_modules .turbo",
+    "dev": "concurrently -n ts,scss -c cyan,magenta \"npm run dev:ts\" \"npm run dev:scss\"",
+    "dev:ts": "tsc --watch -p tsconfig.build.json",
+    "dev:scss": "vite build --watch",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "format": "oxlint --fix",
+    "test": "vitest run --config vitest.config.js",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest run --config vitest.config.js --coverage",
+    "typecheck": "tsc --noEmit",
+    "watch": "npm run dev",
+    "watch:ts": "npm run dev:ts",
+    "watch:scss": "npm run dev:scss"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "@tetherto/mdk-react-adapter": "^0.12.1",
+    "@tetherto/mdk-react-devkit": "^0.12.1",
+    "@tetherto/mdk-ui-foundation": "^0.12.1",
+    "highlight.js": "^11.11.1",
+    "lodash": "^4.18.1",
+    "lowlight": "^3.3.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "zustand": "^5.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.59.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/lodash": "^4.17.24",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "@vitest/coverage-v8": "^4.1.2",
+    "happy-dom": "^21.0.4",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "sass": "^1.83.0",
+    "vitest": "^4.1.2"
+  }
+}

package/src/branding.ts

@@ -0,0 +1,40 @@
+/**
+ * The product name, in one place.
+ *
+ * "Co-pilot" is a placeholder — it collides with GitHub Copilot and the final
+ * name has not been decided. Every user-visible string in the package derives
+ * from `AGENT_NAME` below, so renaming it is a one-line change here.
+ *
+ * Deliberately kept out of the identifiers: the package is `@tetherto/mdk-ui-agent`,
+ * the CSS classes are `mdk-agent-*`, and the storage key is `mdk-ui-agent:*`.
+ * None of those need to move when the name does. The exported component names
+ * (`CoPilot`, `CoPilotProps`, …) are the only remaining mention, and they are a
+ * mechanical rename plus a deprecated alias whenever the decision lands.
+ *
+ * Hosts that want a different name per deployment do not need to fork this:
+ * pass `title` to `CoPilot` / `ChatUIEntry`.
+ */
+
+export const AGENT_NAME = 'Co-pilot'
+
+/** How the operator's own turns are labelled. */
+export const OPERATOR_NAME = 'Operator'
+
+const lower = AGENT_NAME.toLowerCase()
+
+/**
+ * Accessible names and headings, derived so they stay consistent with
+ * {@link AGENT_NAME}.
+ */
+export const AGENT_LABELS = {
+  name: AGENT_NAME,
+  operator: OPERATOR_NAME,
+  open: `Open ${lower}`,
+  close: `Close ${lower}`,
+  composer: `Message the ${lower}`,
+  conversations: 'Conversations',
+  newConversation: 'New conversation',
+  backToConversation: 'Back to conversation',
+  approvalRequired: 'Approval required',
+  placeholder: 'Ask about your fleet...',
+} as const

package/src/components/approval-card.tsx

@@ -0,0 +1,141 @@
+import { Button } from '@tetherto/mdk-react-devkit/primitives'
+import isNil from 'lodash/isNil'
+import type { JSX } from 'react'
+
+import type { ToolLabels } from '../core/tool-label'
+import type { PendingApproval } from '../core/turn'
+import { AGENT_LABELS } from '../branding'
+import { humanizeToolName, toolLabel } from '../core/tool-label'
+
+/** Args the reference site tools use to name their target, most specific first. */
+const TARGET_KEYS = ['ref', 'deviceId', 'device', 'id', 'name'] as const
+
+/**
+ * Friendlier names for argument keys the reference tools use.
+ *
+ * `action` matters most: without it the card shows two rows both labelled
+ * "Action" — the tool itself, and the tool's `action` argument — which is what
+ * the design calls "Command". Anything not listed is humanized from its key.
+ */
+const ARG_LABELS: Record<string, string> = {
+  action: 'Command',
+  mode: 'Mode',
+  family: 'Family',
+  state: 'State',
+}
+
+/** Shown for an argument the tool declared but sent no value for. */
+const EMPTY_VALUE = '—'
+
+const describeValue = (value: unknown): string => {
+  if (isNil(value)) return EMPTY_VALUE
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  return JSON.stringify(value)
+}
+
+export type ApprovalRow = { label: string, value: string }
+
+/**
+ * Flattens the tool args into the Action / Device / Command rows the design
+ * shows.
+ *
+ * Tools are supplied by whichever MCP server the operator points the agent at,
+ * so no argument name is guaranteed. The target is looked up across the names
+ * the reference tools use and everything else is listed as-is, which degrades to
+ * a plain key/value dump for an unknown tool rather than to nothing.
+ */
+export function describeApproval(approval: PendingApproval, labels?: ToolLabels): ApprovalRow[] {
+  const rows: ApprovalRow[] = [{ label: 'Action', value: toolLabel(approval.name, labels) }]
+
+  const targetKey = TARGET_KEYS.find((key) => key in approval.args)
+  if (targetKey) rows.push({ label: 'Device', value: describeValue(approval.args[targetKey]) })
+
+  for (const [key, value] of Object.entries(approval.args)) {
+    if (key === targetKey) continue
+    rows.push({ label: ARG_LABELS[key] ?? humanizeToolName(key), value: describeValue(value) })
+  }
+
+  return rows
+}
+
+/**
+ * The one-line "here is what you are about to allow", shown above the card.
+ *
+ * Synthesized rather than streamed: `pending_approval` arrives between a
+ * `tool_call` and its `tool_result`, and the model does not emit a single token
+ * until after the tool returns — so at the moment the operator is asked to
+ * decide, the agent has said nothing at all. The design shows a sentence there,
+ * and it has to be built from the call itself.
+ */
+export function describeApprovalIntent(approval: PendingApproval, labels?: ToolLabels): string {
+  const action = toolLabel(approval.name, labels).toLowerCase()
+  const targetKey = TARGET_KEYS.find((key) => key in approval.args)
+  const target = targetKey ? describeValue(approval.args[targetKey]) : null
+
+  return target
+    ? `This runs ${action} on ${target}. Review and approve to proceed.`
+    : `This runs ${action}. Review and approve to proceed.`
+}
+
+export type ApprovalCardProps = {
+  approval: PendingApproval
+  toolLabels?: ToolLabels
+  /** A decision has been sent; the stream has not resumed yet. */
+  pending?: boolean
+  onDecide: (approved: boolean) => void
+}
+
+/**
+ * The inline approval prompt. The stream is paused behind this.
+ *
+ * Rendered in the transcript rather than as a blocking modal, because it is not
+ * always the operator who resolves it: an approval left unanswered for
+ * `agent.approvalTimeoutMs` is auto-rejected server-side and the stream resumes
+ * on its own. The card must be able to disappear because the turn moved on — a
+ * modal that only closes on click would strand the operator on a dead prompt.
+ * Unmounting is driven by the reducer clearing `pendingApproval`.
+ */
+export const ApprovalCard = ({
+  approval,
+  toolLabels,
+  pending = false,
+  onDecide,
+}: ApprovalCardProps): JSX.Element => {
+  const rows = describeApproval(approval, toolLabels)
+
+  return (
+    <section className="mdk-agent-approval" aria-label={AGENT_LABELS.approvalRequired}>
+      <h3 className="mdk-agent-approval__title">{AGENT_LABELS.approvalRequired}</h3>
+
+      <dl className="mdk-agent-approval__details">
+        {rows.map((row) => (
+          <div className="mdk-agent-approval__row" key={row.label}>
+            <dt className="mdk-agent-approval__label">{row.label}</dt>
+            <dd className="mdk-agent-approval__value">{row.value}</dd>
+          </div>
+        ))}
+      </dl>
+
+      <div className="mdk-agent-approval__actions">
+        <Button
+          variant="outline"
+          size="sm"
+          disabled={pending}
+          onClick={() => onDecide(false)}
+        >
+          Reject
+        </Button>
+        <Button
+          variant="primary"
+          size="sm"
+          loading={pending}
+          disabled={pending}
+          onClick={() => onDecide(true)}
+        >
+          Approve
+        </Button>
+      </div>
+    </section>
+  )
+}

package/src/components/assistant-message.tsx

@@ -0,0 +1,140 @@
+import { Loader } from '@tetherto/mdk-react-devkit/primitives'
+import type { JSX } from 'react'
+import { memo, useMemo } from 'react'
+
+import type { ToolLabels } from '../core/tool-label'
+import type { PendingApproval, ToolStep } from '../core/turn'
+import { AGENT_LABELS } from '../branding'
+import { describeAgentError } from '../core/error-text'
+import { parseLeakedToolCall } from '../core/prose'
+import { isSmallTalk } from '../core/small-talk'
+import { ApprovalCard, describeApprovalIntent } from './approval-card'
+import { CollapsibleAnswer } from './collapsible-answer'
+import { LeakedToolCallNotice } from './leaked-tool-call-notice'
+import { NoToolsNote } from './no-tools-note'
+import { ToolChip } from './tool-chip'
+
+export type AssistantMessageProps = {
+  text: string
+  /** The operator message this answers — only read to decide whether it was a fleet question. */
+  question?: string
+  tools?: ToolStep[]
+  /** The `error` the turn ended on. A raw `ERR_*` code is mapped before it is shown. */
+  error?: string | null
+  /** The turn was stopped before it finished, so this is a part of an answer. */
+  interrupted?: boolean
+  /** The turn is still running: render plain text and the thinking indicator. */
+  streaming?: boolean
+  toolLabels?: ToolLabels
+  approval?: PendingApproval | null
+  isDecisionPending?: boolean
+  onDecide?: (approved: boolean) => void
+  /** Offered on a failed turn, so the operator does not retype the question. */
+  onRetry?: VoidFunction
+}
+
+const AssistantMessageView = ({
+  text,
+  question = '',
+  tools = [],
+  error = null,
+  interrupted = false,
+  streaming = false,
+  toolLabels,
+  approval = null,
+  isDecisionPending = false,
+  onDecide,
+  onRetry,
+}: AssistantMessageProps): JSX.Element => {
+  // Only worth checking once the turn has settled — a partial answer can look
+  // like a bare JSON object simply because the rest has not arrived yet.
+  const leaked = useMemo(() => (streaming ? null : parseLeakedToolCall(text)), [streaming, text])
+
+  const hasText = text.trim().length > 0
+  const isThinking = streaming && !hasText && approval === null
+
+  // The chip for the gated step is suppressed while its card is up: the card
+  // already names the action, the device and the command, so the chip would just
+  // restate it directly above.
+  const chips = approval ? tools.filter((step) => step.id !== approval.toolStepId) : tools
+
+  // Stated only once the turn has settled — mid-stream the tools may simply not
+  // have been called *yet*. A leaked call and an errored turn already say their
+  // own thing, so the note would only add noise there. Nor is it said against a
+  // greeting: consulting nothing is the right answer to "hey", and the marker
+  // was appearing on every one of them.
+  const answeredWithoutTools
+    = !streaming
+      && tools.length === 0
+      && hasText
+      && leaked === null
+      && !error
+      && !isSmallTalk(question)
+
+  return (
+    <div className="mdk-agent-message mdk-agent-message--assistant">
+      <p className="mdk-agent-message__role">
+        <span className="mdk-agent-message__dot" aria-hidden="true" />
+        {AGENT_LABELS.name}
+        {answeredWithoutTools ? <NoToolsNote /> : null}
+      </p>
+
+      {chips.length > 0
+        ? (
+            <div className="mdk-agent-message__tools">
+              {chips.map((step) => (
+                <ToolChip key={step.id} step={step} toolLabels={toolLabels} />
+              ))}
+            </div>
+          )
+        : null}
+
+      {approval
+        ? (
+            <p className="mdk-agent-message__intent">
+              {describeApprovalIntent(approval, toolLabels)}
+            </p>
+          )
+        : null}
+
+      {/* `inline`, or the loader's 200px block height strands the dots ~100px below this
+          label with dead space between, and the turn reads as frozen while it is working. */}
+      {isThinking ? <Loader inline size={6} count={3} color="orange" /> : null}
+
+      {hasText && leaked === null ? <CollapsibleAnswer text={text} streaming={streaming} /> : null}
+      {hasText && leaked !== null ? <LeakedToolCallNotice call={leaked} /> : null}
+
+      {approval && onDecide
+        ? (
+            <ApprovalCard
+              approval={approval}
+              toolLabels={toolLabels}
+              pending={isDecisionPending}
+              onDecide={onDecide}
+            />
+          )
+        : null}
+
+      {interrupted && !error
+        ? <p className="mdk-agent-message__note">Stopped early — this is not the whole answer.</p>
+        : null}
+
+      {error
+        ? (
+            <p className="mdk-agent-message__error" role="alert">
+              {describeAgentError(error)}
+              {onRetry
+                ? (
+                    <button type="button" className="mdk-agent-message__retry" onClick={onRetry}>
+                      Try again
+                    </button>
+                  )
+                : null}
+            </p>
+          )
+        : null}
+    </div>
+  )
+}
+
+export const AssistantMessage = memo(AssistantMessageView)

package/src/components/co-pilot-panel.tsx

@@ -0,0 +1,109 @@
+import type { JSX, ReactNode } from 'react'
+import { useCallback, useState } from 'react'
+
+import type { ToolLabels } from '../core/tool-label'
+import type { UseAgentChatResult } from '../hooks/use-agent-chat'
+import type { PanelView } from './panel-header'
+import { AGENT_LABELS } from '../branding'
+import { formatConversationSummary } from '../core/format'
+import { Composer } from './composer'
+import { ConversationList } from './conversation-list'
+import { MessageList } from './message-list'
+import { PANEL_VIEW, PanelHeader } from './panel-header'
+
+export type CoPilotPanelProps = {
+  /** The single hook instance. Both entries own one and pass it down. */
+  chat: UseAgentChatResult
+  title?: string
+  status?: ReactNode
+  toolLabels?: ToolLabels
+  placeholder?: string
+  /** Omitted by the route page, which has nothing to collapse into. */
+  onClose?: VoidFunction | undefined
+  className?: string
+}
+
+/** The panel body, shared by the docked overlay and the full-page route. */
+export const CoPilotPanel = ({
+  chat,
+  title = AGENT_LABELS.name,
+  status,
+  toolLabels,
+  placeholder,
+  onClose,
+  className,
+}: CoPilotPanelProps): JSX.Element => {
+  const [view, setView] = useState<PanelView>(PANEL_VIEW.CHAT)
+
+  const toggleConversations = useCallback(() => {
+    setView((current) => (current === PANEL_VIEW.CHAT ? PANEL_VIEW.CONVERSATIONS : PANEL_VIEW.CHAT))
+  }, [])
+
+  const handleNewConversation = useCallback(() => {
+    chat.newConversation()
+    setView(PANEL_VIEW.CHAT)
+  }, [chat])
+
+  const handleSelectConversation = useCallback(
+    (id: string) => {
+      chat.selectConversation(id)
+      setView(PANEL_VIEW.CHAT)
+    },
+    [chat],
+  )
+
+  const isConversations = view === PANEL_VIEW.CONVERSATIONS
+
+  // The conversations view describes the list rather than the connection — the
+  // host-supplied status is about the agent, which is not what is on screen.
+  const headerStatus = isConversations
+    ? formatConversationSummary(chat.conversations.length, chat.isStreaming)
+    : status
+
+  return (
+    <section className={`mdk-agent-panel${className ? ` ${className}` : ''}`} aria-label={title}>
+      <PanelHeader
+        view={view}
+        title={isConversations ? AGENT_LABELS.conversations : title}
+        status={headerStatus}
+        actionsDisabled={chat.isStreaming}
+        onNewConversation={handleNewConversation}
+        onToggleConversations={toggleConversations}
+        onClose={onClose}
+      />
+
+      {isConversations
+        ? (
+            <ConversationList
+              conversations={chat.conversations}
+              activeId={chat.active?.id ?? null}
+              runningId={chat.isStreaming ? (chat.active?.id ?? null) : null}
+              onSelect={handleSelectConversation}
+              onCreate={handleNewConversation}
+              onDelete={chat.removeConversation}
+            />
+          )
+        : (
+            <>
+              <MessageList
+                messages={chat.messages}
+                live={chat.live}
+                toolLabels={toolLabels}
+                pendingApproval={chat.pendingApproval}
+                isDecisionPending={chat.isDecisionPending}
+                onDecide={chat.decide}
+                onRetry={chat.retry}
+              />
+              <Composer
+                disabled={!chat.canSend}
+                isStreaming={chat.isStreaming}
+                placeholder={placeholder}
+                focusKey={chat.active?.id ?? null}
+                onSend={chat.send}
+                onStop={chat.abort}
+              />
+            </>
+          )}
+    </section>
+  )
+}

package/src/components/code-block.tsx

@@ -0,0 +1,63 @@
+import type { ComponentPropsWithoutRef, JSX } from 'react'
+import type { ExtraProps } from 'react-markdown'
+import { useEffect, useRef, useState } from 'react'
+
+/** How long the button confirms the copy before going back to its label. */
+const COPIED_FEEDBACK_MS = 1500
+
+export type CodeBlockProps = ComponentPropsWithoutRef<'pre'> & ExtraProps
+
+/**
+ * A fenced code block, with a copy button.
+ *
+ * What the panel puts in fences is mostly shell commands and JSON an operator
+ * wants to run or paste somewhere, so copying it is the common next action.
+ *
+ * The text is read off the rendered node rather than reassembled from the hast
+ * tree: the highlighter has already replaced the block's children with token
+ * spans, and `textContent` is exactly the source again. The button is absent
+ * where the Clipboard API is — it needs a secure context, and a gateway on a site
+ * LAN is served over plain http.
+ */
+export const CodeBlock = ({ children, node, ...rest }: CodeBlockProps): JSX.Element => {
+  const codeRef = useRef<HTMLPreElement>(null)
+  const [copied, setCopied] = useState(false)
+
+  const canCopy = typeof navigator?.clipboard?.writeText === 'function'
+
+  useEffect(() => {
+    if (!copied) return
+    const timer = setTimeout(() => setCopied(false), COPIED_FEEDBACK_MS)
+    return () => clearTimeout(timer)
+  }, [copied])
+
+  const copy = () => {
+    const text = codeRef.current?.textContent ?? ''
+    if (!text) return
+    void navigator.clipboard.writeText(text).then(
+      () => setCopied(true),
+      () => {
+        // Denied by permissions policy, or the document is not focused. Nothing
+        // to report — the code is still on screen and selectable.
+      },
+    )
+  }
+
+  return (
+    <div className="mdk-agent-code">
+      <pre ref={codeRef} {...rest}>{children}</pre>
+      {canCopy
+        ? (
+            <button
+              type="button"
+              className="mdk-agent-code__copy"
+              aria-label={copied ? 'Copied' : 'Copy code'}
+              onClick={copy}
+            >
+              {copied ? 'Copied' : 'Copy'}
+            </button>
+          )
+        : null}
+    </div>
+  )
+}

package/src/components/collapsible-answer.tsx

@@ -0,0 +1,55 @@
+import type { JSX } from 'react'
+import { memo, useState } from 'react'
+
+import { clipToBoundary } from '../core/markdown'
+import { MarkdownText } from './markdown-text'
+
+/**
+ * Where an answer stops being readable in a docked panel.
+ *
+ * The panel is 420×640, so a few thousand characters is already several screens
+ * of scrolling between one question and the next.
+ */
+export const COLLAPSE_ABOVE_CHARS = 3000
+/** How much of it is shown collapsed. */
+export const COLLAPSED_CHARS = 1500
+
+export type CollapsibleAnswerProps = {
+  text: string
+  /** While the turn streams the answer is never collapsed: growth has to stay visible. */
+  streaming?: boolean
+}
+
+/**
+ * An answer, collapsed behind a toggle when it is long enough to bury the rest of
+ * the transcript.
+ *
+ * Only ever collapsed once the turn has settled — mid-stream, hiding the tail
+ * would hide the very thing the operator is watching.
+ */
+const CollapsibleAnswerView = ({ text, streaming = false }: CollapsibleAnswerProps): JSX.Element => {
+  const [expanded, setExpanded] = useState(false)
+
+  const isLong = !streaming && text.length > COLLAPSE_ABOVE_CHARS
+  const shown = isLong && !expanded ? clipToBoundary(text, COLLAPSED_CHARS) : text
+
+  return (
+    <>
+      <MarkdownText text={shown} streaming={streaming} />
+      {isLong
+        ? (
+            <button
+              type="button"
+              className="mdk-agent-markdown__more"
+              aria-expanded={expanded}
+              onClick={() => setExpanded(!expanded)}
+            >
+              {expanded ? 'Show less' : 'Show full answer'}
+            </button>
+          )
+        : null}
+    </>
+  )
+}
+
+export const CollapsibleAnswer = memo(CollapsibleAnswerView)