@tetherto/mdk-ui-agent 0.0.0 → 0.12.1

package/src/hooks/use-agent-chat.ts

@@ -0,0 +1,387 @@
+/**
+ * The one stateful hook: owns the session, the live turn, and persistence.
+ *
+ * Components below this are presentational — they receive already-shaped props
+ * and render them, per the repo's separation-of-concerns rule.
+ */
+
+import type { StoreApi } from 'zustand/vanilla'
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import type { ChatMessage, Conversation, ConversationStore } from '../core/conversation-store'
+import type { AgentTurnState, PendingApproval } from '../core/turn'
+import type { AgentConfigOptions } from './use-agent-config'
+import { conversationStore as defaultStore, MESSAGE_ROLE } from '../core/conversation-store'
+import { describeAgentError, GENERIC_TURN_ERROR } from '../core/error-text'
+import {
+  AGENT_ERROR,
+  AgentApiError,
+  createSession,
+  decideApproval,
+  deleteSession,
+  streamTurn,
+} from '../core/transport'
+import { abortTurn, createTurnState, failTurn, isTurnSettled, reduceTurn } from '../core/turn'
+import { uuid } from '../core/uuid'
+import { useAgentConfig } from './use-agent-config'
+import { useConversations } from './use-conversations'
+
+/**
+ * Said in the transcript when a turn had to open a new gateway session.
+ *
+ * Sessions live in the gateway's memory, so a restart or the agent's own TTL makes
+ * a stored id a 404 and the next message starts a session with no history. The
+ * transcript above it still reads as one conversation, so without this the operator
+ * asks a follow-up about "that container" and the agent has never heard of it.
+ */
+const SESSION_RESET_NOTICE
+  = 'New session — the agent does not remember the messages above this line.'
+
+function describeError(error: unknown): string {
+  if (error instanceof AgentApiError) return describeAgentError(error.code) ?? error.message
+  return GENERIC_TURN_ERROR
+}
+
+function isAbort(error: unknown): boolean {
+  return error instanceof DOMException && error.name === 'AbortError'
+}
+
+export type UseAgentChatOptions = AgentConfigOptions & {
+  /** Isolated store for tests and the catalog demo; defaults to the singleton. */
+  store?: StoreApi<ConversationStore>
+  /**
+   * The three silences a turn is allowed, all defaulted in `core/sse`: between
+   * events, while an approval is outstanding, and before the first event. Raise
+   * the second if your gateway's `agent.approvalTimeoutMs` is longer than five
+   * minutes, and the third if its model is slower to route than two minutes.
+   */
+  idleTimeoutMs?: number
+  approvalIdleTimeoutMs?: number
+  firstEventIdleTimeoutMs?: number
+}
+
+export type UseAgentChatResult = {
+  conversations: Conversation[]
+  active: Conversation | null
+  /** Persisted transcript of the active conversation. */
+  messages: ChatMessage[]
+  /** The turn currently streaming, rendered after `messages`. Null when idle. */
+  live: AgentTurnState | null
+  isStreaming: boolean
+  pendingApproval: PendingApproval | null
+  /** A decision has been POSTed and the stream has not resumed yet. */
+  isDecisionPending: boolean
+  canSend: boolean
+  send: (text: string) => void
+  decide: (approved: boolean) => void
+  abort: VoidFunction
+  /** Re-sends the last question, for a turn that failed. */
+  retry: VoidFunction
+  newConversation: VoidFunction
+  selectConversation: (id: string) => void
+  removeConversation: (id: string) => void
+}
+
+export function useAgentChat(options: UseAgentChatOptions = {}): UseAgentChatResult {
+  const {
+    store = defaultStore,
+    idleTimeoutMs,
+    approvalIdleTimeoutMs,
+    firstEventIdleTimeoutMs,
+    ...configOptions
+  } = options
+  const config = useAgentConfig(configOptions)
+  const { conversations, active, create, select, remove } = useConversations(store)
+
+  const [live, setLive] = useState<AgentTurnState | null>(null)
+  const [isBusy, setIsBusy] = useState(false)
+  const [decidedApprovalId, setDecidedApprovalId] = useState<string | null>(null)
+
+  // Read inside async callbacks, where the rendered value would be stale.
+  const liveRef = useRef<AgentTurnState | null>(null)
+  const abortRef = useRef<AbortController | null>(null)
+  const busyRef = useRef(false)
+
+  const frameRef = useRef<number | null>(null)
+
+  /**
+   * Records the live turn, and commits it to React at most once per frame.
+   *
+   * One `setState` per SSE event means the whole panel re-renders 30–60 times a
+   * second at token rate, for a transcript whose settled half never changed. The
+   * ref is updated synchronously — callbacks and the next reduce read it — and the
+   * scheduled commit always publishes the latest value, so no event is skipped,
+   * only the intermediate paints. Clearing the turn commits immediately: it is the
+   * end of the turn, not a frame of it.
+   */
+  const publish = useCallback((next: AgentTurnState | null) => {
+    liveRef.current = next
+
+    if (next === null) {
+      if (frameRef.current !== null) cancelAnimationFrame(frameRef.current)
+      frameRef.current = null
+      setLive(null)
+      return
+    }
+
+    if (frameRef.current !== null) return
+    frameRef.current = requestAnimationFrame(() => {
+      frameRef.current = null
+      setLive(liveRef.current)
+    })
+  }, [])
+
+  useEffect(
+    () => () => {
+      if (frameRef.current !== null) cancelAnimationFrame(frameRef.current)
+      abortRef.current?.abort()
+    },
+    [],
+  )
+
+  /**
+   * A stored `sessionId` outlives the session it names — the gateway holds
+   * sessions in memory per process, so a restart or the agent's own TTL makes it
+   * a 404. `force` mints a replacement.
+   */
+  const resolveSessionId = useCallback(
+    async (conversationId: string, force: boolean): Promise<string> => {
+      const conversation = store
+        .getState()
+        .conversations.find((candidate) => candidate.id === conversationId)
+      if (!force && conversation?.sessionId) return conversation.sessionId
+
+      const sessionId = await createSession(config)
+      store.getState().setSessionId(conversationId, sessionId)
+
+      // Only a break if there was something to lose. A conversation whose only
+      // message is the question now being sent has no context to carry over, so
+      // the first session of a conversation is not announced.
+      const hadContext
+        = conversation?.messages.some((message) => message.role === MESSAGE_ROLE.ASSISTANT) ?? false
+      if (hadContext) {
+        store.getState().appendMessage(conversationId, {
+          id: uuid(),
+          role: MESSAGE_ROLE.SYSTEM,
+          text: SESSION_RESET_NOTICE,
+          at: Date.now(),
+        })
+      }
+
+      return sessionId
+    },
+    [config, store],
+  )
+
+  /**
+   * Opens the stream, retrying once against a fresh session if the stored one is
+   * gone. The first `next()` is what performs the fetch — an async generator's
+   * body does not run until then — so the status check happens here, not later
+   * in the consume loop.
+   */
+  const openStream = useCallback(
+    async (conversationId: string, text: string, signal: AbortSignal) => {
+      const start = async (force: boolean) => {
+        const sessionId = await resolveSessionId(conversationId, force)
+        const iterator = streamTurn(sessionId, text, {
+          ...config,
+          ...(idleTimeoutMs === undefined ? {} : { idleTimeoutMs }),
+          ...(approvalIdleTimeoutMs === undefined ? {} : { approvalIdleTimeoutMs }),
+          ...(firstEventIdleTimeoutMs === undefined ? {} : { firstEventIdleTimeoutMs }),
+          signal,
+        })
+        return { iterator, first: await iterator.next() }
+      }
+
+      try {
+        return await start(false)
+      } catch (error) {
+        if (error instanceof AgentApiError && error.is(AGENT_ERROR.SESSION_NOT_FOUND)) {
+          return await start(true)
+        }
+        throw error
+      }
+    },
+    [approvalIdleTimeoutMs, config, firstEventIdleTimeoutMs, idleTimeoutMs, resolveSessionId],
+  )
+
+  const runTurn = useCallback(
+    async (text: string) => {
+      busyRef.current = true
+      setIsBusy(true)
+      setDecidedApprovalId(null)
+
+      const conversationId = store.getState().activeId ?? store.getState().create()
+      store.getState().appendMessage(conversationId, {
+        id: uuid(),
+        role: MESSAGE_ROLE.USER,
+        text,
+        at: Date.now(),
+      })
+
+      const controller = new AbortController()
+      abortRef.current = controller
+
+      let state = createTurnState()
+      publish(state)
+
+      try {
+        const { iterator, first } = await openStream(conversationId, text, controller.signal)
+        let result = first
+        while (!result.done) {
+          state = reduceTurn(state, result.value)
+          publish(state)
+          result = await iterator.next()
+        }
+      } catch (error) {
+        // An abort is the operator's own doing: keep whatever streamed, add no
+        // error. Anything else becomes the turn's error. Either way a tool call
+        // still outstanding is closed — it will never report back now.
+        state = isAbort(error) ? abortTurn(state) : failTurn(state, describeError(error))
+      } finally {
+        // An abort cancels the reader rather than rejecting the read, so it
+        // usually ends the loop normally and never reaches the catch above. The
+        // closing-down a stopped turn needs therefore happens here.
+        const interrupted = controller.signal.aborted && !isTurnSettled(state)
+        if (interrupted) state = abortTurn(state)
+
+        store.getState().appendMessage(conversationId, {
+          id: uuid(),
+          role: MESSAGE_ROLE.ASSISTANT,
+          text: state.text,
+          at: Date.now(),
+          tools: state.tools,
+          error: state.error,
+          // Half an answer must not read back later as the agent's full statement.
+          ...(interrupted ? { interrupted: true } : {}),
+        })
+        publish(null)
+        abortRef.current = null
+        busyRef.current = false
+        setIsBusy(false)
+        setDecidedApprovalId(null)
+      }
+    },
+    [openStream, publish, store],
+  )
+
+  const send = useCallback(
+    (raw: string) => {
+      const text = raw.trim()
+      // Guarded on the ref rather than the rendered flag: two submits inside one
+      // frame would both see the old state and provoke a 409.
+      if (!text || busyRef.current) return
+      void runTurn(text)
+    },
+    [runTurn],
+  )
+
+  const decide = useCallback(
+    (approved: boolean) => {
+      const pending = liveRef.current?.pendingApproval
+      const conversationId = store.getState().activeId
+      if (!pending || !conversationId) return
+      const sessionId = store
+        .getState()
+        .conversations.find((conversation) => conversation.id === conversationId)?.sessionId
+      if (!sessionId) return
+
+      setDecidedApprovalId(pending.approvalId)
+      void decideApproval(sessionId, pending.approvalId, approved, config).catch((error: unknown) => {
+        // A 404 means the approval already settled — it timed out server-side, or
+        // this is a second decision. Both are indistinguishable by design, and
+        // the stream resumes either way, so there is nothing to report.
+        if (error instanceof AgentApiError && error.is(AGENT_ERROR.APPROVAL_NOT_FOUND)) return
+        setDecidedApprovalId(null)
+      })
+    },
+    [config, store],
+  )
+
+  const abort = useCallback(() => {
+    abortRef.current?.abort()
+  }, [])
+
+  /**
+   * Re-asks the last question after a failed turn.
+   *
+   * The question is re-sent as a new message rather than the failed turn being
+   * resumed — the gateway has no notion of resuming one — so the transcript shows
+   * it asked twice, which is what happened.
+   */
+  const retry = useCallback(() => {
+    if (busyRef.current) return
+    const conversationId = store.getState().activeId
+    if (!conversationId) return
+
+    const messages = store
+      .getState()
+      .conversations.find((conversation) => conversation.id === conversationId)?.messages ?? []
+    const lastQuestion = [...messages].reverse().find((message) => message.role === MESSAGE_ROLE.USER)
+    if (!lastQuestion) return
+
+    void runTurn(lastQuestion.text)
+  }, [runTurn, store])
+
+  const newConversation = useCallback(() => {
+    if (busyRef.current) return
+    create()
+  }, [create])
+
+  const selectConversation = useCallback(
+    (id: string) => {
+      if (busyRef.current) return
+      select(id)
+    },
+    [select],
+  )
+
+  /**
+   * Drops the conversation locally and releases its gateway session.
+   *
+   * The DELETE is best-effort and deliberately unawaited: the session may
+   * already be gone (a restart, or the agent's own TTL) and the gateway refuses
+   * to delete one with a turn in flight. Neither should block removing the local
+   * record, which is the only copy the operator can see.
+   */
+  const removeConversation = useCallback(
+    (id: string) => {
+      if (busyRef.current && store.getState().activeId === id) return
+
+      const sessionId = store
+        .getState()
+        .conversations.find((conversation) => conversation.id === id)?.sessionId
+
+      remove(id)
+
+      if (sessionId) {
+        void deleteSession(sessionId, config).catch(() => {
+          // Already collected, or still busy. The gateway reaps it either way.
+        })
+      }
+    },
+    [config, remove, store],
+  )
+
+  const pendingApproval = live?.pendingApproval ?? null
+
+  return {
+    conversations,
+    active,
+    messages: active?.messages ?? [],
+    live,
+    isStreaming: isBusy,
+    pendingApproval,
+    isDecisionPending: pendingApproval !== null && decidedApprovalId === pendingApproval.approvalId,
+    // A turn paused on an approval still holds the session busy, so this stays
+    // false through the approval too — sending now would be a 409.
+    canSend: !isBusy,
+    send,
+    decide,
+    abort,
+    retry,
+    newConversation,
+    selectConversation,
+    removeConversation,
+  }
+}

package/src/hooks/use-agent-config.ts

@@ -0,0 +1,70 @@
+import type { AgentTransportOptions, TokenSource } from '../core/transport'
+import { useMdkAuth, useQueryClient } from '@tetherto/mdk-react-adapter'
+import { getFetcher, getMdkRuntime } from '@tetherto/mdk-ui-foundation'
+import { useMemo } from 'react'
+
+export type AgentConfigOptions = {
+  /**
+   * Gateway origin. Defaults to whatever the app already configured on
+   * `MdkProvider`, so a host that set its API base once does not set it again
+   * here — and to `''` outside one, meaning relative URLs, which is what the
+   * generated shell wants: it proxies `/agent` in dev and is served same-origin
+   * in production. Set it only to override that, and remember the gateway sends
+   * no CORS headers if you point it at another origin.
+   */
+  apiBaseUrl?: string
+  /**
+   * Bearer token source. Defaults to the `MdkProvider`'s auth provider, and to
+   * no token at all outside one — which is correct for a gateway running without
+   * an auth plugin, where every caller is the single local operator.
+   */
+  getToken?: TokenSource
+  /** Injected in tests and by the catalog demo. */
+  fetchImpl?: typeof fetch
+}
+
+/**
+ * The base URL the app already configured on `MdkProvider`, or undefined.
+ *
+ * Two things make this narrower than a plain `getApiBaseUrl`. It has to survive
+ * having no provider at all, since the panel is meant to drop into a non-MDK
+ * app — `useQueryClient` throws there, and the context read happens before the
+ * throw, so guarding it leaves hook order intact. And `getApiBaseUrl` answers
+ * `http://localhost:3000` for a client MDK did not build, which would quietly
+ * point the panel at an origin nobody chose. A fetcher in the meta is what says
+ * the client came from `createMdkQueryClient`, so its base URL — including the
+ * empty string the shell sets deliberately — is meant rather than defaulted.
+ */
+function useConfiguredBaseUrl(): string | undefined {
+  // Neither MDK package re-exports the QueryClient type, and @tanstack/react-query is not a
+  // dependency here — so the type comes from the hook that returns it.
+  let client: ReturnType<typeof useQueryClient>
+  try {
+    client = useQueryClient()
+  } catch {
+    return undefined
+  }
+  return getFetcher(client) ? getMdkRuntime(client).baseUrl : undefined
+}
+
+/**
+ * Resolves transport options from explicit props, falling back to the MDK
+ * provider.
+ *
+ * `useMdkAuth` deliberately does not throw outside an `MdkProvider`, which is
+ * what lets the panel be dropped into a non-MDK app with just an `apiBaseUrl`.
+ */
+export function useAgentConfig(options: AgentConfigOptions = {}): AgentTransportOptions {
+  const auth = useMdkAuth()
+  const configuredBaseUrl = useConfiguredBaseUrl()
+  const { apiBaseUrl, getToken, fetchImpl } = options
+
+  return useMemo<AgentTransportOptions>(
+    () => ({
+      baseUrl: apiBaseUrl ?? configuredBaseUrl ?? '',
+      getToken: getToken ?? (() => auth.getToken()),
+      ...(fetchImpl ? { fetchImpl } : {}),
+    }),
+    [apiBaseUrl, configuredBaseUrl, getToken, fetchImpl, auth],
+  )
+}

package/src/hooks/use-conversations.ts

@@ -0,0 +1,39 @@
+import type { StoreApi } from 'zustand/vanilla'
+import { useMemo } from 'react'
+import { useStore } from 'zustand'
+
+import type { Conversation, ConversationStore } from '../core/conversation-store'
+import { conversationStore as defaultStore } from '../core/conversation-store'
+
+export type UseConversationsResult = {
+  /** Newest first — the order the Conversations view renders. */
+  conversations: Conversation[]
+  active: Conversation | null
+  activeId: string | null
+  create: ConversationStore['create']
+  select: ConversationStore['select']
+  remove: ConversationStore['remove']
+}
+
+/**
+ * Binds the conversation store to React.
+ *
+ * Takes a store instance so tests and the catalog demo can run against an
+ * isolated one; runtime callers get the module singleton.
+ */
+export function useConversations(
+  store: StoreApi<ConversationStore> = defaultStore,
+): UseConversationsResult {
+  const conversations = useStore(store, (state) => state.conversations)
+  const activeId = useStore(store, (state) => state.activeId)
+  const create = useStore(store, (state) => state.create)
+  const select = useStore(store, (state) => state.select)
+  const remove = useStore(store, (state) => state.remove)
+
+  const active = useMemo(
+    () => conversations.find((conversation) => conversation.id === activeId) ?? null,
+    [conversations, activeId],
+  )
+
+  return { conversations, active, activeId, create, select, remove }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * @tetherto/mdk-ui-agent
+ *
+ * The operator Co-pilot, as a drop-in for any MDK UI shell. Talks to the agent
+ * gateway plugin (`@tetherto/mdk-app-agent`) over SSE and renders its
+ * six-event contract as a conversation.
+ *
+ * ```tsx
+ * import { CoPilot } from '@tetherto/mdk-ui-agent'
+ * import '@tetherto/mdk-ui-agent/styles.css'
+ *
+ * <CoPilot />
+ * ```
+ *
+ * `CoPilotPanel` is deliberately NOT exported here — it is reachable from
+ * `@tetherto/mdk-ui-agent/panel`. Both entries load it through a lazy boundary
+ * so the markdown renderer and syntax highlighter stay out of the host's first
+ * paint, and a single static import from this barrel would collapse that split
+ * for every consumer.
+ */
+
+export { AGENT_LABELS, AGENT_NAME, OPERATOR_NAME } from './branding'
+export * from './core'
+export type { ChatUIEntryProps } from './entries/chat-page'
+
+export { ChatUIEntry } from './entries/chat-page'
+export type { CoPilotPosition, CoPilotProps } from './entries/co-pilot'
+
+export { CoPilot, COPILOT_POSITION } from './entries/co-pilot'
+export * from './hooks'

package/src/styles/_approval.scss

@@ -0,0 +1,68 @@
+/* The inline approval prompt. The stream is paused behind this. */
+
+.mdk-agent-approval {
+  padding: 12px 14px 14px;
+
+  /* Dashed, per the design — it reads as "pending / not yet real", which is
+     exactly the state a paused write is in. */
+  border: 1px dashed color-mix(in srgb, var(--mdk-agent-accent) 60%, transparent);
+  border-radius: var(--mdk-agent-radius);
+  background: color-mix(in srgb, var(--mdk-agent-accent) 6%, var(--mdk-agent-surface));
+
+  &__title {
+    margin: 0 0 12px;
+    color: var(--mdk-agent-accent);
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+  }
+
+  &__details {
+    margin: 0 0 14px;
+  }
+
+  &__row {
+    display: flex;
+    gap: 12px;
+    align-items: baseline;
+
+    & + & {
+      margin-top: 6px;
+    }
+  }
+
+  &__label {
+    flex: none;
+    width: 90px;
+    color: var(--mdk-agent-text-muted);
+    font-size: 11px;
+    text-transform: capitalize;
+  }
+
+  &__value {
+    margin: 0;
+    min-width: 0;
+    overflow-wrap: anywhere;
+  }
+
+  &__actions {
+    display: flex;
+    gap: 8px;
+    justify-content: flex-end;
+
+    /* Reject is the outline variant, which the devkit renders light-on-dark —
+       a white slab next to the filled Approve. The design has it dark with a
+       hairline border, so it reads as the secondary choice. */
+    button:first-child {
+      border: 1px solid var(--mdk-agent-border-strong);
+      background: transparent;
+      color: var(--mdk-agent-text);
+
+      &:hover:not(:disabled) {
+        border-color: var(--mdk-agent-danger);
+        color: var(--mdk-agent-danger);
+      }
+    }
+  }
+}

package/src/styles/_composer.scss

@@ -0,0 +1,45 @@
+/* The input row. */
+
+.mdk-agent-composer {
+  display: flex;
+  flex: none;
+  gap: 8px;
+  align-items: flex-end;
+  padding: 12px;
+  border-top: 1px solid var(--mdk-agent-border);
+
+  &__input {
+    flex: 1 1 auto;
+    min-width: 0;
+    padding: 10px 12px;
+    border: 1px solid var(--mdk-agent-border-strong);
+    border-radius: var(--mdk-agent-radius);
+    background: transparent;
+    color: var(--mdk-agent-text);
+    font-family: inherit;
+    font-size: 13px;
+    line-height: 19px;
+    resize: none;
+
+    &::placeholder {
+      color: var(--mdk-agent-text-muted);
+    }
+
+    &:focus-visible {
+      border-color: var(--mdk-agent-accent);
+      outline: none;
+    }
+
+    &:disabled {
+      cursor: not-allowed;
+      opacity: 0.5;
+    }
+  }
+
+  &__send {
+    flex: none;
+    width: 40px;
+    height: 40px;
+    padding: 0;
+  }
+}