@hyperflow/react

/**
 * Configuration for the core Hyperflow app shell.
 *
 * This component wires the client provider, router, and navigation context
 * together so consumers can focus on route and layout composition.
 */
export interface AppCoreProps {
  /** Hyperflow client configuration passed to the singleton client. */
  config: ClientConfig;
  /** Public routes rendered by the app router, in the supplied order. */
  routes?: HyperflowRoute[];
  /** Navigation items exposed to layout components through context. */
  navItems?: NavItem[];
  /** Layout component used for protected routes. */
  layoutComponent: ComponentType<{
    children: ReactNode;
  }>;
  /** Component rendered on the login route. */
  loginComponent: ComponentType;
  /** Optional runtime-reload screen component. */
  runtimeReloadComponent?: ComponentType;
  /** Suspense fallback used while the client initializes. */
  fallback?: ReactNode;
}

interface HyperflowProviderProps {
  /** Hyperflow client configuration used to initialize the singleton client. */
  config: ClientConfig;
  /** Tree rendered once the client is ready. */
  children: ReactNode;
  /** Optional fallback rendered while initialization is suspended. */
  fallback?: ReactNode;
}

interface HyperflowRoute {
  /** Route path relative to the router root. */
  path: string;
  /** Component rendered when the route matches. */
  component: ComponentType;
  /** When true, the route requires authentication before rendering. */
  requireAuth?: boolean;
  /** When true, the route is rendered outside the main application layout. */
  noLayout?: boolean;
  /** Nested child routes rendered under this route. */
  children?: HyperflowRoute[];
}

interface NavItem {
  /** The route path associated with the navigation item. */
  path: string;
  /** The text label shown for the navigation item. */
  label: string;
  /** Optional icon component rendered next to the label. */
  icon?: ComponentType;
}

type UseAuth = {
  /**
   * Whether the initial current-user request has finished, including a failed
   * request.
   */
  initialized: boolean;
  /** Authenticated user, or undefined when no user is available. */
  authUser: User | undefined;
  /** Authentication mode configured by the server. */
  authMode: AuthMode;
  /** Whether the current-user request is in progress. */
  fetching: boolean;
  /** Whether a login request is in progress. */
  authorizing: boolean;
  /**
   * Signs in with the supplied credentials and resolves to the authorization result.
   */
  login: (credentials: AuthorizeInput) => Promise<AuthorizeResult>;
  /** Clears the authenticated session and starts the logout flow. */
  logout: () => void;
};

type UseLogin = {
  /**
   * Signs in with the supplied credentials and resolves to the authorization result.
   */
  login: (credentials: AuthorizeInput) => Promise<AuthorizeResult>;
  /** Error from the login request, or undefined when no login error is recorded. */
  error?: Error | undefined;
  /** Whether a login request is in progress. */
  authorizing: boolean;
};

type UseLogout = {
  /** Clears the authenticated session and starts the logout flow. */
  logout: () => void;
};

type UseAuthUser = {
  /** Authenticated user, or undefined when no user is available. */
  authUser: User | undefined;
  /** Whether the current-user request is in progress. */
  fetching: boolean;
  /** Whether a login request is in progress. */
  authorizing: boolean;
  /**
   * Reloads the current user and resolves to the user, or undefined when unavailable.
   */
  fetchAuthUser: () => Promise<User | undefined>;
};

type UseMyAccount = {
  /** Current account details, or undefined when no user is available. */
  authUser: User | undefined;
  /** Whether the current-user request is in progress. */
  fetching: boolean;
  /** Whether an account-details update is in progress. */
  saving: boolean;
  /** Whether a password change is in progress. */
  changingPassword: boolean;
  /** Error from an account operation, or undefined when none is recorded. */
  error?: Error | undefined;
  /** Saves the supplied account details and resolves to the updated user. */
  updateMyAccount: (input: UpdateMyAccountInput) => Promise<User>;
  /** Changes the account password using the supplied current and new credentials. */
  changePassword: (input: ChangePasswordInput) => Promise<void>;
};

interface AuthUserProps {
  /** Render prop receiving the current auth state. */
  children?: (props: UseAuth) => React.ReactNode;
}

type UseSidebar = {
  /** Current session grouping preference. */
  groupBy: ListSessionsGroupBy;
  /** Changes the grouping preference used to fetch and display the session list. */
  setGroupBy: (groupBy: ListSessionsGroupBy) => void;
  /** Current session ordering preference. */
  sortBy: SessionListSortBy;
  /** Changes the ordering preference used to fetch the session list. */
  setSortBy: (sortBy: SessionListSortBy) => void;
  /** Clears the unread marker for the supplied session id. */
  markSessionRead: (sessionId: string) => void;
  /**
   * Display groups for the selected grouping mode, or null when the list is
   * ungrouped.
   */
  groups: SessionListGroup[] | null;
  /** Sessions currently loaded in the sidebar list. */
  sessions: ReturnType<typeof useSessionStore.getState>["sessions"];
  /** Whether the first page of sessions is being fetched. */
  loading: boolean;
  /** Whether an additional page of sessions is being fetched. */
  loadingMore: boolean;
  /** Whether another page of sessions is available. */
  hasMore: boolean;
  /** Session-list request error, or undefined when no list error is recorded. */
  error?: Error | undefined;
  /** Reloads the first page using the current grouping and ordering preferences. */
  refetch: () => Promise<void>;
  /** Loads the next page when more sessions are available. */
  loadMore: () => Promise<void>;
  /** Creates a session from the supplied input and resolves to the new session. */
  createSession: ReturnType<typeof useSessionActions>["createSession"];
  /** Updates the session identified by id and resolves to the updated session. */
  updateSession: ReturnType<typeof useSessionActions>["updateSession"];
  /**
   * Moves a session to the supplied custom group; null removes its custom-group
   * assignment.
   */
  moveSessionToGroup: ReturnType<typeof useSessionActions>["moveSessionToGroup"];
  /** Deletes the session identified by id. */
  deleteSession: ReturnType<typeof useSessionActions>["deleteSession"];
  /**
   * Sets the title of the session identified by id and resolves to the updated
   * session.
   */
  renameSession: ReturnType<typeof useSessionActions>["renameSession"];
  /** Creates a named custom group and resolves to the created group. */
  createCustomGroup: (name: string) => Promise<SessionCustomGroup>;
  /** Renames the custom group identified by id and resolves to the updated group. */
  updateCustomGroup: (id: string, name: string) => Promise<SessionCustomGroup>;
  /** Deletes the custom group identified by id. */
  deleteCustomGroup: (id: string) => Promise<void>;
  /** Available custom session groups. */
  customGroups: SessionCustomGroup[];
  /** Whether custom session groups are being fetched. */
  customGroupsLoading: boolean;
  /** Custom-group request error, or undefined when none is recorded. */
  customGroupsError?: Error | undefined;
};

type UseRowIndicators = {
  /** Whether the session is currently generating a response. */
  isGenerating: boolean;
  /** Whether the session has unread activity; false for the active session. */
  hasUnread: boolean;
  /** Status feedback for the row, or null when disabled or no indicator applies. */
  statusIndicator: SessionStatusIndicator | null;
};

type UseSessions = {
  /** Sessions loaded for the current list query. */
  sessions: ReturnType<typeof useSessionStore.getState>["sessions"];
  /** Server-provided session groups, or null for an ungrouped list. */
  sessionGroups: ReturnType<typeof useSessionStore.getState>["sessionGroups"];
  /** Whether the first page is being fetched. */
  loading: boolean;
  /** Whether the next page is being fetched. */
  loadingMore: boolean;
  /** Whether another page is available. */
  hasMore: boolean;
  /** List request error, or undefined when none is recorded. */
  error?: Error | undefined;
  /** Reloads the first page for the current query. */
  refetch: () => Promise<void>;
  /** Loads the next page when more sessions are available. */
  loadMore: () => Promise<void>;
};

type UseSession = {
  /**
   * Cached session details, falling back to the list entry; undefined when the
   * session is unavailable.
   */
  session: Session | undefined;
  /** Whether the session details are being fetched; false without a session id. */
  loading: boolean;
  /** Session-details request error, or undefined when none is recorded. */
  error?: Error | undefined;
  /** Reloads the session details; does nothing without a session id. */
  refetch: () => Promise<void>;
};

type UseSessionActions = {
  /** Creates a session from the supplied input and resolves to the new session. */
  createSession: (input: CreateSessionInput) => Promise<Session>;
  /** Updates the session identified by id and resolves to the updated session. */
  updateSession: (id: string, input: UpdateSessionInput) => Promise<Session>;
  /**
   * Moves a session to the supplied custom group; null removes its custom-group
   * assignment.
   */
  moveSessionToGroup: (id: string, customGroupId: string | null) => Promise<Session>;
  /** Deletes the session identified by id. */
  deleteSession: (id: string) => Promise<void>;
  /**
   * Sets the title of the session identified by id and resolves to the updated
   * session.
   */
  renameSession: (id: string, title: string) => Promise<Session>;
};

type UseSendSessionMessage = {
  /**
   * Creates a user message in the supplied session and starts the agent response;
   * accepts plain text or a structured message input.
   */
  send: (
    sessionId: string,
    input: SendSessionMessageInput | string,
    options?: SendSessionMessageOptions,
  ) => Promise<void>;
  /**
   * Whether this hook instance is submitting a message; does not represent the full
   * response stream.
   */
  sending: boolean;
  /**
   * Message-submission error, or undefined before submission or after the next
   * attempt begins.
   */
  error: Error | undefined;
};

type UseAbortSessionAct = {
  /**
   * Requests cancellation of the active response; does nothing without a session id.
   */
  abortAct: () => Promise<void>;
  /**
   * Whether this hook is issuing the abort request; does not wait for the response
   * stream to stop.
   */
  aborting: boolean;
  /** Error while issuing the abort request, or undefined when none is recorded. */
  error: Error | undefined;
};

type UseBackgroundTasks = {
  /** Background tasks for the selected session; empty without a session id. */
  tasks: BackgroundTask[];
  /** Whether the session task list is being fetched; false without a session id. */
  loading: boolean;
  /** Task-list request error, or undefined when none is recorded. */
  error?: Error | undefined;
  /** Reloads the task list; does nothing without a session id. */
  refresh: () => Promise<void>;
  /**
   * Requests cancellation of the task identified by taskId; does nothing without a
   * session id.
   */
  cancel: (taskId: string) => Promise<void>;
  /** Deletes the task identified by taskId; does nothing without a session id. */
  remove: (taskId: string) => Promise<void>;
  /** Deletes all tasks whose status is not running. */
  clearFinished: () => Promise<void>;
};

/** Session alert hook return shape. */
export type UseSessionAlert = {
  /**
   * Alert for unresolved user intervention or provider-login recovery failure; kind
   * is none when no alert is needed.
   */
  alert: SessionAlertState;
};

/** Visible session alert state for shell and skin consumers. */
export type SessionAlertState =
  | {
      kind: "none";
    }
  | {
      kind: "intervention_unavailable";
    }
  | {
      kind: "provider_login_error";
      message: string;
    };

type SessionListSortBy = "createdAt" | "lastActivityAt";

type SessionStatusIndicator = "need_user_input" | "error";

{ enabled: boolean; text: string }

{
  text: string;
  setText: (value: string) => void;
  attachments: File[];
  attachmentItems: {
    id: string;
    file: File;
    name: string;
    remove: () => void;
    preparation: DocumentAttachmentState | undefined;
    retry: () => void;
  }[];
  addAttachments: (files: File[]) => void;
  onAttachmentsChange: ChangeEventHandler<HTMLInputElement>;
  attachmentsInputProps: {
    type: "file";
    multiple: boolean;
    accept: string;
    disabled: boolean;
    onChange: ChangeEventHandler<HTMLInputElement>;
  };
  removeAttachment: (index: number) => void;
  resetAttachments: () => void;
  reset: () => void;
  snapshot: () => { text: string; attachments: File[] };
  replace: (snapshot: { text: string; attachments: File[] }) => void;
  trimmed: string;
  canSubmit: boolean;
}

{
  draftKey: string;
  value: string;
  revision: number;
  setValue: (value: string) => void;
  onLiveValueChange: (value: string) => void;
  disabled: boolean;
  placeholder: string;
  onChange: ChangeEventHandler<HTMLTextAreaElement>;
  onKeyDown: KeyboardEventHandler<HTMLTextAreaElement>;
  onDragOver: DragEventHandler<HTMLElement>;
  onDrop: DragEventHandler<HTMLElement>;
  onPaste: ClipboardEventHandler<HTMLTextAreaElement>;
  props: {
    value: string;
    disabled: boolean;
    placeholder: string;
    onChange: ChangeEventHandler<HTMLTextAreaElement>;
    onKeyDown: KeyboardEventHandler<HTMLTextAreaElement>;
    onDragOver: DragEventHandler<HTMLElement>;
    onDrop: DragEventHandler<HTMLElement>;
    onPaste: ClipboardEventHandler<HTMLTextAreaElement>;
  };
}

{
  canSubmit: boolean;
  isBusy: boolean;
  onSubmit: SubmitEventHandler<HTMLFormElement>;
  submit: (options?: ComposerSubmitOptions) => Promise<ComposerSubmitResult>;
}

{
  components: SessionOptionsComponent[];
  controls: ComposerSessionOptionControl[];
}

type UseComposer = ReturnType<typeof useComposer>;

type UseContextWindowMeterOptions = {
  /** Context-window control supplied by useComposer.slotControls. */
  slot: ComposerSlotControls["contextWindow"];
  /**
   * Whether to refresh usage automatically when the provider changes. Defaults to
   * false.
   */
  refreshProviderUsage?: boolean | undefined;
};

type UseContextWindowMeterResult = {
  /** Context-window usage, capacity, and breakdown derived from the supplied slot. */
  view: ContextWindowMeterView;
  /**
   * Indicator geometry and labels, or null when usage data or capacity is
   * unavailable.
   */
  indicatorModel: ContextWindowIndicatorModel | null;
  /** Provider plan-usage entries available for display. */
  planUsageItems: PlanUsageItem[];
  /** Whether a provider is known and usage is loading, has entries, or has an error. */
  shouldShowPlanUsage: boolean;
};

type AgentOption =
  | {
      type: "agent";
      id: string;
      name: string;
      description?: string | null;
    }
  | {
      type: "separator";
    };

declare function buildAgentMenu(
  agentSelectorSlot: ComposerComponent | undefined,
  agents: Record<string, ComposerResourceLink>,
): AgentOption[];

declare function buildModelMenu(groups: ComposerModelGroup[]): ModelGroupOption[];

/** Runtime agent mode projected for composer mode selectors. */
export type ComposerAgentModeOption = AgentMode & {
  label: string;
  description?: string | undefined;
};

type ComposerResourceLink = {
  name: string;
  description?: string | null;
};

type ComposerSessionOptionControl =
  | {
      c: "agent_selector";
      component: Extract<
        SessionOptionsComponent,
        {
          c: "agent_selector";
        }
      >;
      slot: ComposerSlotControls["agent"];
    }
  | {
      c: "model_selector";
      component: Extract<
        SessionOptionsComponent,
        {
          c: "model_selector";
        }
      >;
      slot: ComposerSlotControls["model"];
    }
  | {
      c: "toolhost_selector";
      component: Extract<
        SessionOptionsComponent,
        {
          c: "toolhost_selector";
        }
      >;
      slot: ComposerSlotControls["toolhost"];
    }
  | {
      c: "tool_policy_selector";
      component: Extract<
        SessionOptionsComponent,
        {
          c: "tool_policy_selector";
        }
      >;
      slot: ComposerSlotControls["approvalPolicy"];
    };

/** UI controls projected for the independent composer selector components. */
export type ComposerSlotControls = {
  agent: {
    /** Backend display region for this control. */
    display: ComposerSlotDisplay;
    value: string;
    label: string;
    options: ReturnType<typeof buildAgentMenu>;
    selectOptions: Array<{
      value: string;
      label: string;
      description?: string;
    }>;
    setValue: (agentId: string) => Promise<void>;
    selectProps: {
      value: string;
      disabled: boolean;
      onChange: ChangeEventHandler<HTMLSelectElement>;
    };
  };
  model: {
    /** Backend display region for this control. */
    display: ComposerSlotDisplay;
    value: ReturnType<typeof readModelSelection>;
    label: string;
    options: ReturnType<typeof buildModelMenu>;
    selectedProvider: ReturnType<typeof buildModelMenu>[number] | undefined;
    selectedModel:
      | ReturnType<typeof buildModelMenu>[number]["models"][number]
      | undefined;
    modelOptions: ReturnType<typeof buildModelMenu>[number]["models"];
    thinkingOptions: ReturnType<
      typeof buildModelMenu
    >[number]["models"][number]["thinkingOptions"];
    thinkingVisible: boolean;
    reasoningSupported: boolean;
    attachmentsSupported: boolean;
    setValue: (selection: ReturnType<typeof readModelSelection>) => Promise<void>;
    setProvider: (provider: string) => Promise<void>;
    setModel: (modelId: string, provider?: string | undefined) => Promise<void>;
    setThink: (think: string) => Promise<void>;
    providerSelectProps: {
      value: string;
      disabled: boolean;
      onChange: ChangeEventHandler<HTMLSelectElement>;
    };
    modelSelectProps: {
      value: string;
      disabled: boolean;
      onChange: ChangeEventHandler<HTMLSelectElement>;
    };
    thinkingSelectProps: {
      value: string;
      disabled: boolean;
      onChange: ChangeEventHandler<HTMLSelectElement>;
    };
  };
  toolhost: {
    /** Backend display region for this control. */
    display: ComposerSlotDisplay;
    value: string | null;
    selectValue: string;
    label: string;
    options: ComposerToolhostOption[];
    selectOptions: Array<{
      value: string;
      label: string;
      description?: string;
    }>;
    toolResources: Record<string, ResourceLink>;
    toolResourcesLoading: boolean;
    loading: boolean;
    setValue: (toolhost: string | null) => Promise<void>;
    dismissToolhost: (name: string) => void;
    selectProps: {
      value: string;
      disabled: boolean;
      onChange: ChangeEventHandler<HTMLSelectElement>;
    };
  };
  contextWindow: {
    /** Backend display region for this control. */
    display: ComposerSlotDisplay;
    /**
     * Latest synchronized session context accounting, when session sync is mounted.
     */
    contextWindow?: ContextWindowState | null | undefined;
    /**
     * Selected model context-window capacity used when runtime accounting is
     * unavailable.
     */
    catalogContextWindow?: number | null | undefined;
    provider?: string | undefined;
    usageProvider?: string | undefined;
    providerUsageResponse?: ProviderUsageResponse | undefined;
    providerUsageLoading: boolean;
    providerUsageError?: Error | undefined;
    refreshProviderUsage: () => Promise<void>;
  };
  approvalPolicy: {
    /** Backend display region for this control. */
    display: ComposerSlotDisplay;
    value: ApprovalPolicy;
    label: string;
    modeName: string | null;
    modes: ComposerAgentModeOption[];
    options: Array<{
      value: ApprovalPolicy;
      label: string;
      description?: string;
    }>;
    setValue: (policy: string) => Promise<void>;
    setMode: (mode: ComposerAgentModeOption) => Promise<void>;
    selectProps: {
      value: ApprovalPolicy;
      disabled: boolean;
      onChange: ChangeEventHandler<HTMLSelectElement>;
    };
  };
  status: {
    updating: boolean;
    error?: Error | undefined;
  };
};

type ComposerSlotDisplay =
  | "left"
  | "right"
  | "top-left"
  | "top-right"
  | "bottom-left"
  | "bottom-right"
  | "none";

/** Per-submit controls for composer routing behavior. */
export type ComposerSubmitOptions = {
  /** Skips automatic navigation after a new session is created. */
  disableNavigate?: boolean | undefined;
  /** Overrides the route used after a new session is created. */
  navigateTo?: string | undefined;
};

/** Result returned by a composer submission attempt. */
export type ComposerSubmitResult = {
  submitted: boolean;
  session?: Session | undefined;
};

type ComposerToolhostCategory = "computer" | "server" | "cloud" | "shared";

/** Toolhost option projected from runtime metadata for composer renderers. */
export type ComposerToolhostOption = ToolhostInfo & {
  /** Selectable value passed back to the session update. */
  value: string;
  /** Default headless label; skins may derive richer labels from metadata. */
  label: string;
  /** Semantic runtime category for skins that group toolhosts. */
  category: ComposerToolhostCategory;
  /** False when the runtime reports that the toolhost is no longer connected. */
  available: boolean;
  /** Tool names enriched with runtime descriptions when available. */
  toolItems: ComposerToolhostTool[];
  /** Runtime tools known by the agent but not exposed by this toolhost. */
  missingTools: ComposerToolhostTool[];
  /** Optional secondary text for headless renderers. */
  description?: string | null;
};

type ComposerToolhostTool = ComposerResourceLink;

type ContextWindowBreakdownItem = {
  key: ContextWindowBreakdownKey;
  tokens: number;
};

type ContextWindowBreakdownKey =
  | "systemPrompt"
  | "toolDefinitions"
  | "messages"
  | "promptOverhead";

type ContextWindowIndicatorModel = {
  progress: number;
  percent: number;
  resolvedUsedTokens: number;
  breakdownItems: ContextWindowBreakdownItem[];
};

type ContextWindowMeterView = {
  hasData: boolean;
  value: number;
  usedTokens: number | null;
  maxTokens: number | null;
  breakdown: ContextWindowBreakdownItem[];
  provider?: string | undefined;
};

type ModelGroupOption = {
  value: string;
  label: string;
  models: ModelOption[];
};

type ModelOption = {
  value: string;
  label: string;
  thinkingOptions: ThinkOption[];
};

type ModelSelection = {
  provider: string;
  modelId: string;
  think: string;
};

type PlanUsageItem = {
  entityLabel: string;
  windowLabel?: string | undefined;
  percent: number;
  used?: number | null | undefined;
  limit?: number | null | undefined;
  remainingPercent?: number | null | undefined;
  resetAt?: string | null | undefined;
  unit?: string | null | undefined;
  plan?: string | null | undefined;
  status: ProviderUsageStatus;
  error?: string | null | undefined;
  providerKey: string;
  segments: readonly PlanUsageSegment[];
};

type PlanUsageSegment = {
  label: string;
  percent: number;
  providerKey: string;
};

declare function readModelSelection(
  groups: ComposerModelGroup[],
  models: ComposerModel[],
  modelId: string,
  think: ThinkMode | null | undefined,
  chatClientRef: string | null,
): ModelSelection;

type SlotRenderer<TSlot> = ComponentType<{
  slot: TSlot;
  disabled?: boolean;
}>;

type ThinkOption = {
  value: string;
  label: string;
};

type UseTimeline = {
  /**
   * Ordered semantic history and live entries ready to render, including messages,
   * tools, and execution feedback.
   */
  entries: readonly TimelineEntry[];
  /**
   * Initial-history loading, failure, and empty-state flags, with the history request
   * error when present.
   */
  status: TimelineStatus;
  /** Availability, loading state, and a load action for older responses. */
  history: TimelineHistory;
  /**
   * Session-scoped background tasks and their refresh, cancel, remove, and
   * clear-finished actions.
   */
  backgroundTasks: TimelineBackgroundTasks;
};

type SendSessionMessageInput = {
  text: string;
  attachments?: File[];
  draftKey?: string;
};

type SendSessionMessageOptions = {
  /**
   * Overrides automatic naming of untitled sessions with title generation enabled on
   * their first message.
   */
  generateTitle?: boolean;
};

/**
 * In-progress assistant response accumulated from `session.response.delta` events.
 *
 * Keyed by act id in `SessionStore.streamingDrafts`.
 */
export type StreamingDraft = {
  actId: string;
  itemId?: string | null;
  content: string;
  reasoningActivities?: ReasoningActivity[];
  thinking: string;
  toolCallArgs: Record<string, string>;
  toolCallNames: Record<string, string>;
  toolOutputs: Record<string, ToolOutputContent[]>;
  phases?: StreamingPhase[];
  lastSeq?: number;
};

type StreamingPhase =
  | {
      kind: "thinking";
      offset: number;
      itemId?: string | null;
      seq?: number;
    }
  | {
      kind: "content";
      itemId?: string | null;
      seq?: number;
    }
  | {
      kind: "tool";
      callId: string;
      itemId?: string | null;
      seq?: number;
    };

type TimelineBackgroundTasks = {
  /** Background tasks belonging to the session. */
  tasks: BackgroundTask[];
  /** Whether the session's background-task list is being fetched. */
  loading: boolean;
  /** Task-list request error, or undefined when none is recorded. */
  error?: Error | undefined;
  /** Reloads the session's background tasks. */
  refresh: () => Promise<void>;
  /** Requests cancellation of a task by id. */
  cancel: (taskId: string) => Promise<void>;
  /** Deletes a task by id. */
  remove: (taskId: string) => Promise<void>;
  /** Deletes every task whose status is not running. */
  clearFinished: () => Promise<void>;
};

type TimelineEntry =
  | {
      id: string;
      kind: "user_message";
      item: SessionItem;
      text: string;
      /** Whether this user message is a valid rewind/fork pivot. */
      historyActionsAvailable: boolean;
    }
  | {
      id: string;
      kind: "assistant_message";
      item: SessionItem;
      text: string;
      /** Whether this is the final assistant message in a completed user turn. */
      isLastInTurn: boolean;
    }
  | {
      id: string;
      kind: "session_change";
      item: SessionItem;
    }
  | {
      id: string;
      kind: "compaction";
      item: SessionItem;
    }
  | {
      id: string;
      kind: "tool_group";
      pairs: ToolCallPair[];
      toolResources: Record<string, ResourceLink>;
      streaming: boolean;
    }
  | {
      id: string;
      kind: "draft";
      draft: StreamingDraft;
    }
  | {
      id: string;
      kind: "thinking";
      text: string;
      streaming: boolean;
    }
  | {
      id: string;
      kind: "streaming_message";
      content: string;
    }
  | {
      id: string;
      kind: "work_duration";
      startedAt?: string | undefined;
      hidden?: boolean | undefined;
    }
  | {
      id: string;
      kind: "background_task_group";
      /** Whether this task was received through a live update in this page lifetime. */
      live?: boolean | undefined;
      tasks: Array<{
        item: SessionItem;
        taskId: string;
        task?: BackgroundTask | undefined;
      }>;
    }
  | {
      id: string;
      kind: "background_task_completed";
      item: SessionItem;
      taskId?: string | undefined;
      task?: BackgroundTask | undefined;
    }
  | {
      id: string;
      kind: "session_error";
      message: string;
    }
  | {
      id: string;
      kind: "act_error";
      actId: string;
      message: string;
    }
  | {
      id: string;
      kind: "act_note";
      actId: string;
      message: string;
    };

type TimelineHistory = {
  /** Whether the server has older responses available to fetch. */
  hasOlder: boolean;
  /** Whether an older-history page is being fetched. */
  isLoading: boolean;
  /** Requests the next page of older responses. */
  loadOlder: () => void;
};

type TimelineStatus = {
  /** Whether initial history is loading and no entries are available yet. */
  isLoading: boolean;
  /** Whether history loading has failed, after initial loading finishes. */
  isError: boolean;
  /** Whether there are no entries and neither loading nor error feedback applies. */
  isEmpty: boolean;
  /** Initial-history request error, or undefined when none is recorded. */
  error?: Error | undefined;
};

type ToolCallPair = {
  call: SessionItem;
  output?: SessionItem | undefined;
};

type ToolLabelContext = {
  locale?: string;
  answeredToolCallIds?: ReadonlySet<string>;
};

type UseHitl = {
  /**
   * Request kind to display, prioritizing tool input, tool approval, then agent
   * authentication; null when none is pending.
   */
  kind: HitlKind | null;
  /**
   * Pending requests for all three interaction kinds; each missing request is
   * undefined.
   */
  requests: HitlRequests;
};

type HitlGateProps = {
  /**
   * Session whose pending interaction should be rendered; undefined selects no
   * session.
   */
  sessionId: string | undefined;
  /** Render callback receiving the selected interaction kind and pending requests. */
  children: (state: HitlGateState) => React.ReactNode;
};

{
  questions: InputRequestQuestion[];
  contentType: ToolInputContentType;
  answers: string[];
  getAnswer: (index: number) => string;
  step: number;
  allAnswered: boolean;
  isLastStep: boolean;
  continueDisabled: boolean;
}

{
  value: string;
  setValue: (value: string) => void;
  setDraftValue: (value: string) => void;
  disabled: boolean;
  onChange: ChangeEventHandler<HTMLTextAreaElement>;
  props: {
    value: string;
    disabled: boolean;
    onChange: ChangeEventHandler<HTMLTextAreaElement>;
  };
  draftProps: {
    defaultValue: string;
    disabled: boolean;
    onChange: ChangeEventHandler<HTMLTextAreaElement>;
  };
}

{
  canSubmit: boolean;
  onSubmit: (event: Pick<Event, "preventDefault">) => Promise<void>;
  props: { onSubmit: (event: Pick<Event, "preventDefault">) => Promise<void> };
}

{
  setAnswer: (index: number, value: string) => void;
  setAnswerDraft: (index: number, value: string) => void;
  setStep: Dispatch<SetStateAction<number>>;
  submit: () => Promise<void>;
  continue: () => void;
}