@tetherto/mdk-ui-agent 0.0.0 → 0.12.1

package/src/core/turn.ts

@@ -0,0 +1,299 @@
+/**
+ * Folds the event stream of one turn into a render model.
+ *
+ * Pure and synchronous: no fetch, no React, no timers. Every branch here is
+ * driven by a contract invariant, so the fixtures in `src/test-utils/fixtures`
+ * exercise it directly.
+ */
+
+import type { ToolArgs, WireEvent } from './events'
+import { EVENT } from './events'
+
+export const TURN_STATUS = {
+  IDLE: 'idle',
+  STREAMING: 'streaming',
+  AWAITING_APPROVAL: 'awaiting-approval',
+  COMPLETE: 'complete',
+  ERROR: 'error',
+} as const
+
+export type TurnStatus = (typeof TURN_STATUS)[keyof typeof TURN_STATUS]
+
+export const TOOL_STATUS = {
+  RUNNING: 'running',
+  AWAITING_APPROVAL: 'awaiting-approval',
+  OK: 'ok',
+  /** Refused — by the operator, or by the approval timing out. Not an error. */
+  REJECTED: 'rejected',
+  ERROR: 'error',
+  /**
+   * The turn ended before the tool reported back — an `error` event, a lost
+   * connection, or the operator stopping the turn. Whether the tool ran is
+   * genuinely unknown, which is why it is neither `ok` nor `error`.
+   */
+  INTERRUPTED: 'interrupted',
+} as const
+
+export type ToolStatus = (typeof TOOL_STATUS)[keyof typeof TOOL_STATUS]
+
+/**
+ * How a refused write comes back.
+ *
+ * The producer answers a declined approval with an ordinary `tool_result` and
+ * **no `isError`** (`backend/core/agent/src/loop.js`), so without this a
+ * rejected write renders with the same green tick as one that ran — telling the
+ * operator their refusal succeeded in doing the thing they refused.
+ *
+ * It is a bare string literal over there, not an exported constant, so this is
+ * matched on a prefix and pinned by `turn.contract.test.ts`.
+ */
+const REJECTED_RESULT_PREFIX = '(rejected by operator'
+
+export function isRejectionResult(text: string): boolean {
+  return text.startsWith(REJECTED_RESULT_PREFIX)
+}
+
+export type ToolStep = {
+  id: string
+  name: string
+  args: ToolArgs
+  status: ToolStatus
+  /** The tool's answer, once it has one. */
+  text?: string
+  /** The call itself failed. */
+  isError?: boolean
+  /** The tool answered, but the answer broke its verb's contract. Implies `isError`. */
+  contractViolation?: string
+  startedAt: number
+  endedAt?: number
+  /** What renders as `· 0.4s` on the chip. */
+  durationMs?: number
+}
+
+export type PendingApproval = {
+  approvalId: string
+  name: string
+  args: ToolArgs
+  /** The `ToolStep` this approval gates. */
+  toolStepId: string
+  at: number
+}
+
+export type AgentTurnState = {
+  turnId: string | null
+  tools: ToolStep[]
+  text: string
+  status: TurnStatus
+  error: string | null
+  pendingApproval: PendingApproval | null
+  usage: Record<string, unknown> | null
+}
+
+export function createTurnState(): AgentTurnState {
+  return {
+    turnId: null,
+    tools: [],
+    text: '',
+    status: TURN_STATUS.IDLE,
+    error: null,
+    pendingApproval: null,
+    usage: null,
+  }
+}
+
+export function isTurnSettled(state: AgentTurnState): boolean {
+  return state.status === TURN_STATUS.COMPLETE || state.status === TURN_STATUS.ERROR
+}
+
+function isOpen(step: ToolStep): boolean {
+  return step.status === TOOL_STATUS.RUNNING || step.status === TOOL_STATUS.AWAITING_APPROVAL
+}
+
+/**
+ * The OLDEST step of that name still waiting on its `tool_result`.
+ *
+ * The wire carries no id linking a result to its call, so attribution is by call
+ * order: the producer runs tools one at a time and emits each result in the order
+ * the calls were made, so the first unanswered call of a name is the one this
+ * result belongs to. Matching the newest instead crossed durations and outputs
+ * over as soon as a turn called the same tool twice.
+ */
+function findOpenStep(tools: ToolStep[], name: string): ToolStep | undefined {
+  return tools.find((step) => isOpen(step) && step.name === name)
+}
+
+function replaceStep(tools: ToolStep[], id: string, next: ToolStep): ToolStep[] {
+  return tools.map((step) => (step.id === id ? next : step))
+}
+
+/**
+ * Closes every step still waiting on a result.
+ *
+ * A turn can end while a call is outstanding — an `error` event, a dropped
+ * socket, the operator pressing stop — and a step left `running` renders as a
+ * spinner that never resolves, which then gets persisted into the transcript and
+ * read back as a turn still in flight.
+ */
+function settleOpenSteps(tools: ToolStep[], at: number): ToolStep[] {
+  return tools.map((step) =>
+    isOpen(step) ? { ...step, status: TOOL_STATUS.INTERRUPTED, endedAt: at } : step,
+  )
+}
+
+/**
+ * Ends a turn from outside the event stream: a transport failure, an idle
+ * connection, or an unmount. `reduceTurn` handles the producer's own `error`
+ * event; this is the same closing-down for the cases that never reach it.
+ */
+export function failTurn(state: AgentTurnState, error: string, at = Date.now()): AgentTurnState {
+  return {
+    ...state,
+    status: TURN_STATUS.ERROR,
+    error,
+    pendingApproval: null,
+    tools: settleOpenSteps(state.tools, at),
+  }
+}
+
+/**
+ * Ends a turn the operator stopped. Not an error — they meant it — so whatever
+ * streamed is kept and no error is recorded, but an outstanding call is still
+ * closed: it did not report back and now never will.
+ */
+export function abortTurn(state: AgentTurnState, at = Date.now()): AgentTurnState {
+  return {
+    ...state,
+    pendingApproval: null,
+    tools: settleOpenSteps(state.tools, at),
+  }
+}
+
+/**
+ * Applies one event. Returns a new state; never mutates the one passed in.
+ *
+ * Unknown event types fall through unchanged (invariant 5) — the caller has
+ * usually filtered them already, but this must not throw either way.
+ */
+export function reduceTurn(state: AgentTurnState, event: WireEvent): AgentTurnState {
+  const turnId = state.turnId ?? event.turnId
+
+  switch (event.type) {
+    case EVENT.TOKEN:
+      return {
+        ...state,
+        turnId,
+        text: state.text + event.text,
+        status: TURN_STATUS.STREAMING,
+      }
+
+    case EVENT.TOOL_CALL:
+      return {
+        ...state,
+        turnId,
+        status: TURN_STATUS.STREAMING,
+        tools: [
+          ...state.tools,
+          {
+            id: `${event.turnId}:${event.seq}`,
+            name: event.name,
+            args: event.args,
+            status: TOOL_STATUS.RUNNING,
+            startedAt: event.ts,
+          },
+        ],
+      }
+
+    case EVENT.PENDING_APPROVAL: {
+      // Only ever emitted between a `tool_call` and its `tool_result`
+      // (invariant 3), so the gated step is the open one with the same name.
+      const step = findOpenStep(state.tools, event.name)
+      if (!step || !event.approvalId) return { ...state, turnId }
+      return {
+        ...state,
+        turnId,
+        status: TURN_STATUS.AWAITING_APPROVAL,
+        tools: replaceStep(state.tools, step.id, {
+          ...step,
+          status: TOOL_STATUS.AWAITING_APPROVAL,
+        }),
+        pendingApproval: {
+          approvalId: event.approvalId,
+          name: event.name,
+          args: event.args,
+          toolStepId: step.id,
+          at: event.ts,
+        },
+      }
+    }
+
+    case EVENT.TOOL_RESULT: {
+      const step = findOpenStep(state.tools, event.name)
+      if (!step) return { ...state, turnId }
+
+      // A refusal only reaches us as this text — the decision is sent
+      // out-of-band, and an approval that timed out server-side was never
+      // decided here at all.
+      const wasRefused
+        = step.status === TOOL_STATUS.AWAITING_APPROVAL && isRejectionResult(event.text)
+
+      const settled: ToolStep = {
+        ...step,
+        status: event.isError
+          ? TOOL_STATUS.ERROR
+          : wasRefused
+            ? TOOL_STATUS.REJECTED
+            : TOOL_STATUS.OK,
+        text: event.text,
+        endedAt: event.ts,
+        // The operator's own deliberation is not the tool's runtime. On a gated call the
+        // producer says how long the prompt was up, and it comes back off the clock.
+        durationMs: Math.max(0, event.ts - step.startedAt - (event.approvalWaitMs ?? 0)),
+        ...(event.isError === undefined ? {} : { isError: event.isError }),
+        ...(event.contractViolation === undefined
+          ? {}
+          : { contractViolation: event.contractViolation }),
+      }
+
+      // Clears the approval whether the operator answered, the approval timed
+      // out server-side, or the turn was declined — in every case the stream has
+      // moved on and the prompt must stop being shown.
+      const stillPending
+        = state.pendingApproval && state.pendingApproval.toolStepId !== step.id
+          ? state.pendingApproval
+          : null
+
+      return {
+        ...state,
+        turnId,
+        tools: replaceStep(state.tools, step.id, settled),
+        pendingApproval: stillPending,
+        status: stillPending ? TURN_STATUS.AWAITING_APPROVAL : TURN_STATUS.STREAMING,
+      }
+    }
+
+    case EVENT.ERROR:
+      return {
+        ...state,
+        turnId,
+        status: TURN_STATUS.ERROR,
+        error: event.error,
+        pendingApproval: null,
+        tools: settleOpenSteps(state.tools, event.ts),
+      }
+
+    case EVENT.DONE:
+      return {
+        ...state,
+        turnId,
+        status: TURN_STATUS.COMPLETE,
+        pendingApproval: null,
+        // `done` may carry the whole answer. Only used when nothing streamed,
+        // otherwise it would duplicate the text already accumulated.
+        text: state.text === '' && event.text ? event.text : state.text,
+        usage: event.usage ?? state.usage,
+      }
+
+    default:
+      return state
+  }
+}

package/src/core/uuid.ts

@@ -0,0 +1,59 @@
+/**
+ * Ids for conversations and messages.
+ *
+ * `crypto.randomUUID` is defined only in a secure context, and a gateway on a
+ * site LAN is routinely reached over plain http — the UI is served from the
+ * gateway's own `staticRootPath`, so `http://10.0.0.4:3000` is an ordinary
+ * deployment rather than an edge case. There `randomUUID` is undefined, and
+ * calling it would throw on conversation creation and on every send, i.e. the
+ * panel would be dead on arrival. `getRandomValues` is available in insecure
+ * contexts, so the v4 shape is assembled from it instead.
+ */
+
+/** Version and variant bits, per RFC 4122 §4.4. */
+const VERSION_BYTE = 6
+const VARIANT_BYTE = 8
+
+function hex(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+function uuidFromBytes(bytes: Uint8Array): string {
+  const stamped = Uint8Array.from(bytes)
+  stamped[VERSION_BYTE] = ((stamped[VERSION_BYTE] ?? 0) & 0x0F) | 0x40
+  stamped[VARIANT_BYTE] = ((stamped[VARIANT_BYTE] ?? 0) & 0x3F) | 0x80
+
+  const digits = hex(stamped)
+  return [
+    digits.slice(0, 8),
+    digits.slice(8, 12),
+    digits.slice(12, 16),
+    digits.slice(16, 20),
+    digits.slice(20, 32),
+  ].join('-')
+}
+
+/**
+ * A v4 UUID where the platform offers one, and a v4-shaped id built from
+ * `getRandomValues` where it does not.
+ *
+ * These ids never leave the browser — they key conversations and messages in
+ * localStorage and React lists — so the only requirement is that two of them
+ * never collide within one browser.
+ */
+export function uuid(): string {
+  const source = globalThis.crypto as Crypto | undefined
+
+  if (typeof source?.randomUUID === 'function') return source.randomUUID()
+  if (typeof source?.getRandomValues === 'function') {
+    return uuidFromBytes(source.getRandomValues(new Uint8Array(16)))
+  }
+
+  // No WebCrypto at all: a very old browser, or a stripped non-browser global.
+  // Uniqueness within one tab is all these ids are asked for.
+  const bytes = new Uint8Array(16)
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Math.floor(Math.random() * 256)
+  }
+  return uuidFromBytes(bytes)
+}

package/src/entries/chat-page.tsx

@@ -0,0 +1,56 @@
+import type { JSX, ReactNode } from 'react'
+import { Suspense } from 'react'
+
+import type { ToolLabels } from '../core/tool-label'
+import type { UseAgentChatOptions } from '../hooks/use-agent-chat'
+import { useAgentChat } from '../hooks/use-agent-chat'
+import { LazyCoPilotPanel } from './lazy-panel'
+
+export type ChatUIEntryProps = UseAgentChatOptions & {
+  title?: string
+  status?: ReactNode
+  toolLabels?: ToolLabels
+  placeholder?: string
+  className?: string
+}
+
+/**
+ * The same conversation as {@link CoPilot}, rendered as a full-height page
+ * instead of a docked overlay.
+ *
+ * Zero required props and a default export, so it drops straight into the
+ * shell's lazy route registry:
+ *
+ * ```ts
+ * { path: '/chat', label: 'Co-pilot', page: () => import('@tetherto/mdk-ui-agent/chat-page') }
+ * ```
+ *
+ * The panel is loaded through the shared lazy boundary rather than imported
+ * directly — a static edge here would pull the transcript and its markdown
+ * renderer into the root barrel, undoing the split for `CoPilot` as well.
+ */
+export const ChatUIEntry = ({
+  title,
+  status,
+  toolLabels,
+  placeholder,
+  className,
+  ...chatOptions
+}: ChatUIEntryProps): JSX.Element => {
+  const chat = useAgentChat(chatOptions)
+
+  return (
+    <Suspense fallback={<div className="mdk-agent-panel mdk-agent-panel--page" />}>
+      <LazyCoPilotPanel
+        chat={chat}
+        title={title}
+        status={status}
+        toolLabels={toolLabels}
+        placeholder={placeholder}
+        className={`mdk-agent-panel--page${className ? ` ${className}` : ''}`}
+      />
+    </Suspense>
+  )
+}
+
+export default ChatUIEntry

package/src/entries/co-pilot.tsx

@@ -0,0 +1,84 @@
+import type { JSX, ReactNode } from 'react'
+import { Suspense, useCallback, useState } from 'react'
+
+import type { ToolLabels } from '../core/tool-label'
+import type { UseAgentChatOptions } from '../hooks/use-agent-chat'
+import { LauncherFab } from '../components/launcher-fab'
+import { useAgentChat } from '../hooks/use-agent-chat'
+import { LazyCoPilotPanel } from './lazy-panel'
+
+export const COPILOT_POSITION = {
+  BOTTOM_RIGHT: 'bottom-right',
+  BOTTOM_LEFT: 'bottom-left',
+} as const
+
+export type CoPilotPosition = (typeof COPILOT_POSITION)[keyof typeof COPILOT_POSITION]
+
+export type CoPilotProps = UseAgentChatOptions & {
+  title?: string
+  /** The line under the title, e.g. `Local model · 6 tools`. */
+  status?: ReactNode
+  /** Human labels for tool chips, keyed by the MCP tool name. */
+  toolLabels?: ToolLabels
+  placeholder?: string
+  defaultOpen?: boolean
+  position?: CoPilotPosition
+  className?: string
+}
+
+/**
+ * The Co-pilot as a docked overlay: a launcher in the corner that opens the
+ * panel over whatever page is showing.
+ *
+ * Mount it once, in the app root, next to the router outlet:
+ *
+ * ```tsx
+ * import { CoPilot } from '@tetherto/mdk-ui-agent'
+ *
+ * <div className="app-root">
+ *   …
+ *   <CoPilot />
+ * </div>
+ * ```
+ *
+ * Everything is optional. Inside an `MdkProvider` it picks up the gateway base
+ * URL and the bearer token from the provider's auth seam; outside one it falls
+ * back to relative URLs and no token, which is what a gateway running without an
+ * auth plugin serves anyway.
+ */
+export const CoPilot = ({
+  title,
+  status,
+  toolLabels,
+  placeholder,
+  defaultOpen = false,
+  position = COPILOT_POSITION.BOTTOM_RIGHT,
+  className,
+  ...chatOptions
+}: CoPilotProps): JSX.Element => {
+  const [open, setOpen] = useState(defaultOpen)
+  const chat = useAgentChat(chatOptions)
+
+  const close = useCallback(() => setOpen(false), [])
+  const openPanel = useCallback(() => setOpen(true), [])
+
+  return (
+    <div className={`mdk-agent-root mdk-agent-root--${position}${className ? ` ${className}` : ''}`}>
+      {open
+        ? (
+            <Suspense fallback={<div className="mdk-agent-panel mdk-agent-panel--docked" />}>
+              <LazyCoPilotPanel
+                chat={chat}
+                title={title}
+                status={status}
+                toolLabels={toolLabels}
+                placeholder={placeholder}
+                onClose={close}
+                className="mdk-agent-panel--docked"
+              />
+            </Suspense>
+          )
+        : <LauncherFab onClick={openPanel} />}
+    </div>
+  )
+}

package/src/entries/lazy-panel.tsx

@@ -0,0 +1,19 @@
+import { lazy } from 'react'
+
+/**
+ * The panel, split off from whatever mounts it.
+ *
+ * Both entries load it this way, and nothing in the package's root barrel may
+ * import `co-pilot-panel` statically — one static edge anywhere in the graph
+ * collapses the split back into the caller's main chunk, which bundlers report
+ * as an ineffective dynamic import. That is why `CoPilotPanel` is reachable only
+ * from the `./panel` subpath and not from the root export.
+ *
+ * What sits behind the boundary is the transcript: the markdown renderer and the
+ * syntax highlighter. Eagerly bundled, they made the generated shell's main
+ * chunk 80% larger before anyone had opened the panel.
+ */
+export const LazyCoPilotPanel = lazy(async () => {
+  const module = await import('../components/co-pilot-panel')
+  return { default: module.CoPilotPanel }
+})

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export type { UseAgentChatOptions, UseAgentChatResult } from './use-agent-chat'
+export { useAgentChat } from './use-agent-chat'
+
+export type { AgentConfigOptions } from './use-agent-config'
+export { useAgentConfig } from './use-agent-config'
+
+export type { UseConversationsResult } from './use-conversations'
+export { useConversations } from './use-conversations'