@agents-js/ui-components

Lit web components for ACP-aware chat interfaces. Drop-in surface with streaming, permissions, elicitation, auth, and theming.

Installation

bun add @agents-js/ui-components

API

Classes

• AcpAuthSelector
• AcpButton
• AcpChatApp
• AcpCheckbox
• AcpChoicePicker
• AcpCodeBlock
• AcpColumn
• AcpConnectDialog
• AcpDateTimeInput
• AcpDebugPanel
• AcpDiffBlock
• AcpDivider
• AcpElicitationForm
• AcpIcon
• AcpImage
• AcpMessage
• AcpModal
• AcpModelSelector
• AcpOverlayStack
• AcpPermissionModal
• AcpPermissionModeSelector
• AcpPlanPanel
• AcpPromptInput
• AcpRow
• AcpSlider
• AcpStatusBar
• AcpStreamingText
• AcpTerminalEmbed
• AcpTextField
• AcpToolCallDetail
• AcpToolKindIcon
• AcpTranscript
• AcpWriteGateModal
• ChatAppProfileManager
• HostWSClient
• PromptHistoryStore

Functions

• clearConnectPreferences — Clear stored connection preferences and profiles.
• clearIconRegistries — Clear all registered external icon sets, leaving only the built-in icons.
• createLocalStoragePromptHistoryPersistence
• createPermissionResolution
• deleteConnectProfile
• deriveDisplayedSessionStatus
• deriveFallbackModelId
• deriveRuntimeNotice
• deriveSessionState — Derive flat component properties from an incoming SessionStateLike. This is a pure function with no side effects — the caller is responsible for applying the result to Lit reactive properties with ...
• isHostBridgeActiveForTarget
• isKnownModelId
• loadConnectPreferences — Load previously saved connection preferences. Returns the active profile's preferences, or null if nothing valid was saved.
• loadConnectProfiles
• mapModels
• mapPendingElicitation — Map a raw PendingElicitation (as serialized by the gateway) into the display-only PendingElicitationInfo used by the browser. The gateway's JSON serializer strips the resolve function, so the...
• mapPermissionRequest — Map a raw RequestPermissionRequest object into the minimal PendingPermissionInfo shape expected by the UI components.
• mapRuntimeSwitchState
• mapSnapshot — Extract host-relevant fields from a full ACPSessionState snapshot. The snapshot arrives as the serialized ACPSessionState. The pending permission lives at currentTurn.pendingPermission.request wh...
• normalizeHostBridgeUrl
• reconcileModelSelection
• registerAllComponents — Marker function for hosts that prefer an explicit registerAllComponents() call after importing -js/ui-components. The function body is intentionally empty. Actual <acp-*> registration is ...
• registerIconSet — Register an external icon set. Icons from this registry take priority over the built-in set and previously registered sets.
• repairActiveSavedRuntimePreference
• resolveBrowserLaunchConfig
• safeCustomElement — Idempotent variant of Lit's `` decorator. Usage is identical to the Lit decorator: import { safeCustomElement } from "./safe-custom-element.ts"; ("acp-button") export class AcpButton extends LitEl...
• saveConnectPreferences — Save connection preferences into a named profile. If profileId is omitted, a new profile is created unless the store is empty, in which case the default profile ID is used.
• sessionViewStateChanged — Shallow-compare two SessionViewState objects. Returns true when at least one top-level value differs (meaning the component should re-render).
• setActiveConnectProfile
• shouldClearStaleSessionHash
• shouldRepairSavedRuntimeRestore
• statusCategory — Maps a session status string to a semantic category for styling.

Interfaces

• AcpChoiceOption
• AcpToolCallDetailData — Mirrors the shape of ActiveToolCall from the agents-js/a2a-client package without taking a runtime dependency on it — keeps ui-components framework-agnostic. Consumers can pass an `ActiveTool...
• AgentCardLike — Unified agent card shape — covers preview, snapshot, and view uses.
• BrowserLaunchConfig
• ChatAppDerivedState
• ConnectPreferences
• ConnectProfile
• ConnectProfilesState
• DebugRecordLike — Debug record shape — mirrors DebugRecord from a2a-client types.
• ElicitationResolution
• HistoryNavResult
• HostState — Flat state object pushed to subscribers on every relevant event.
• HostTurnSummary
• HostWSClientOptions — Optional behaviour hooks for {HostWSClient}. All fields are optional so existing new HostWSClient(url) call sites keep working unchanged. Omitting a hook leaves the corresponding surface inert.
• ModelInfo
• ModelInfoLike
• PendingElicitationInfo — Minimal elicitation request shape for display purposes. Mirrors the non-function fields of PendingElicitation on the host side (see packages/acp-host/src/types/session.ts). The gateway's JSON s...
• PendingPermissionInfo — Minimal permission request shape for display purposes.
• PendingWriteGateInfo — Minimal write-gate shape for display purposes.
• PermissionOptionInfo — Permission option shape matching /sdk PermissionOption.
• PermissionRequestLike — Minimal shape for permission requests from acp-host.
• PermissionResolution
• PlanEntryLike — Plan entry shape matching PlanEntryInfo from acp-host session state.
• ProfileManagerCallbacks
• ProfileManagerState
• PromptHistoryPersistence — A framework-agnostic prompt history store that provides up-arrow input recall. Extracted from an earlier host prompt-history state machine and generalized here. No DOM or Lit dependencies — pure Ty...
• PromptHistoryStoreOptions
• ResolveBrowserLaunchConfigOptions
• RuntimeInfo
• RuntimeInfoLike
• RuntimeModelInfo
• RuntimeModelLike — Model info from the runtime CLI (available before session creation).
• RuntimeSwitchState
• SaveConnectPreferencesOptions
• SessionModelsInfo
• SessionModelsLike
• SessionStateLike — Unified session state shape — covers snapshot and view uses.
• TargetInspectionLike
• TranscriptMessageEntryLike
• TranscriptToolCallEntryLike
• TranscriptToolCallEntryPayload — ActiveToolCall-shaped payload for transcript tool-call entries. Re-uses the SDK's typed shapes (ToolKind, ToolCallContent, ToolCallLocation) so receivers get spec-shaped enums and proper di...
• WorkflowActivityEntryState
• WorkflowSurfaceActivityState
• WorkflowSurfaceComposerState
• WorkflowSurfaceContext
• WorkflowSurfaceInterruptActionState
• WorkflowSurfaceInterruptState
• WorkflowSurfacePlanState
• WorkflowSurfaceRenderState
• WorkflowSurfaceTranscriptState
• WriteGateLike — Minimal shape for write gate pending state.
• WriteGateResolution

Types

• HostStateListener
• IconRegistry — Icon registry type: a record mapping icon names to SVG path data strings.
• PermissionModalDetail
• RuntimeSwitchOrigin
• SessionViewState — SessionViewState groups the derived state fields that drive the main chat view rendering. The component stores this as a single () property with a custom hasChanged guard instead of 17+ individ...
• TranscriptEntryLike — Discriminated union for transcript entries. Two variants today: - Message: a user or agent text message (the original TranscriptEntry shape from agents-js/a2a-client). Carries `role: "user"...
• WorkflowActivityKind
• WorkflowActivityStatus
• WorkflowSurfaceActivityPhase
• WorkflowSurfaceComposerMode
• WorkflowSurfaceInterruptKind
• WorkflowSurfaceSeverity
• WSServerMessage — Server-to-client messages sent by the ws-bridge.

Constants

• _typeFixtures
• acpInputStyles — Shared CSS for input and label elements used across form components. Provides consistent styling for <label>, <input>, <textarea>, and <select> elements including focus, disabled, and error...
• acpTheme — Shared Tokyo Night theme as CSS custom properties. Each property uses a double-var pattern: the component references var(--acp-bg, #0f1117) as the compiled default, but hosts can set --acp-bg o...
• DEFAULT_PERMISSION_MODE_LABELS — Default label copy for each mode. Consumers can override any subset via the labels property; missing keys fall back to these values.

Exports

• type AcpChoiceOption

Dependencies

• @agentclientprotocol/sdk
• @agents-js/a2ui-types
• @agents-js/acp-host
• @agents-js/schema-utils

Peer Dependencies

• lit

License

MIT