@frontera-sdk/chat 1.50.40

package/src/hooks.ts

@@ -0,0 +1,202 @@
+import { createContext, useContext } from 'react'
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type UseMutationOptions,
+  type UseMutationResult,
+  type UseQueryOptions,
+  type UseQueryResult,
+} from '@tanstack/react-query'
+
+import type { ChatClient } from './chat-client'
+import type {
+  ApprovalDecision,
+  CreateSessionRequest,
+  ListSessionsQuery,
+  PendingApproval,
+  Paginated,
+  Session,
+  SessionMessage,
+  UpdateSessionRequest,
+} from './types'
+
+/**
+ * Query-key factory, same convention as `blueprintKeys`: requests serialise
+ * into the key so structurally equal requests share a cache entry.
+ */
+export const chatKeys = {
+  all: ['chat'] as const,
+  sessions: (query?: ListSessionsQuery) =>
+    ['chat', 'sessions', JSON.stringify(query ?? {})] as const,
+  session: (id: string) => ['chat', 'session', id] as const,
+  messages: (id: string) => ['chat', 'messages', id] as const,
+  followUps: (conversationId: string, messageId: string) =>
+    ['chat', 'follow-ups', conversationId, messageId] as const,
+  approvals: (conversationId: string) => ['chat', 'approvals', conversationId] as const,
+}
+
+export const FronteraChatContext = createContext<ChatClient | null>(null)
+
+export function useChatClient(): ChatClient {
+  const client = useContext(FronteraChatContext)
+  if (!client) {
+    throw new Error(
+      'No ChatClient in context. Wrap the tree in FronteraChatContext.Provider — in a Frontera app, add chatProvider to createFronteraApp providers.',
+    )
+  }
+  return client
+}
+
+type ReadOptions<TData> = Omit<UseQueryOptions<TData, Error>, 'queryKey' | 'queryFn' | 'select'>
+type WriteOptions<TData, TVariables> = Omit<
+  UseMutationOptions<TData, Error, TVariables>,
+  'mutationFn'
+>
+
+/**
+ * These hooks cover PERSISTED state (sessions, history). Live streaming state
+ * belongs to `useChat` from `@ai-sdk/react` with `createChatTransport` — there
+ * is deliberately no second streaming state machine here.
+ */
+export function useSessions(
+  query?: ListSessionsQuery,
+  options: ReadOptions<Paginated<Session>> = {},
+): UseQueryResult<Paginated<Session>, Error> {
+  const client = useChatClient()
+  return useQuery({
+    queryKey: chatKeys.sessions(query),
+    queryFn: () => client.listSessions(query),
+    ...options,
+  })
+}
+
+export function useSession(
+  id: string,
+  options: ReadOptions<Session> = {},
+): UseQueryResult<Session, Error> {
+  const client = useChatClient()
+  return useQuery({
+    queryKey: chatKeys.session(id),
+    queryFn: () => client.getSession(id),
+    ...options,
+  })
+}
+
+export function useSessionMessages(
+  id: string,
+  options: ReadOptions<SessionMessage[]> = {},
+): UseQueryResult<SessionMessage[], Error> {
+  const client = useChatClient()
+  return useQuery({
+    queryKey: chatKeys.messages(id),
+    queryFn: () => client.getMessages(id),
+    ...options,
+  })
+}
+
+export function useFollowUps(
+  conversationId: string,
+  messageId: string,
+  options: ReadOptions<{ suggestions: unknown[] }> = {},
+): UseQueryResult<{ suggestions: unknown[] }, Error> {
+  const client = useChatClient()
+  return useQuery({
+    queryKey: chatKeys.followUps(conversationId, messageId),
+    queryFn: () => client.getFollowUps(conversationId, messageId),
+    ...options,
+  })
+}
+
+export function useCreateSession(
+  options: WriteOptions<Session, CreateSessionRequest> = {},
+): UseMutationResult<Session, Error, CreateSessionRequest> {
+  const client = useChatClient()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (request: CreateSessionRequest) => client.createSession(request),
+    ...options,
+    onSuccess: (data, variables, context, mutation) => {
+      void queryClient.invalidateQueries({ queryKey: chatKeys.all })
+      return options.onSuccess?.(data, variables, context, mutation)
+    },
+  })
+}
+
+export function useUpdateSession(
+  options: WriteOptions<{ success: boolean }, { id: string; patch: UpdateSessionRequest }> = {},
+): UseMutationResult<{ success: boolean }, Error, { id: string; patch: UpdateSessionRequest }> {
+  const client = useChatClient()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: ({ id, patch }) => client.updateSession(id, patch),
+    ...options,
+    onSuccess: (data, variables, context, mutation) => {
+      void queryClient.invalidateQueries({ queryKey: chatKeys.session(variables.id) })
+      void queryClient.invalidateQueries({ queryKey: chatKeys.all })
+      return options.onSuccess?.(data, variables, context, mutation)
+    },
+  })
+}
+
+/**
+ * The parked tool calls of one conversation.
+ *
+ * Polling is on by default while the tab is visible, and that is the point: an
+ * approval appears mid-run, from the agent's side, so a query that only ran on
+ * mount would leave the user staring at a stalled conversation. Pass
+ * `refetchInterval: false` if you drive it from the stream instead.
+ */
+export function usePendingApprovals(
+  conversationId: string,
+  options: ReadOptions<PendingApproval[]> = {},
+): UseQueryResult<PendingApproval[], Error> {
+  const client = useChatClient()
+  return useQuery({
+    queryKey: chatKeys.approvals(conversationId),
+    queryFn: () => client.listPendingApprovals(conversationId),
+    enabled: Boolean(conversationId),
+    refetchInterval: 5_000,
+    ...options,
+  })
+}
+
+export function useRespondToApproval(
+  conversationId: string,
+  options: WriteOptions<
+    { id: string; status: string },
+    { approvalId: string; decision: ApprovalDecision }
+  > = {},
+): UseMutationResult<
+  { id: string; status: string },
+  Error,
+  { approvalId: string; decision: ApprovalDecision }
+> {
+  const client = useChatClient()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: ({ approvalId, decision }) => client.respondToApproval(approvalId, decision),
+    ...options,
+    onSuccess: (data, variables, context, mutation) => {
+      void queryClient.invalidateQueries({ queryKey: chatKeys.approvals(conversationId) })
+      return options.onSuccess?.(data, variables, context, mutation)
+    },
+  })
+}
+
+export function useCancelRun(
+  options: WriteOptions<{ success: true }, string> = {},
+): UseMutationResult<{ success: true }, Error, string> {
+  const client = useChatClient()
+  return useMutation({ mutationFn: (runId: string) => client.cancelRun(runId), ...options })
+}
+
+export function useSteerRun(
+  options: WriteOptions<{ success: true }, { runId: string; message: string }> = {},
+): UseMutationResult<{ success: true }, Error, { runId: string; message: string }> {
+  const client = useChatClient()
+  return useMutation({
+    mutationFn: ({ runId, message }) => client.steerRun(runId, message),
+    ...options,
+  })
+}

package/src/provider.tsx

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react'
+import type { FronteraClient } from '@frontera-sdk/core/client'
+
+import { ChatClient } from './chat-client'
+import { FronteraChatContext } from './hooks'
+
+/**
+ * Plug chat into `createFronteraApp` — Frontera Apps only:
+ *
+ * ```tsx
+ * createFronteraApp(<App />, { providers: [blueprintProvider, chatProvider] })
+ * ```
+ *
+ * External applications don't use this: they construct their own
+ * `FronteraClient` and either use `ChatClient` directly or wrap
+ * `FronteraChatContext.Provider` themselves. The client is rebuilt whenever
+ * the host rotates the credential, same as `blueprintProvider`.
+ */
+export function chatProvider(value: { client: FronteraClient }, children: ReactNode): ReactNode {
+  return (
+    <FronteraChatContext.Provider value={new ChatClient(value.client)}>
+      {children}
+    </FronteraChatContext.Provider>
+  )
+}

package/src/stream.ts

@@ -0,0 +1,61 @@
+import type { FronteraClient } from '@frontera-sdk/core/client'
+import { FronteraError } from '@frontera-sdk/core/errors'
+
+import type { StartChatRequest, StartChatResult } from './types'
+
+export interface ChatStreamOptions {
+  signal?: AbortSignal
+}
+
+/**
+ * Start a run. The returned `response.body` is an AI SDK v6 UI-message SSE
+ * stream — hand it to `readUIMessageStream` from `ai`, or use
+ * `createChatTransport` with `useChat` instead of calling this directly.
+ *
+ * The server interleaves `: ping` SSE comment frames every 15s as keepalive;
+ * standard SSE parsers (including the AI SDK's) ignore them.
+ */
+export async function startChat(
+  client: FronteraClient,
+  request: StartChatRequest,
+  options: ChatStreamOptions = {},
+): Promise<StartChatResult> {
+  const response = await client.requestRaw('/v1/chat', {
+    method: 'POST',
+    body: request,
+    signal: options.signal,
+  })
+
+  const conversationId = response.headers.get('x-conversation-id')
+  const runId = response.headers.get('x-workflow-run-id')
+  if (!conversationId || !runId) {
+    throw new FronteraError('chat response is missing run identification headers', {
+      code: 'PROTOCOL_ERROR',
+      status: response.status,
+    })
+  }
+
+  return {
+    conversationId,
+    runId,
+    runtime: response.headers.get('x-agent-runtime') ?? 'pi',
+    quotaWarning: response.headers.get('x-quota-warning') ?? undefined,
+    response,
+  }
+}
+
+/**
+ * Re-attach to a running (or just-finished) run's stream. `startIndex` is the
+ * journal index to replay from — pass the count of chunks already consumed to
+ * resume without duplicates.
+ */
+export async function resumeStream(
+  client: FronteraClient,
+  runId: string,
+  options: { startIndex?: number } & ChatStreamOptions = {},
+): Promise<Response> {
+  return client.requestRaw(`/v1/chat/${encodeURIComponent(runId)}/stream`, {
+    query: { startIndex: options.startIndex },
+    signal: options.signal,
+  })
+}

package/src/token-session.ts

@@ -0,0 +1,182 @@
+/**
+ * A chat credential that keeps itself alive.
+ *
+ * The alternative — what an integration writes by hand — is a timer that calls
+ * their own backend, plus a 401 handler, plus the knowledge that both are
+ * needed. Every one of those is a place to be subtly wrong: refresh too late
+ * and a send fails; forget the 401 path and a laptop reopened after lunch
+ * shows a chat that quietly cannot send.
+ *
+ * So the session owns it. It renews against the platform (one signature check,
+ * no round trip to the customer's backend), falls back to `getToken` when
+ * renewal is no longer allowed, and hands the current credential to whoever
+ * asks. Nothing else in the SDK needs to know a token can expire.
+ */
+
+import { FronteraClient } from '@frontera-sdk/core/client'
+import { FronteraError } from '@frontera-sdk/core/errors'
+
+import type { ChatToken } from './types'
+
+export interface TokenSessionOptions {
+  apiBaseUrl: string
+  /**
+   * Fetches a token from YOUR backend. Called once at the start, and again
+   * whenever renewal is no longer possible — a session that has run past its
+   * ceiling, or a token that expired while the tab was asleep.
+   */
+  getToken: () => Promise<ChatToken | string>
+  /**
+   * A token you already have — typically the one whose expiry told you which
+   * `apiBaseUrl` to use. Supplying it skips the opening fetch, so a mount does
+   * not mint twice for the same person.
+   */
+  initialToken?: ChatToken
+  /**
+   * Renew this long before expiry, as a fraction of the token's lifetime.
+   * 0.8 leaves a fifth of the lifetime as slack — enough for a slow network or
+   * a suspended tab to recover without a single failed request.
+   */
+  renewAt?: number
+  /** Called after every successful renewal. Handy for persisting the token. */
+  onToken?: (token: ChatToken) => void
+  /**
+   * Called when the session cannot be kept alive at all — both renewal and
+   * `getToken` failed. The chat is dead until something changes, and the host
+   * is the only one that can say so on screen.
+   */
+  onExpired?: (error: unknown) => void
+  /** Test seam. Defaults to the global. */
+  fetchImpl?: typeof fetch
+}
+
+export interface TokenSession {
+  /** The client to hand to `ChatClient` and `createChatTransport`. */
+  getClient: () => FronteraClient
+  /** The credential right now, mostly for diagnostics. */
+  current: () => ChatToken | null
+  /**
+   * Force a refresh — call it when a request comes back `UNAUTHORIZED`. Safe to
+   * call concurrently: overlapping callers share one in-flight refresh rather
+   * than racing to mint several tokens for the same person.
+   */
+  refresh: () => Promise<ChatToken>
+  /** Stop the timer. Call it when the chat unmounts. */
+  dispose: () => void
+}
+
+const DEFAULT_RENEW_AT = 0.8
+/** Never schedule closer than this; a pathologically short token would
+ *  otherwise spin the timer. */
+const MIN_DELAY_MS = 5_000
+
+function asToken(value: ChatToken | string): ChatToken {
+  return typeof value === 'string'
+    ? // A bare string has no expiry to plan around. Treated as one hour — the
+      // platform default — so the session still refreshes rather than waiting
+      // for a failure. Return the full object from your backend to be exact.
+      { token: value, expiresAt: new Date(Date.now() + 3600_000).toISOString() }
+    : value
+}
+
+export function createTokenSession(options: TokenSessionOptions): TokenSession {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch
+  const renewAt = options.renewAt ?? DEFAULT_RENEW_AT
+
+  let token: ChatToken | null = null
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let inFlight: Promise<ChatToken> | null = null
+  let disposed = false
+
+  const client = () =>
+    new FronteraClient(
+      {
+        apiBaseUrl: options.apiBaseUrl,
+        credential: { kind: 'token', token: token?.token ?? '' },
+      },
+      fetchImpl,
+    )
+
+  const schedule = (current: ChatToken) => {
+    if (timer) clearTimeout(timer)
+    if (disposed) return
+    const lifetime = new Date(current.expiresAt).getTime() - Date.now()
+    if (!Number.isFinite(lifetime)) return
+    const delay = Math.max(MIN_DELAY_MS, lifetime * renewAt)
+    timer = setTimeout(() => {
+      void refresh().catch(() => {
+        // `refresh` already reported through onExpired; swallowing here keeps
+        // an unhandled rejection out of the host's console for a condition it
+        // has already been told about.
+      })
+    }, delay)
+    // A timer must never hold a Node process open on its own account.
+    ;(timer as unknown as { unref?: () => void }).unref?.()
+  }
+
+  /** Renew against the platform; the customer's backend is not involved. */
+  const renew = async (): Promise<ChatToken> => {
+    if (!token) throw new Error('no token to renew')
+    const response = await fetchImpl(`${options.apiBaseUrl}/v1/chat-tokens/renew`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token.token}` },
+    })
+    if (!response.ok) {
+      throw new FronteraError(`renewal refused with ${response.status}`, {
+        code: response.status === 401 ? 'UNAUTHORIZED' : 'RENEWAL_FAILED',
+        status: response.status,
+      })
+    }
+    const body = (await response.json()) as { data?: ChatToken } & ChatToken
+    return body.data ?? body
+  }
+
+  const refresh = (): Promise<ChatToken> => {
+    // One refresh at a time. Three components noticing an expiry in the same
+    // tick must not mint three tokens — and the two that lose the race would
+    // otherwise keep using a credential the third has already replaced.
+    inFlight ??= (async () => {
+      try {
+        let next: ChatToken
+        try {
+          next = token ? await renew() : asToken(await options.getToken())
+        } catch {
+          // Renewal is the fast path, not the only one: a session past its
+          // ceiling, or a token that expired while the tab slept, is exactly
+          // when the customer's backend should be asked again.
+          next = asToken(await options.getToken())
+        }
+        token = next
+        options.onToken?.(next)
+        schedule(next)
+        return next
+      } catch (error) {
+        options.onExpired?.(error)
+        throw error
+      } finally {
+        inFlight = null
+      }
+    })()
+    return inFlight
+  }
+
+  if (options.initialToken) {
+    token = options.initialToken
+    schedule(token)
+  } else {
+    // Start immediately so the first render has a credential in flight rather
+    // than a client pointing at an empty token.
+    void refresh().catch(() => {})
+  }
+
+  return {
+    getClient: client,
+    current: () => token,
+    refresh,
+    dispose: () => {
+      disposed = true
+      if (timer) clearTimeout(timer)
+      timer = null
+    },
+  }
+}

package/src/transport.ts

@@ -0,0 +1,200 @@
+import { DefaultChatTransport, type ChatTransport, type UIMessage } from 'ai'
+import type { FronteraClient } from '@frontera-sdk/core/client'
+import { authHeaders } from '@frontera-sdk/core/transport'
+import { errorFromResponse } from '@frontera-sdk/core/errors'
+import { chatDoctor } from './doctor'
+
+import type { StartChatRequest } from './types'
+
+export interface ChatTransportOptions {
+  /** Continue an existing conversation. Omit to let the server create one. */
+  conversationId?: string
+  /**
+   * Send only the last user message (default true). The server rehydrates the
+   * rest of the conversation from its own store, which keeps request bodies
+   * small — the platform web app does the same.
+   */
+  lastMessageOnly?: boolean
+  /**
+   * Extra body fields merged into every send (agentName, modelMode, …).
+   *
+   * Pass a FUNCTION for anything that can change while the chat is mounted.
+   * An object is read once, at construction: `useChat` keeps the transport it
+   * was first handed, so rebuilding this one with new options never reaches
+   * the request, and the send goes out with whatever was true at first render.
+   * That is how a conversation ends up with a different agent than the one on
+   * screen.
+   */
+  body?:
+    | Partial<Omit<StartChatRequest, 'messages' | 'conversationId'>>
+    | (() => Partial<Omit<StartChatRequest, 'messages' | 'conversationId'>>)
+  /**
+   * Fired once per run with the identifiers from the response headers. The
+   * `runId` is what `resumeStream`/`cancelRun`/`steerRun` take, and
+   * `conversationId` is how a fresh conversation learns its id.
+   */
+  onStart?: (info: {
+    conversationId: string
+    runId: string
+    runtime: string
+    quotaWarning?: string
+  }) => void
+  /**
+   * Called once when a request comes back `401`, before it is retried.
+   *
+   * Pass `session.refresh` from `createTokenSession` and an expired credential
+   * stops being a visible failure: the send is replayed with the new token and
+   * the person never learns there was one. Without it, a chat left open past
+   * the token's lifetime fails on the next message with nothing on screen
+   * explaining why.
+   */
+  onUnauthorized?: () => Promise<unknown>
+}
+
+/**
+ * The body of a failed response, as whatever it turns out to be.
+ *
+ * A gateway between the caller and the service answers HTML, and a dropped
+ * connection answers nothing at all; neither must turn a 502 into a parse
+ * error that hides the status the caller needed to see.
+ */
+async function readErrorBody(response: Response): Promise<unknown> {
+  try {
+    const text = await response.text()
+    if (!text) return undefined
+    try {
+      return JSON.parse(text)
+    } catch {
+      return text
+    }
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * An AI SDK `ChatTransport` for `useChat` that speaks the platform's chat
+ * wire protocol: auth from the `FronteraClient`'s credential, last-message-only
+ * sends, and reconnects via the run's replay stream.
+ *
+ * Browser use requires a browser-safe credential (an end-user `cht_` token, or
+ * an `apiBaseUrl` pointing at your own proxy) — never ship a `sak_` key to a
+ * browser.
+ */
+export function createChatTransport(
+  client: FronteraClient | (() => FronteraClient),
+  options: ChatTransportOptions = {},
+): ChatTransport<UIMessage> {
+  // A getter is accepted because end-user tokens are short-lived BY DESIGN: an
+  // integration refreshes them mid-session, and a transport that captured the
+  // client at construction would keep signing with the expired credential
+  // until it was rebuilt — which drops any stream in flight. Reading the
+  // client per request makes rotation invisible.
+  const current = typeof client === 'function' ? client : () => client
+  let conversationId = options.conversationId
+  let runId: string | undefined
+
+  const wrappedFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const send = async () => {
+      const merged: Record<string, string> = {}
+      new Headers(init?.headers).forEach((value, name) => {
+        merged[name] = value
+      })
+      // Read per attempt, not once: a refresh between the two swaps the
+      // credential, and replaying with the old one would fail identically.
+      Object.assign(merged, authHeaders(current().config))
+      return fetch(input, { ...init, headers: merged })
+    }
+
+    let response = await send()
+
+    // Exactly one retry, and only for 401. A second attempt after a refusal
+    // that refreshing cannot fix is just a slower failure — and a loop here
+    // would hammer the mint path with a credential that will never work.
+    if (response.status === 401) {
+      if (options.onUnauthorized) {
+        await options.onUnauthorized()
+        response = await send()
+      } else {
+        // Said once, immediately: without a refresh wired, the next send fails
+        // the same way, and the person is looking at a chat that has silently
+        // stopped accepting messages.
+        chatDoctor.noticed('unauthorized')
+      }
+    }
+
+    /*
+      Refusals become `FronteraError` here, before the AI SDK sees them.
+
+      Left alone, a non-2xx reaches `useChat` as a bare `Error` whose message
+      is the response body — so "quota exhausted", "your token expired" and
+      "this agent was deleted" all arrive as one indistinguishable string, and
+      an integration cannot tell the user which of them happened or decide to
+      refresh the token. The service already answers with a coded envelope;
+      this keeps the code instead of discarding it.
+    */
+    if (!response.ok) {
+      throw errorFromResponse(response.status, await readErrorBody(response))
+    }
+    const headerConversationId = response.headers.get('x-conversation-id')
+    const headerRunId = response.headers.get('x-workflow-run-id')
+    if (headerConversationId && headerRunId) {
+      conversationId = headerConversationId
+      runId = headerRunId
+      options.onStart?.({
+        conversationId: headerConversationId,
+        runId: headerRunId,
+        runtime: response.headers.get('x-agent-runtime') ?? 'pi',
+        quotaWarning: response.headers.get('x-quota-warning') ?? undefined,
+      })
+    }
+    // Development only, and a no-op otherwise: watches the stream for the two
+    // things that park a run, so an unhandled one becomes a console warning
+    // rather than a conversation that appears to have stopped for no reason.
+    return chatDoctor.observe(response)
+  }) as typeof fetch
+
+  return new DefaultChatTransport<UIMessage>({
+    // Resolved per request, not here. The client may not exist yet: a caller
+    // that fetches its token asynchronously has nothing to give until the
+    // first exchange returns, and reading `.config` at construction would
+    // throw before anything could render.
+    api: '',
+    fetch: wrappedFetch,
+    /*
+      `body` here is the PER-CALL one — `sendMessage(message, { body })`.
+
+      It was dropped, and the loss was silent: attachments upload fine, the
+      composer shows them, the send succeeds, and the agent simply never
+      receives the file. Anything a caller attaches to one message travels this
+      way, so the same omission also swallowed per-send `modelMode` and any
+      custom field a host passes for a single turn.
+
+      Merged AFTER the transport-level `options.body` on purpose: that one is
+      the standing configuration for every send, and a value supplied for one
+      message is the more specific statement.
+    */
+    prepareSendMessagesRequest: ({ messages, body }) => {
+      const lastUserMessage = [...messages].reverse().find((m) => m.role === 'user')
+      const trimmed =
+        options.lastMessageOnly === false
+          ? messages
+          : lastUserMessage
+            ? [lastUserMessage]
+            : messages.slice(-1)
+      return {
+        api: `${current().config.apiBaseUrl}/v1/chat`,
+        body: {
+          messages: trimmed,
+          ...(conversationId ? { conversationId } : {}),
+          ...(typeof options.body === 'function' ? options.body() : options.body),
+          ...body,
+        },
+      }
+    },
+    prepareReconnectToStreamRequest: () => {
+      if (!runId) throw new Error('no run to reconnect to — no send has completed yet')
+      return { api: `${current().config.apiBaseUrl}/v1/chat/${encodeURIComponent(runId)}/stream` }
+    },
+  })
+}