@tetherto/mdk-ui-agent 0.0.0 → 0.12.1

package/src/core/conversation-store.ts

@@ -0,0 +1,342 @@
+/**
+ * Conversation history, persisted client-side.
+ *
+ * The gateway keeps sessions in an in-memory `Map` per process — no titles, no
+ * timestamps, no transcripts, and nothing survives a restart — and exposes no
+ * route to list them. So the Conversations view is backed from here instead.
+ *
+ * A stored `sessionId` is therefore a weak reference: it 404s after a gateway
+ * restart or once the agent's own 30-minute session TTL lapses. That is expected,
+ * not an error — the transcript still reads back, and the next message mints a
+ * fresh session (see `useAgentChat`).
+ */
+
+import { createStore } from 'zustand/vanilla'
+import type { StoreApi } from 'zustand/vanilla'
+
+import type { ToolStep } from './turn'
+import { uuid } from './uuid'
+
+export const CONVERSATION_STORAGE_KEY = 'mdk-ui-agent:conversations:v1'
+
+/** Keeps localStorage bounded. The oldest conversations fall off the end. */
+export const MAX_CONVERSATIONS = 50
+/** Mirrors the agent's own per-session ceiling in `backend/core/agent/src/session-store.js`. */
+export const MAX_MESSAGES_PER_CONVERSATION = 200
+/**
+ * How much of a tool result is kept in storage.
+ *
+ * A `list_devices` result is the whole fleet serialized, and it is written again on
+ * every subsequent change. The full text stays in memory for the session — this is
+ * only what survives a reload, where the chip's tooltip is a convenience and the
+ * quota is not. Mirrors `HISTORY_RESULT_CHARS` in the producer's own transcript.
+ */
+export const MAX_PERSISTED_TOOL_TEXT_CHARS = 400
+
+export const MESSAGE_ROLE = {
+  USER: 'user',
+  ASSISTANT: 'assistant',
+  /** Not from the model: something the panel itself has to tell the operator. */
+  SYSTEM: 'system',
+} as const
+
+export type MessageRole = (typeof MESSAGE_ROLE)[keyof typeof MESSAGE_ROLE]
+
+export type ChatMessage = {
+  id: string
+  role: MessageRole
+  text: string
+  at: number
+  /** Assistant only: the tool chips for this turn, in call order. */
+  tools?: ToolStep[]
+  /** Assistant only: set when the turn ended on an `error` event. Raw `ERR_*` codes included. */
+  error?: string | null
+  /**
+   * Assistant only: the turn was stopped before it finished — by the operator, or
+   * by the panel unmounting. Whatever streamed is kept, but it is not the whole
+   * answer and must not read back as one.
+   */
+  interrupted?: boolean
+}
+
+export type Conversation = {
+  id: string
+  title: string
+  /** Null until the first turn creates one, or after a stale one is discarded. */
+  sessionId: string | null
+  messages: ChatMessage[]
+  createdAt: number
+  updatedAt: number
+}
+
+export type ConversationState = {
+  conversations: Conversation[]
+  activeId: string | null
+}
+
+export type ConversationActions = {
+  create: (id?: string, at?: number) => string
+  select: (id: string) => void
+  remove: (id: string) => void
+  setSessionId: (id: string, sessionId: string | null) => void
+  appendMessage: (id: string, message: ChatMessage) => void
+  updateMessage: (id: string, messageId: string, patch: Partial<ChatMessage>) => void
+  reset: () => void
+}
+
+export type ConversationStore = ConversationState & ConversationActions
+
+export type ConversationStorage = Pick<Storage, 'getItem' | 'setItem'>
+
+export type ConversationStoreOptions = {
+  storageKey?: string
+  /** Pass `null` to disable persistence entirely (tests, SSR). */
+  storage?: ConversationStorage | null
+}
+
+const initialState: ConversationState = { conversations: [], activeId: null }
+
+/**
+ * `localStorage` throws on access in some privacy modes and does not exist
+ * outside the browser, so it is probed rather than assumed.
+ */
+function defaultStorage(): ConversationStorage | null {
+  try {
+    return globalThis.localStorage ?? null
+  } catch {
+    return null
+  }
+}
+
+/** First line of the first user message, which is what the design lists. */
+export function deriveTitle(text: string, max = 48): string {
+  const line = text.trim().split('\n')[0]?.trim() ?? ''
+  if (line.length === 0) return 'New conversation'
+  return line.length <= max ? line : `${line.slice(0, max - 1).trimEnd()}…`
+}
+
+export function newConversation(id: string, at: number): Conversation {
+  return { id, title: 'New conversation', sessionId: null, messages: [], createdAt: at, updatedAt: at }
+}
+
+function isConversation(value: unknown): value is Conversation {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as Partial<Conversation>
+  return typeof candidate.id === 'string' && Array.isArray(candidate.messages)
+}
+
+/**
+ * Anything unreadable is discarded rather than repaired: the stored shape can
+ * predate a release, and losing local history is a far better failure than
+ * booting the panel into a broken state.
+ */
+function readPersisted(storage: ConversationStorage | null, key: string): ConversationState {
+  if (!storage) return initialState
+  try {
+    const raw = storage.getItem(key)
+    if (!raw) return initialState
+    const parsed = JSON.parse(raw) as Partial<ConversationState>
+    const conversations = Array.isArray(parsed.conversations)
+      ? parsed.conversations.filter(isConversation)
+      : []
+    const activeId
+      = typeof parsed.activeId === 'string'
+        && conversations.some((conversation) => conversation.id === parsed.activeId)
+        ? parsed.activeId
+        : null
+    return { conversations, activeId }
+  } catch {
+    return initialState
+  }
+}
+
+/** Keeps a full fleet dump out of every write. The in-memory copy is untouched. */
+function trimForStorage(conversation: Conversation): Conversation {
+  if (!conversation.messages.some((message) => message.tools?.length)) return conversation
+
+  return {
+    ...conversation,
+    messages: conversation.messages.map((message) =>
+      message.tools?.length
+        ? {
+            ...message,
+            tools: message.tools.map((step) =>
+              step.text === undefined || step.text.length <= MAX_PERSISTED_TOOL_TEXT_CHARS
+                ? step
+                : { ...step, text: `${step.text.slice(0, MAX_PERSISTED_TOOL_TEXT_CHARS)}…` },
+            ),
+          }
+        : message,
+    ),
+  }
+}
+
+function serialize(state: ConversationState): string {
+  return JSON.stringify({
+    conversations: state.conversations.map(trimForStorage),
+    activeId: state.activeId,
+  })
+}
+
+function writePersisted(storage: ConversationStorage | null, key: string, payload: string): void {
+  if (!storage) return
+  try {
+    storage.setItem(key, payload)
+  } catch {
+    // Quota exceeded or storage disabled mid-session. History is a convenience,
+    // never a correctness requirement, so the live conversation continues.
+  }
+}
+
+function touch(conversation: Conversation, at: number): Conversation {
+  return { ...conversation, updatedAt: at }
+}
+
+/** Newest first, capped — the order the Conversations view renders. */
+function sortAndCap(conversations: Conversation[]): Conversation[] {
+  return [...conversations].sort((a, b) => b.updatedAt - a.updatedAt).slice(0, MAX_CONVERSATIONS)
+}
+
+/**
+ * Reconciles this tab's conversations with what another tab has just written.
+ *
+ * Union by id, newer `updatedAt` wins. Without it the last tab to act overwrites
+ * the other's turns with its own staler snapshot — and since the gateway keeps no
+ * history, that is permanent loss rather than a cache miss.
+ *
+ * The trade-off is deliberate: a conversation deleted in one tab can come back
+ * from the other tab's copy, because "absent" and "never seen" are the same thing
+ * in a union. Resurrecting a transcript is the recoverable direction; losing one
+ * is not.
+ */
+export function mergeConversations(mine: Conversation[], theirs: Conversation[]): Conversation[] {
+  const byId = new Map(mine.map((conversation) => [conversation.id, conversation]))
+
+  for (const other of theirs) {
+    const own = byId.get(other.id)
+    if (!own || other.updatedAt > own.updatedAt) byId.set(other.id, other)
+  }
+
+  return sortAndCap([...byId.values()])
+}
+
+/**
+ * Factory for an isolated conversation store. Tests and SSR should use this;
+ * runtime code binds to the singleton {@link conversationStore}.
+ */
+export function createConversationStore(
+  options: ConversationStoreOptions = {},
+): StoreApi<ConversationStore> {
+  const key = options.storageKey ?? CONVERSATION_STORAGE_KEY
+  const storage = options.storage === undefined ? defaultStorage() : options.storage
+
+  const store = createStore<ConversationStore>((set, get) => ({
+    ...readPersisted(storage, key),
+
+    create: (id, at) => {
+      const conversationId = id ?? uuid()
+      const createdAt = at ?? Date.now()
+      set((state) => ({
+        conversations: sortAndCap([newConversation(conversationId, createdAt), ...state.conversations]),
+        activeId: conversationId,
+      }))
+      return conversationId
+    },
+
+    select: (id) => {
+      if (!get().conversations.some((conversation) => conversation.id === id)) return
+      set({ activeId: id })
+    },
+
+    remove: (id) => {
+      set((state) => {
+        const conversations = state.conversations.filter((conversation) => conversation.id !== id)
+        return {
+          conversations,
+          activeId: state.activeId === id ? (conversations[0]?.id ?? null) : state.activeId,
+        }
+      })
+    },
+
+    setSessionId: (id, sessionId) => {
+      set((state) => ({
+        conversations: state.conversations.map((conversation) =>
+          conversation.id === id ? { ...conversation, sessionId } : conversation,
+        ),
+      }))
+    },
+
+    appendMessage: (id, message) => {
+      set((state) => ({
+        conversations: sortAndCap(
+          state.conversations.map((conversation) => {
+            if (conversation.id !== id) return conversation
+            const messages = [...conversation.messages, message].slice(-MAX_MESSAGES_PER_CONVERSATION)
+            const title
+              = conversation.messages.length === 0 && message.role === MESSAGE_ROLE.USER
+                ? deriveTitle(message.text)
+                : conversation.title
+            return touch({ ...conversation, messages, title }, message.at)
+          }),
+        ),
+      }))
+    },
+
+    updateMessage: (id, messageId, patch) => {
+      set((state) => ({
+        conversations: state.conversations.map((conversation) => {
+          if (conversation.id !== id) return conversation
+          return {
+            ...conversation,
+            messages: conversation.messages.map((message) =>
+              message.id === messageId ? { ...message, ...patch } : message,
+            ),
+          }
+        }),
+      }))
+    },
+
+    reset: () => set({ ...initialState }),
+  }))
+
+  // The last payload written or read, so an unchanged state is not written again —
+  // and, with the cross-tab listener below, so two tabs cannot ping-pong identical
+  // writes at each other forever.
+  let persisted = serialize(store.getState())
+
+  store.subscribe((state) => {
+    const payload = serialize(state)
+    if (payload === persisted) return
+    persisted = payload
+    writePersisted(storage, key, payload)
+  })
+
+  /**
+   * Another tab wrote the same key: merge its conversations in rather than letting
+   * whichever tab acts last overwrite the other.
+   *
+   * Only wired up for real `localStorage`, because the `storage` event describes
+   * nothing else — an injected storage (tests, SSR) has no cross-tab notion at all.
+   */
+  if (storage && storage === globalThis.localStorage && typeof globalThis.addEventListener === 'function') {
+    globalThis.addEventListener('storage', (event) => {
+      if (event.storageArea && event.storageArea !== globalThis.localStorage) return
+      // A null key is `localStorage.clear()`, which drops ours too.
+      if (event.key !== null && event.key !== key) return
+
+      const external = readPersisted(storage, key)
+      const merged = mergeConversations(store.getState().conversations, external.conversations)
+      persisted = serialize({ conversations: merged, activeId: store.getState().activeId })
+      // The other tab's `activeId` is about its own window, so ours is kept.
+      store.setState({ conversations: merged })
+    })
+  }
+
+  return store
+}
+
+/**
+ * Module-level singleton holding every conversation the operator has had in this
+ * browser. React subscribers bind to it through `useConversations`.
+ */
+export const conversationStore = createConversationStore()

package/src/core/error-text.ts

@@ -0,0 +1,36 @@
+/**
+ * Operator-readable text for the failures a turn can end on.
+ *
+ * `reduceTurn` stores whatever the `error` event carried, which is a bare code
+ * like `ERR_AGENT_STREAM_TRUNCATED` — useful in a bug report, meaningless in a
+ * transcript. The raw code stays on the message; this is applied at render time,
+ * so the stored history keeps the diagnosable value.
+ */
+
+import { ERR_STREAM_IDLE, ERR_STREAM_TRUNCATED } from './sse'
+import { AGENT_ERROR } from './transport'
+
+/** Shown when a turn dies before the gateway said anything useful. */
+export const GENERIC_TURN_ERROR = 'The agent could not complete that request.'
+
+const TEXT_FOR_CODE: Record<string, string> = {
+  [AGENT_ERROR.UNAVAILABLE]: 'The agent is not configured on this gateway.',
+  [AGENT_ERROR.TURN_ACTIVE]: 'A turn is already running in this conversation.',
+  [AGENT_ERROR.TEXT_REQUIRED]: 'Type a message first.',
+  [AGENT_ERROR.SESSION_NOT_FOUND]: 'That conversation is no longer open on the gateway.',
+  [ERR_STREAM_TRUNCATED]: 'The connection to the agent ended before the answer finished.',
+  [ERR_STREAM_IDLE]: 'The agent stopped responding, so the connection was assumed lost.',
+}
+
+/**
+ * Maps a code to a sentence, passing anything that is not one through unchanged.
+ *
+ * The producer's codes are all `ERR_*`, so a value in that shape that is not in
+ * the table is a code this release has never seen — it becomes the generic
+ * sentence rather than being shown verbatim. Anything else is already prose.
+ */
+export function describeAgentError(error: string | null | undefined): string | null {
+  if (!error) return null
+  if (TEXT_FOR_CODE[error]) return TEXT_FOR_CODE[error]
+  return error.startsWith('ERR_') ? GENERIC_TURN_ERROR : error
+}

package/src/core/events.ts

@@ -0,0 +1,127 @@
+/**
+ * The agent event contract, redeclared for the browser.
+ *
+ * The producer of record is `backend/core/agent/src/events.js`. That module is
+ * Node-only ESM inside a private package with no `exports` map, and importing it
+ * would pull the model provider and the MCP client into the bundle — so the six
+ * events are restated here instead. `src/core/events.contract.test.ts` reads the
+ * backend file and fails if the two ever drift.
+ */
+
+import isPlainObject from 'lodash/isPlainObject'
+
+/** Bump only alongside the producer's `CONTRACT_VERSION`. */
+export const AGENT_CONTRACT_VERSION = 'v1'
+
+/** Reference these constants, never the raw strings, so a typo is a type error. */
+export const EVENT = {
+  TOKEN: 'token',
+  TOOL_CALL: 'tool_call',
+  TOOL_RESULT: 'tool_result',
+  PENDING_APPROVAL: 'pending_approval',
+  ERROR: 'error',
+  DONE: 'done',
+} as const
+
+export type EventType = (typeof EVENT)[keyof typeof EVENT]
+
+/** `done` and `error` only. Exactly one of them ends a turn, and it is always last. */
+export const TERMINAL_EVENTS = [EVENT.DONE, EVENT.ERROR] as const
+
+export type TerminalEventType = (typeof TERMINAL_EVENTS)[number]
+
+export type ToolArgs = Record<string, unknown>
+
+/** A chunk of the answer, to append to the open bubble. */
+export type TokenEvent = { type: typeof EVENT.TOKEN, text: string }
+
+/** The model chose a tool. Always followed by a `tool_result` with the same `name`. */
+export type ToolCallEvent = { type: typeof EVENT.TOOL_CALL, name: string, args: ToolArgs }
+
+/**
+ * The tool answered. `isError` means the call itself failed; `contractViolation`
+ * — which the producer only ever emits together with `isError` — means the tool
+ * answered but the answer broke its verb's contract.
+ */
+export type ToolResultEvent = {
+  type: typeof EVENT.TOOL_RESULT
+  name: string
+  text: string
+  isError?: boolean
+  contractViolation?: string
+  /**
+   * How long the operator held the turn at the approval prompt, on a gated call only.
+   * Subtract it before showing a duration: the gap between a `tool_call` and its
+   * `tool_result` spans the wait, so a card left open for a minute reads as a minute
+   * of tool.
+   */
+  approvalWaitMs?: number
+}
+
+/** A write tool is waiting on the operator. The stream PAUSES here. */
+export type PendingApprovalEvent = {
+  type: typeof EVENT.PENDING_APPROVAL
+  name: string
+  args: ToolArgs
+}
+
+/** Terminal. Distinct from a decline, which is tokens + `done` with no `tool_call`. */
+export type ErrorEvent = { type: typeof EVENT.ERROR, error: string }
+
+/** Terminal. */
+export type DoneEvent = {
+  type: typeof EVENT.DONE
+  text?: string
+  usage?: Record<string, unknown>
+}
+
+export type AgentEvent =
+  | TokenEvent
+  | ToolCallEvent
+  | ToolResultEvent
+  | PendingApprovalEvent
+  | ErrorEvent
+  | DoneEvent
+
+/**
+ * What actually arrives on the wire: the event's own fields with the gateway's
+ * envelope spread onto the same flat object, not nested under a key.
+ */
+export type WireEvent = AgentEvent & {
+  /** Correlates every event of one turn. */
+  turnId: string
+  /** Monotonic per turn — ordering and dedup. */
+  seq: number
+  /** Stamped by the gateway on every event, despite being optional in the docs. */
+  ts: number
+  /** Present ONLY on `pending_approval`. Echo it back to decide. */
+  approvalId?: string
+}
+
+const EVENT_TYPES = new Set<string>(Object.values(EVENT))
+const TERMINAL_TYPES = new Set<string>(TERMINAL_EVENTS)
+
+export function isTerminal(event: Pick<AgentEvent, 'type'>): boolean {
+  return TERMINAL_TYPES.has(event.type)
+}
+
+/**
+ * Structural check only — enough to decide whether we know how to render it.
+ *
+ * Contract invariant 5: unknown event types MUST be ignored, not thrown on. That
+ * is what lets the producer add event types without a breaking release, so this
+ * returns false rather than raising.
+ */
+export function isAgentEvent(value: unknown): value is AgentEvent {
+  // Every event arrives from `JSON.parse`, so a plain object is exactly the shape
+  // to accept — anything else on the wire is malformed by definition.
+  if (!isPlainObject(value)) return false
+  const type = (value as { type?: unknown }).type
+  return typeof type === 'string' && EVENT_TYPES.has(type)
+}
+
+export function isWireEvent(value: unknown): value is WireEvent {
+  if (!isAgentEvent(value)) return false
+  const { turnId, seq } = value as Partial<WireEvent>
+  return typeof turnId === 'string' && typeof seq === 'number'
+}

package/src/core/format.ts

@@ -0,0 +1,59 @@
+/**
+ * Formatting for the conversation list.
+ *
+ * Deliberately local-time, not the fleet timezone from `timezoneStore`: these
+ * are records of when the operator had a conversation in this browser, not
+ * telemetry timestamps.
+ */
+
+const DAY_MS = 86_400_000
+
+function startOfDay(at: number): number {
+  const date = new Date(at)
+  date.setHours(0, 0, 0, 0)
+  return date.getTime()
+}
+
+/** `Today` / `Yesterday` / `Jul 28`. */
+export function formatDay(at: number, now: number = Date.now()): string {
+  const days = Math.round((startOfDay(now) - startOfDay(at)) / DAY_MS)
+  if (days <= 0) return 'Today'
+  if (days === 1) return 'Yesterday'
+  return new Date(at).toLocaleDateString(undefined, { month: 'short', day: 'numeric' })
+}
+
+/** `14:32`, 24-hour so it lines up in a monospace column. */
+export function formatClock(at: number): string {
+  return new Date(at).toLocaleTimeString(undefined, {
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  })
+}
+
+export function formatMessageCount(count: number): string {
+  return count === 1 ? '1 message' : `${count} messages`
+}
+
+/**
+ * `4 conversations · 1 running` — the header line for the conversations view.
+ *
+ * "Running" counts only what this client is streaming: the gateway holds
+ * sessions in memory per process and exposes no way to list them, so a turn
+ * started in another tab is invisible here.
+ */
+export function formatConversationSummary(count: number, running: boolean): string {
+  const conversations = count === 1 ? '1 conversation' : `${count} conversations`
+  return running ? `${conversations} · 1 running` : conversations
+}
+
+/** `Today · 14:32 · 6 messages` */
+export function formatConversationMeta(
+  updatedAt: number,
+  messageCount: number,
+  now?: number,
+): string {
+  return [formatDay(updatedAt, now), formatClock(updatedAt), formatMessageCount(messageCount)].join(
+    ' · ',
+  )
+}

package/src/core/index.ts

@@ -0,0 +1,115 @@
+/**
+ * The headless half of the package: contract types, SSE transport, the turn
+ * reducer and the conversation store. No React, no DOM.
+ *
+ * Exported as a subpath (`@tetherto/mdk-ui-agent/core`) so a consumer building
+ * its own chat surface can reuse the protocol work without the components.
+ */
+
+export type {
+  ChatMessage,
+  Conversation,
+  ConversationActions,
+  ConversationState,
+  ConversationStorage,
+  ConversationStore,
+  ConversationStoreOptions,
+  MessageRole,
+} from './conversation-store'
+export {
+  CONVERSATION_STORAGE_KEY,
+  conversationStore,
+  createConversationStore,
+  deriveTitle,
+  MAX_CONVERSATIONS,
+  MAX_MESSAGES_PER_CONVERSATION,
+  MAX_PERSISTED_TOOL_TEXT_CHARS,
+  mergeConversations,
+  MESSAGE_ROLE,
+  newConversation,
+} from './conversation-store'
+
+export { describeAgentError, GENERIC_TURN_ERROR } from './error-text'
+
+export type {
+  AgentEvent,
+  DoneEvent,
+  ErrorEvent,
+  EventType,
+  PendingApprovalEvent,
+  TerminalEventType,
+  TokenEvent,
+  ToolArgs,
+  ToolCallEvent,
+  ToolResultEvent,
+  WireEvent,
+} from './events'
+export {
+  AGENT_CONTRACT_VERSION,
+  EVENT,
+  isAgentEvent,
+  isTerminal,
+  isWireEvent,
+  TERMINAL_EVENTS,
+} from './events'
+
+export {
+  formatClock,
+  formatConversationMeta,
+  formatConversationSummary,
+  formatDay,
+  formatMessageCount,
+} from './format'
+
+export { clipToBoundary, unwrapWholeAnswerFence } from './markdown'
+
+export type { LeakedToolCall } from './prose'
+
+export { parseLeakedToolCall } from './prose'
+export { isSmallTalk } from './small-talk'
+
+export type { ReadAgentStreamOptions, ReadFramesOptions } from './sse'
+export {
+  APPROVAL_IDLE_TIMEOUT_MS,
+  ERR_STREAM_IDLE,
+  ERR_STREAM_TRUNCATED,
+  FIRST_EVENT_IDLE_TIMEOUT_MS,
+  parseFrame,
+  readAgentStream,
+  readFrames,
+  STREAM_IDLE_TIMEOUT_MS,
+  StreamIdleError,
+} from './sse'
+
+export type { ToolLabels } from './tool-label'
+export { formatDuration, humanizeToolName, toolLabel } from './tool-label'
+
+export type {
+  AgentErrorCode,
+  AgentTransportOptions,
+  StreamTurnOptions,
+  TokenSource,
+} from './transport'
+export {
+  AGENT_ERROR,
+  AGENT_ROUTE_PREFIX,
+  AgentApiError,
+  createSession,
+  decideApproval,
+  deleteSession,
+  streamTurn,
+} from './transport'
+
+export type { AgentTurnState, PendingApproval, ToolStatus, ToolStep, TurnStatus } from './turn'
+export {
+  abortTurn,
+  createTurnState,
+  failTurn,
+  isRejectionResult,
+  isTurnSettled,
+  reduceTurn,
+  TOOL_STATUS,
+  TURN_STATUS,
+} from './turn'
+
+export { uuid } from './uuid'