The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
import { type ReactNode, useMemo, useState } from 'react'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
import { Switch } from '@/components/ui/switch'
import { Textarea } from '@/components/ui/textarea'
import { useI18n } from '@/i18n'
import { Loader2, Save, SlidersHorizontal } from '@/lib/icons'
import { cn } from '@/lib/utils'
import type { PluginSettingField, PluginSettingFieldType } from '@/store/agent-plugins'
import { CONTROL_TEXT } from './constants'
import { ListRow, Pill, SectionHeading } from './primitives'
// A plugin manifest's `config_schema` rendered as a form. Every non-secret
// value is edited as TEXT (the draft) and coerced to its wire type on save, so a
// half-typed number never fights the input; secrets are drafted separately and
// only ever sent to the `.env` credential route by the caller.
export type PluginSettingsDraft = Record<string, string>
export interface PluginSettingsSave {
values: Record<string, unknown>
secrets: Record<string, string>
}
interface ControlProps {
field: PluginSettingField
id: string
raw: string
disabled: boolean
onChange: (raw: string) => void
/** Localised hint for a secret that already has a stored value. */
secretSetHint: string
}
// Words a humanized key keeps upper-case ("maps_api_key" → "Maps API key").
const KEY_ACRONYMS = new Set([
'ai',
'api',
'cpu',
'css',
'dns',
'gpu',
'html',
'http',
'https',
'id',
'ip',
'json',
'llm',
'mcp',
'oauth',
'sql',
'ssh',
'ssl',
'tls',
'tts',
'ui',
'uri',
'url',
'xml'
])
const ACRONYM_SPELLING: Record<string, string> = { ids: 'IDs', oauth: 'OAuth', urls: 'URLs' }
/** A config key as a sentence-case label: `daily_budget` → "Daily budget",
* `maps_api_key` → "Maps API key", `webhookURL` → "Webhook URL". */
export function humanizeSettingKey(key: string): string {
const words = key
.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
.split(/[\s_.\-/]+/)
.filter(Boolean)
return words
.map((word, index) => {
const lower = word.toLowerCase()
if (ACRONYM_SPELLING[lower]) {
return ACRONYM_SPELLING[lower]
}
if (KEY_ACRONYMS.has(lower)) {
return lower.toUpperCase()
}
return index === 0 ? lower.charAt(0).toUpperCase() + lower.slice(1) : lower
})
.join(' ')
}
/** The row label: the manifest's `label`/`title` when it gave one (the backend
* falls back to the bare key), else the key humanized. */
export function fieldLabel(field: Pick<PluginSettingField, 'key' | 'label'>): string {
const label = field.label.trim()
return label && label !== field.key ? label : humanizeSettingKey(field.key)
}
/** Helper copy from independent sentences (a plugin's description, the secret
* storage note): each part ends its sentence before the next begins. */
export function joinSentences(...parts: (null | string | undefined)[]): string {
const kept = parts.map(part => part?.trim() ?? '').filter(Boolean)
return kept
.map((part, index) => (index < kept.length - 1 && !/[.!?。!?…:;]$/.test(part) ? `${part}.` : part))
.join(' ')
}
/** What the input shows before the user touches it. */
const INITIAL_TEXT: Record<PluginSettingFieldType, (field: PluginSettingField) => string> = {
boolean: field => (field.value === true ? 'true' : 'false'),
enum: field => String(field.value ?? field.choices?.[0] ?? ''),
json: field => (field.value === undefined || field.value === null ? '' : JSON.stringify(field.value, null, 2)),
number: field => (field.value === undefined || field.value === null ? '' : String(field.value)),
secret: () => '',
string: field => String(field.value ?? '')
}
/** Text → wire value; a thrown Error is the field's validation message. */
const COERCE: Record<Exclude<PluginSettingFieldType, 'secret'>, (raw: string, field: PluginSettingField) => unknown> = {
boolean: raw => raw === 'true',
enum: (raw, field) => {
if (!field.choices?.includes(raw)) {
throw new Error(`${fieldLabel(field)}: not one of ${field.choices?.join(', ') ?? ''}`)
}
return raw
},
json: (raw, field) => {
const parsed: unknown = JSON.parse(raw || 'null')
if (parsed === null || typeof parsed !== 'object') {
throw new Error(`${fieldLabel(field)}: expected a JSON list or object`)
}
return parsed
},
number: (raw, field) => {
const n = Number(raw)
if (raw.trim() === '' || Number.isNaN(n)) {
throw new Error(`${fieldLabel(field)}: expected a number`)
}
return n
},
string: raw => raw
}
const TEXT_CLASS = cn('w-full', CONTROL_TEXT)
function StringControl({ disabled, id, onChange, raw }: ControlProps) {
return (
<Input
className={TEXT_CLASS}
disabled={disabled}
id={id}
onChange={e => onChange(e.currentTarget.value)}
value={raw}
/>
)
}
function NumberControl({ disabled, id, onChange, raw }: ControlProps) {
return (
<Input
className={TEXT_CLASS}
disabled={disabled}
id={id}
inputMode="decimal"
onChange={e => onChange(e.currentTarget.value)}
type="number"
value={raw}
/>
)
}
function BooleanControl({ disabled, field, id, onChange, raw }: ControlProps) {
return (
<Switch
aria-label={fieldLabel(field)}
checked={raw === 'true'}
disabled={disabled}
id={id}
onCheckedChange={on => onChange(on ? 'true' : 'false')}
/>
)
}
function EnumControl({ disabled, field, id, onChange, raw }: ControlProps) {
return (
<Select disabled={disabled} onValueChange={onChange} value={raw}>
<SelectTrigger aria-label={fieldLabel(field)} className={TEXT_CLASS} id={id}>
<SelectValue />
</SelectTrigger>
<SelectContent>
{(field.choices ?? []).map(choice => (
<SelectItem key={choice} value={choice}>
{choice}
</SelectItem>
))}
</SelectContent>
</Select>
)
}
function SecretControl({ disabled, field, id, onChange, raw, secretSetHint }: ControlProps) {
return (
<Input
autoComplete="off"
className={TEXT_CLASS}
data-env={field.env}
disabled={disabled}
id={id}
onChange={e => onChange(e.currentTarget.value)}
placeholder={field.has_value ? secretSetHint : ''}
type="password"
value={raw}
/>
)
}
function JsonControl({ disabled, id, onChange, raw }: ControlProps) {
return (
<Textarea
className={cn('min-h-28 resize-y bg-background font-mono', CONTROL_TEXT)}
disabled={disabled}
id={id}
onChange={e => onChange(e.currentTarget.value)}
spellCheck={false}
value={raw}
/>
)
}
/** Field type → control. Adding a manifest type means one row here, one in
* INITIAL_TEXT and one in COERCE — never a branch in the renderer. */
export const FIELD_CONTROLS: Record<PluginSettingFieldType, (props: ControlProps) => ReactNode> = {
boolean: BooleanControl,
enum: EnumControl,
json: JsonControl,
number: NumberControl,
secret: SecretControl,
string: StringControl
}
export function initialDraft(fields: PluginSettingField[]): PluginSettingsDraft {
return Object.fromEntries(fields.map(field => [field.key, INITIAL_TEXT[field.type](field)]))
}
/** Split a draft into the two payloads: coerced non-secret values that
* CHANGED, and non-blank secrets keyed by their `.env` name. Throws the first
* field's validation error. */
export function collectChanges(fields: PluginSettingField[], draft: PluginSettingsDraft): PluginSettingsSave {
const initial = initialDraft(fields)
const values: Record<string, unknown> = {}
const secrets: Record<string, string> = {}
for (const field of fields) {
const raw = draft[field.key] ?? ''
if (field.type === 'secret') {
if (raw && field.env) {
secrets[field.env] = raw
}
continue
}
if (raw !== initial[field.key]) {
values[field.key] = COERCE[field.type](raw, field)
}
}
return { values, secrets }
}
export function PluginSettingsForm({
fields,
idPrefix,
disabled,
intro,
onSave,
title
}: {
fields: PluginSettingField[]
idPrefix: string
disabled: boolean
/** Lead copy under the page heading (the plugin's description). */
intro?: ReactNode
/** Resolves true when everything landed; the form then re-seeds from `fields`. */
onSave: (changes: PluginSettingsSave) => Promise<boolean>
/** Page title; the Settings breadcrumb owns it, embedded callers show it. */
title: string
}) {
const { t } = useI18n()
const s = t.skills.plugins.settingsForm
const seed = useMemo(() => initialDraft(fields), [fields])
const [draft, setDraft] = useState<PluginSettingsDraft>(seed)
const [seedRef, setSeedRef] = useState(seed)
const [error, setError] = useState<null | string>(null)
const [saving, setSaving] = useState(false)
// The row's refreshed copy re-seeds the form (a saved value becomes the new baseline).
if (seedRef !== seed) {
setSeedRef(seed)
setDraft(seed)
}
const dirty = fields.some(field => (draft[field.key] ?? '') !== seed[field.key])
const save = async () => {
let changes: PluginSettingsSave
try {
changes = collectChanges(fields, draft)
} catch (e) {
setError(e instanceof Error ? e.message : String(e))
return
}
setError(null)
setSaving(true)
try {
if (await onSave(changes)) {
// Secrets are never echoed back; clear them so the placeholder shows "set".
setDraft(current =>
Object.fromEntries(
fields.map(field => [field.key, field.type === 'secret' ? '' : (current[field.key] ?? '')])
)
)
}
} finally {
setSaving(false)
}
}
return (
<form
data-testid={`${idPrefix}-settings-form`}
onSubmit={event => {
event.preventDefault()
void save()
}}
>
{/* The page's one action rides the heading row, like every Settings page
with a primary action (Passwords & Logins' Add): never mid-canvas. */}
<SectionHeading
aside={
<Button className="gap-1.5" disabled={disabled || saving || !dirty} size="sm" type="submit">
{saving ? <Loader2 className="size-3.5 animate-spin" /> : <Save className="size-3.5" />}
{s.save}
</Button>
}
icon={SlidersHorizontal}
page
title={title}
/>
{intro}
{error && (
<p className="mb-1 text-[length:var(--conversation-caption-font-size)] text-destructive" role="alert">
{error}
</p>
)}
<div>
{fields.map(field => {
const id = `${idPrefix}-${field.key}`
const Control = FIELD_CONTROLS[field.type]
const label = fieldLabel(field)
const control = (
<Control
disabled={disabled || saving}
field={field}
id={id}
onChange={raw => setDraft(current => ({ ...current, [field.key]: raw }))}
raw={draft[field.key] ?? ''}
secretSetHint={s.secretSet}
/>
)
const description =
joinSentences(field.description, field.type === 'secret' && field.env ? s.secretStoredAs(field.env) : '') ||
undefined
const rowTitle = (
<span className="inline-flex flex-wrap items-center gap-2">
<label htmlFor={id}>{label}</label>
{field.required && <Pill>{s.required}</Pill>}
</span>
)
// Editors too big for the control column take the full width under
// the description, as native config rows do.
return field.type === 'json' ? (
<ListRow
below={<div className="mt-3">{control}</div>}
data-tour={`plugin-field-${field.key}`}
description={description}
key={field.key}
title={rowTitle}
wide
/>
) : (
<ListRow
action={control}
data-tour={`plugin-field-${field.key}`}
description={description}
key={field.key}
title={rowTitle}
/>
)
})}
</div>
</form>
)
}