Embed a Session view

Render a live Session transcript in your React app without adopting Checkfu’s frontend stack.

@checkfu/ui is a React library your application installs and renders itself. There is no iframe, hosted widget, or script tag. The components take event data and emit intents; they know nothing about your router, state library, authentication, or backend framework.

Install and render

React 19 and react-dom are the only peer dependencies.

Private alpha: the package is not yet published to npm. Today it lives inside the platform repository while the public release is prepared, so the install below does not resolve yet. The component surface is the stable one.

pnpm add @checkfu/ui react react-dom

Import the plain CSS once. Its --cfui-* custom properties are the entire theme boundary; no Tailwind setup is required.

import "@checkfu/ui/styles.css"
import { EventMinimap, TranscriptView, toTranscript } from "@checkfu/ui"

export function SessionView({ events }) {
  const rows = toTranscript(events)
  const items = events.map((event, index) => ({ event, row: rows[index] }))

  return (
    <section aria-label="Agent activity">
      <EventMinimap rows={rows} events={events} activeSeq={null} onSelect={() => {}} />
      <TranscriptView items={items} mode="transcript" followOutput />
    </section>
  )
}

The package also exports EventRow, ToolCallCard, SessionStatusBadge, and the compound ActionApprovalPrompt. Each has its own subpath for hosts that want one piece rather than the barrel.

Give the browser one Session, not your Workspace key

Keep the Checkfu API key on your server. After authenticating your end user and resolving their person Principal, mint a short-lived capability for the exact Session and actions the UI needs:

// Server only
const capability = await checkfu.sessions.clientCapabilities.create(sessionId, {
  principal: principalId,
  permissions: ["observe", "steer", "answer_question"],
  ttl_seconds: 300,
})
return Response.json(capability)

Checkfu binds the token to that Session, Principal, installation/surface placement, permission set, wire version, and expiry. Every use rechecks the live Session and PermissionAssignments. The token is rejected on every control-plane, operator, runtime, MCP, and other-Session route.

Use the returned object with the capability-only SDK in the browser:

import { SessionClient } from "@checkfu/sdk"

const session = new SessionClient({ capability })
const firstPage = await session.events.list()

for await (const event of session.events.stream()) {
  // Reconcile by event.seq; the iterator resumes with Last-Event-ID.
}

SessionClient has no generic request escape hatch and accepts no API key or Workspace selector. It can list/stream events and send only messages, interrupts, or Question answers allowed by the token. ActionApproval remains a server-owned flow.

For a trusted embedded agent surface that also needs the active managed agent’s released Connections, mint invoke_tools in addition to the event permissions. This permission is available only while an installed Session has an active Run:

// Server only
const capability = await checkfu.sessions.clientCapabilities.create(sessionId, {
  principal: principalId,
  permissions: ["observe", "invoke_tools"],
  ttl_seconds: 300,
})

// Browser or external SDK client
const session = new SessionClient({ capability })
const result = await session.tools.call(connectionId, "create_issue", {
  title: "Investigate the failed deployment",
})

The call reuses the Session’s exact active Run, frozen release and Connection roster, then crosses CapabilityGateway. The client receives neither the RunCapabilityToken nor a provider credential. A token carrying invoke_tools is consequential: give it only to the intended trusted origin and request it only when the UI actually needs tool access.

Never put CHECKFU_API_KEY, a Workspace key, or a console key in browser JavaScript. A Session capability is intentionally attenuated and expires, but it remains a bearer; invoke_tools can request real provider effects for the active Run, so grant it only to a trusted embedded client.

The stream is data, not a change bell

useSessionEvents from @checkfu/ui/sdk owns the whole loop. Hand it your client — a SessionClient for browser-direct mode, or the Workspace-proxy transport when your backend’s two forwarding routes hold the key:

import { useSessionEvents, workspaceProxyTransport } from "@checkfu/ui/sdk"

// Browser-direct: the attenuated capability names its own Session.
const direct = useSessionEvents({ client: session })

// Proxy mode: your backend forwards
// GET {routePrefix}/sessions/{id}/events and .../events/stream upstream.
const proxied = useSessionEvents({
  sessionKey: sessionId,
  transport: workspaceProxyTransport({ sessionId, routePrefix: "/api/agent" }),
})

The hook pages the durable log once, then consumes stream frames as data: durable frames append by seq (appending event N never re-reads 1..N-1), streaming previews render as ephemeral deltas and are replaced by their durable event, and a checkfu.cursor_gap triggers exactly one bounded backfill page for the gap range. Reconnects resume losslessly from the last durable seq, with a bounded five-second poll only while the stream is down.

Honesty is part of the result: state.unavailable carries the durable positions whose content the platform cannot produce (crypto-shredded, zero data retention, or an unaccounted gap), and TranscriptView renders them as explicit rows — a complete transcript and a shredded one never look the same. In transcript mode, keyboard reading order visits each unavailable range as one disabled option; it is announced without changing the event-only selectedSeq. state.previews carries in-flight streaming deltas; render them with StreamingDeltaRow, which is explicit about being ephemeral. The rest of the chat surface is composable the same way: Composer (drives user.message with disabled-with-reason states), QuestionCard (agent.question → user.question_answer), InterruptButton (cooperative drain vs immediate force cancel), and SessionList — all intent-emitting, none fetching. In QuestionCard, empty options render one bounded free-text answer, and a new Question id clears every local draft before it renders.

The SDK’s stream is the only SSE reader involved — no host application parses data:/id: lines. See Resume a stream reliably for the cursor rules the SDK implements.

ActionApproval intents

The compound approval component keeps API ownership in your host:

<ActionApprovalPrompt.Root approval={frozenContext} onIntent={respondFromYourBackend}>
  <ActionApprovalPrompt.Context />
  <ActionApprovalPrompt.Actions />
</ActionApprovalPrompt.Root>

onIntent receives one of three UI intents: approve, deny, or instructions. The first two map to the ActionApproval API’s decision enum — it accepts approve | deny and nothing else. instructions is not a decision: it is the reviewer asking to attach a note, which your host renders and then sends as the optional instructions string alongside an approve or deny. Route the resulting decision to your authenticated backend, which uses the TypeScript SDK to respond to the durable ActionApproval. The component never responds on its own.