Human-in-the-loop

HitlOverlay is the default Chakra surface for requests that need a user response during a session. It selects the input, approval, or agent-authorization panel; the headless HITL contract keeps the request state and actions.

Usage

The default session page already includes the overlay. When assembling a Chakra session page yourself, render it in the session route:

import { HitlOverlay } from '@hyperflow/chakra-ui'

export function SessionRequests() {
  return <HitlOverlay />
}

The overlay reads the active session from the route. It renders nothing until the runtime has a pending request.

Examples

Replace the approval panel

Use approvalPanelComponent when the tool-review surface needs a different visual structure. The replacement reads the same pending approval through the headless contract.

import { Box, Button, Text } from '@chakra-ui/react'
import { useSession, useToolApproval } from '@hyperflow/react'
import {
  HitlOverlay,
  type ApprovalPanelProps,
} from '@hyperflow/chakra-ui'
import { useParams } from 'react-router'

function ProjectApprovalPanel({ title = 'Review action' }: ApprovalPanelProps) {
  const { sessionId } = useParams()
  const { session } = useSession(sessionId)
  const { request, approve, submitting } = useToolApproval(
    sessionId,
    session?.activeAgentId,
  )

  if (!request) return null

  return (
    <Box borderWidth="1px" borderRadius="lg" p="4">
      <Text fontWeight="medium">{title}</Text>
      <Text mt="1">{request.function.name}</Text>
      <Button mt="3" loading={submitting} onClick={() => approve()}>
        Continue
      </Button>
    </Box>
  )
}

export function SessionRequests() {
  return <HitlOverlay approvalPanelComponent={ProjectApprovalPanel} />
}

Guide

Keep request state in the HITL contract

HitlOverlay uses HitlGate to select the active request. InputPanel, ApprovalPanel, and AgentAuthPanel use their dedicated headless hooks for the request and its actions. A replacement panel should use the corresponding hook rather than create a second subscription or call the client directly.

Replace one panel at a time

Use inputPanelComponent, approvalPanelComponent, or agentAuthPanelComponent to replace only the request surface that needs different presentation. The other request kinds retain their default panels.

Keep the panel in the session route

The overlay resolves the current sessionId from the route. Render it inside the routed session page, alongside the timeline and Composer; it returns null when no request is pending.

For a complete headless walkthrough, see Handle human-in-the-loop flows.

Props

For the complete HitlOverlayProps type, see the @hyperflow/chakra-ui reference.

Related components

• InputPanel
• ApprovalPanel
• AgentAuthPanel