Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
24.9 KB
Raw Blame
'use client'

import React, { useEffect, useMemo, useRef, useState } from 'react'
import { CreateStepFlow } from '@components/CreateStepFlow'
import { useToast } from '@components/Toast'
import { Button, CheckboxField, Field, FormSection, SelectInput, TextInput } from '@components/ui'
import type { CredentialSchema, HookCapability, HostResource } from '@lib/api'
import { getHosts, getRegistryCredentialSchema, installHookFromRegistry } from '@lib/api'
import { buildPastedValue } from '@lib/pasteUtils'
import { getEmbeddedHookCredentialSchema } from '../registryInstallHelpers'
import {
  ALL_HOOK_CAPABILITIES,
  DEFAULT_HOOK_ORDER,
  ENFORCED_HOOK_CAPABILITIES,
  HOOK_CAPABILITY_OPTIONS,
  HOOK_INSTALL_ERROR_LABELS,
  ORDER_HINT_LABELS,
} from './constants'
import type { HookInstallFormProps } from './types'

const STEPS = ['Configure', 'Install'] as const

const STEP_DETAILS = [
  {
    description: 'Bind the guardrail hook',
    title: 'Guardrail hook',
    subtitle: 'Pick the target agent and configure how this hook runs.',
  },
  {
    description: 'Confirm install',
    title: 'Review install',
    subtitle: 'Check the guardrail hook install before applying it.',
  },
] as const

// A Host's guardrails.capabilityCeiling bounds which capabilities a hook may be
// granted. An absent ceiling is the empty set, not "unbounded": the install
// route reads it as `capabilityCeiling ?? []` and rejects anything requested
// against it, so granting must narrow to nothing here for the same Host.
//
// `null` means "no agent resolved yet" and is the one case that must not
// narrow, so the author's seed survives the load rather than being cleared
// before the selected Host has arrived. spec is typed AnyRecord in lib/api, so
// read it defensively and keep only the four known capability values.
function hostCapabilityCeiling(host: HostResource | undefined): HookCapability[] | null {
  if (!host) return null
  const guardrails = (host.spec as { guardrails?: { capabilityCeiling?: unknown } } | undefined)
    ?.guardrails
  const ceiling = guardrails?.capabilityCeiling
  if (!Array.isArray(ceiling)) return []
  return ceiling.filter((c): c is HookCapability =>
    ALL_HOOK_CAPABILITIES.includes(c as HookCapability)
  )
}

// Surface the install-hook route's { error, reason? } body. formatApiError stashes
// the parsed JSON on `.body` and the code on `.code`; fall back to the message.
function describeHookInstallError(err: unknown): string {
  const withBody = err as { code?: string; body?: Record<string, unknown>; message?: string }
  const code =
    withBody.code ?? (typeof withBody.body?.error === 'string' ? withBody.body.error : '')
  const reason = typeof withBody.body?.reason === 'string' ? withBody.body.reason : ''
  const base =
    (code && HOOK_INSTALL_ERROR_LABELS[code]) || (err instanceof Error ? err.message : '')
  const message = base || 'Failed to install guardrail hook'
  return reason ? `${message} (${reason})` : message
}

/**
 * What the author declared and the install will not get. Rendered at step 0,
 * where the operator can still act on it, and again in the review, which is the
 * last thing they see before Install.
 */
function DegradedGrantNotices({
  enforced,
  unenforced,
}: {
  enforced: HookCapability[]
  unenforced: HookCapability[]
}) {
  return (
    <>
      {enforced.length > 0 ? (
        <div className="cu-banner cu-banner--warning">
          This hook needs {enforced.join(', ')} to function. Without{' '}
          {enforced.length > 1 ? 'them' : 'it'}, it installs and reports Ready, but the actions it
          takes are discarded.
        </div>
      ) : null}
      {unenforced.length > 0 ? (
        <div className="cu-banner cu-banner--info">
          {enforced.length > 0 ? 'The author also lists' : 'The author lists'}{' '}
          {unenforced.join(', ')}, which the runtime does not enforce today: the hook behaves the
          same whether or not {unenforced.length > 1 ? 'they are' : 'it is'} granted.
        </div>
      ) : null}
    </>
  )
}

export function HookInstallForm({ entry, onCancel, onInstalled }: HookInstallFormProps) {
  const { showToast } = useToast()
  const [step, setStep] = useState(0)
  const [hosts, setHosts] = useState<HostResource[]>([])
  const [hostRef, setHostRef] = useState('')
  const [credSchema, setCredSchema] = useState<CredentialSchema | null>(null)
  const [credValues, setCredValues] = useState<Record<string, string>>({})
  const [capabilities, setCapabilities] = useState<Set<HookCapability>>(new Set())
  const [order, setOrder] = useState(String(DEFAULT_HOOK_ORDER))
  const [failMode, setFailMode] = useState<'open' | 'closed'>('open')
  // Owned here rather than inside FormSection: step 0's subtree unmounts on
  // Continue, so a disclosure holding its own state would forget it and come
  // back closed on Back, hiding the capabilities the operator just reviewed.
  const [advancedOpen, setAdvancedOpen] = useState(false)
  const [loading, setLoading] = useState(true)
  const [installing, setInstalling] = useState(false)
  const [error, setError] = useState('')
  const installInFlightRef = useRef(false)

  const hookMeta = entry.hook_meta ?? null
  const lifecyclePoints = useMemo(
    () => (Array.isArray(hookMeta?.lifecyclePoints) ? hookMeta.lifecyclePoints : []),
    [hookMeta]
  )
  // target.{image,service,remote} are objects on the wire — derive display strings.
  const targetImage = hookMeta?.target?.image?.ref ?? ''
  const svc = hookMeta?.target?.service
  const targetService = svc
    ? `${svc.namespace ? `${svc.namespace}/` : ''}${svc.name ?? ''}${svc.port ? `:${svc.port}` : ''}`
    : ''
  const targetRemote = hookMeta?.target?.remote?.baseUrl ?? ''

  // What the author says the hook needs. Publisher-supplied, so filter to the
  // known capability values — an unrecognised entry must degrade to "declared
  // nothing", never widen what the operator can grant.
  const declaredCapabilities = useMemo<HookCapability[]>(() => {
    const raw = hookMeta?.requiredCapabilities
    if (!Array.isArray(raw)) return []
    return raw.filter((c): c is HookCapability =>
      ALL_HOOK_CAPABILITIES.includes(c as HookCapability)
    )
  }, [hookMeta])

  const authorDefaults = hookMeta?.authorDefaults ?? null
  const authorFailMode =
    authorDefaults?.failMode === 'open' || authorDefaults?.failMode === 'closed'
      ? authorDefaults.failMode
      : null
  const authorOrderHint =
    typeof authorDefaults?.orderHint === 'string' ? authorDefaults.orderHint.trim() : ''

  useEffect(() => {
    installInFlightRef.current = false
    setStep(0)
    setError('')
    setCredValues({})
    setAdvancedOpen(false)
    autoOpenedRef.current = false
    // Seed from the author's declaration so the default install is the working
    // one. The ceiling effect below narrows this once an agent is selected, and
    // the operator can still untick anything.
    setCapabilities(new Set(declaredCapabilities))
    setOrder(String(DEFAULT_HOOK_ORDER))
    setFailMode(authorFailMode ?? 'open')
    setLoading(true)
    ;(async () => {
      try {
        const [schema, hostResult] = await Promise.all([
          getRegistryCredentialSchema(entry.name, entry.version).catch(() =>
            getEmbeddedHookCredentialSchema(entry)
          ),
          getHosts(),
        ])
        setCredSchema(schema)
        const hostItems = (hostResult.items ?? []).filter(h => !!h.metadata?.name)
        setHosts(hostItems)
        if (hostItems.length > 0) {
          setHostRef(prev => prev || (hostItems[0].metadata?.name ?? ''))
        }
      } catch (loadError) {
        setError(loadError instanceof Error ? loadError.message : 'Failed to load configuration')
      } finally {
        setLoading(false)
      }
    })()
  }, [entry])

  const selectedHost = useMemo(
    () => hosts.find(h => h.metadata?.name === hostRef),
    [hosts, hostRef]
  )
  const ceiling = useMemo(() => hostCapabilityCeiling(selectedHost), [selectedHost])

  // Drop any selected capability the newly selected agent does not allow. A
  // null ceiling is the not-yet-resolved agent, which narrows nothing.
  useEffect(() => {
    if (!ceiling) return
    setCapabilities(prev => {
      const next = new Set([...prev].filter(c => ceiling.includes(c)))
      return next.size === prev.size ? prev : next
    })
  }, [ceiling])

  // What is ticked, then what the agent permits — the second sentence applies
  // whether or not the author declared anything, so it is appended rather than
  // chosen between. An agent with no ceiling can grant nothing, so say that
  // plainly instead of pointing at a ceiling it does not have.
  const capabilitiesDescription = [
    declaredCapabilities.length > 0
      ? "Pre-selected from what the hook's author says it needs. Removing one does not stop the install — the hook runs without that power."
      : 'Grant only the capabilities this hook needs.',
    ceiling === null
      ? ''
      : ceiling.length === 0
        ? 'This agent has no capability ceiling, so no capability can be granted until one is set on the agent.'
        : "Only the capabilities within this agent's capability ceiling can be granted.",
  ]
    .filter(Boolean)
    .join(' ')

  // Declared capabilities the hook will not get — either the operator unticked
  // them or the agent's ceiling forbids them. Either way the hook is installed
  // less capable than its author says it needs.
  const missingDeclared = useMemo(
    () => declaredCapabilities.filter(c => !capabilities.has(c)),
    [declaredCapabilities, capabilities]
  )

  // Split by whether mcp-host actually withholds the action. The two cases
  // deserve different words: one silently breaks the hook, the other changes
  // nothing about how it runs today.
  const missingEnforced = missingDeclared.filter(c => ENFORCED_HOOK_CAPABILITIES.includes(c))
  const missingUnenforced = missingDeclared.filter(c => !ENFORCED_HOOK_CAPABILITIES.includes(c))

  // The capability grant lives behind a disclosure that ships closed, so an
  // operator can reach Install having never seen it. Open it the first time the
  // grant falls short of what the author declared — which is only knowable once
  // the agent's ceiling has loaded, so it cannot be a static default. Once per
  // entry: an operator who closes it again has answered the question.
  //
  // Not while loading: the seed is applied by an effect, so the first render
  // sees an empty selection and every declared capability as missing.
  const autoOpenedRef = useRef(false)
  useEffect(() => {
    if (loading || missingDeclared.length === 0 || autoOpenedRef.current) return
    autoOpenedRef.current = true
    setAdvancedOpen(true)
  }, [loading, missingDeclared])

  // may_deny ⇒ fail-closed, matching the backend deny_requires_fail_closed rule.
  const mustFailClosed = capabilities.has('may_deny')
  const effectiveFailMode: 'open' | 'closed' = mustFailClosed ? 'closed' : failMode

  const credHasKeys = (credSchema?.keys?.length ?? 0) > 0
  const credRequired = !!credSchema?.required && credHasKeys
  const credStarted =
    credRequired && credSchema!.keys.some(key => (credValues[key.name] ?? '').trim() !== '')
  const missingCredentialKeys =
    credRequired && credStarted
      ? credSchema!.keys
          .filter(key => !(credValues[key.name] ?? '').trim())
          .map(key => key.label || key.name)
      : []
  const credComplete = !credStarted || missingCredentialKeys.length === 0

  const orderValid = order.trim() === '' || Number.isFinite(Number(order))
  const canSubmit = hostRef.trim() !== '' && credComplete && orderValid && !installing
  const canContinue = step === 0 ? !loading && canSubmit : true

  function canSelectStep(targetStep: number) {
    if (targetStep <= step) return true
    return hostRef.trim() !== '' && credComplete && orderValid
  }

  function toggleCapability(value: HookCapability) {
    setCapabilities(prev => {
      const next = new Set(prev)
      if (next.has(value)) next.delete(value)
      else next.add(value)
      return next
    })
  }

  function pasteCredentialValue(keyName: string, event: React.ClipboardEvent<HTMLInputElement>) {
    const pasted = event.clipboardData.getData('text')
    if (!pasted) return
    event.preventDefault()
    const current = credValues[keyName] ?? ''
    const nextValue = buildPastedValue(current, pasted, event.currentTarget)
    setCredValues(previous => ({ ...previous, [keyName]: nextValue }))
  }

  async function handleInstall() {
    if (!canSubmit || installInFlightRef.current) return
    installInFlightRef.current = true
    setInstalling(true)
    setError('')
    try {
      const filled = credHasKeys
        ? Object.fromEntries(
            credSchema!.keys
              .map(key => [key.name, credValues[key.name] ?? ''])
              .filter(([, value]) => (value as string).trim() !== '')
          )
        : {}
      const credentials = Object.keys(filled).length > 0 ? filled : undefined
      const selectedCapabilities = [...capabilities]
      const parsedOrder = order.trim() === '' ? undefined : Number(order)

      const result = await installHookFromRegistry({
        hostRef,
        registryEntryName: entry.name,
        registryEntryVersion: entry.version,
        capabilities: selectedCapabilities.length > 0 ? selectedCapabilities : undefined,
        order: parsedOrder,
        failMode: effectiveFailMode,
        credentials,
      })
      showToast(
        `Installed guardrail hook "${result.hookName}" (trust: ${result.trustLevel}) on ${hostRef}.`,
        { tone: 'success' }
      )
      onInstalled(result.hookName)
    } catch (installError) {
      setError(describeHookInstallError(installError))
    } finally {
      installInFlightRef.current = false
      setInstalling(false)
    }
  }

  return (
    <CreateStepFlow
      ariaLabel="Install guardrail hook steps"
      className="cu-create-step-flow--2"
      currentStep={step}
      onStepChange={setStep}
      canSelectStep={canSelectStep}
      steps={STEP_DETAILS}
      stepLabels={STEPS}
      titleId="registry-hook-install-step-title"
    >
      {loading ? (
        <div className="cu-card">
          <div className="cu-card__body cu-muted">Loading installation configuration...</div>
        </div>
      ) : (
        <form
          onSubmit={event => {
            event.preventDefault()
            if (step < STEPS.length - 1) {
              if (canContinue) setStep(current => Math.min(STEPS.length - 1, current + 1))
              return
            }
            void handleInstall()
          }}
          className="cu-form-stack cu-agent-form-stack cu-agent-form-stack--wide"
        >
          {step === 0 ? (
            <>
              <FormSection
                title="Install guardrail hook from Marketplace"
                description={
                  <>
                    Bind <strong>{entry.name}</strong> v{entry.version} to a target agent as a
                    guardrail hook.
                  </>
                }
              >
                <div className="cu-registry-entry-card">
                  <div className="cu-registry-entry-card__head">
                    <strong className="cu-registry-name">{entry.name}</strong>
                    <span className="cu-muted">v{entry.version}</span>
                  </div>
                  {entry.description ? (
                    <p className="cu-registry-description">{entry.description}</p>
                  ) : null}
                </div>
              </FormSection>

              <FormSection
                title="Target agent"
                description="Choose the agent to bind this hook to."
              >
                <Field htmlFor="hif-host" label="Agent" required>
                  <SelectInput
                    id="hif-host"
                    value={hostRef}
                    onChange={event => setHostRef(event.target.value)}
                  >
                    <option value="">Select an agent...</option>
                    {hosts.map(host => (
                      <option key={host.metadata?.name} value={host.metadata?.name}>
                        {host.metadata?.name}
                      </option>
                    ))}
                  </SelectInput>
                </Field>
              </FormSection>

              {credHasKeys ? (
                <FormSection
                  title={`Credentials (${credSchema!.authType}${credRequired ? '' : ' - optional'})`}
                  description="Provided per this hook's credential schema."
                >
                  {credSchema!.keys.map(key => (
                    <Field key={key.name} htmlFor={`hif-cred-${key.name}`} label={key.label}>
                      <TextInput
                        id={`hif-cred-${key.name}`}
                        type={
                          key.kind === 'api-key' || key.kind === 'password' ? 'password' : 'text'
                        }
                        value={credValues[key.name] ?? ''}
                        onChange={event =>
                          setCredValues(previous => ({
                            ...previous,
                            [key.name]: event.target.value,
                          }))
                        }
                        onPaste={event => pasteCredentialValue(key.name, event)}
                        autoComplete="new-password"
                        placeholder={key.description}
                      />
                    </Field>
                  ))}
                  {credRequired ? (
                    <div
                      className={`cu-banner ${credStarted && !credComplete ? 'cu-banner--error' : 'cu-banner--info'}`}
                    >
                      {credStarted && !credComplete
                        ? `Complete all credential fields or clear them all to install pending. Missing: ${missingCredentialKeys.join(', ')}.`
                        : 'Leave all credential fields empty to install and add the secret later, or fill every field to create it during install.'}
                    </div>
                  ) : null}
                </FormSection>
              ) : null}

              {/* Everything an install can leave at its default lives behind one
                  disclosure: the entry's own facts, which are applied as-is, the
                  granted capabilities, and the ordering/fail-mode knobs. */}
              <FormSection
                title="Advanced details"
                collapsible
                open={advancedOpen}
                onOpenChange={setAdvancedOpen}
              >
                <div className="cu-summary-list cu-summary-list--flush">
                  {targetImage ? (
                    <div className="cu-summary-list__row">
                      <span>Target image</span>
                      <strong>{targetImage}</strong>
                    </div>
                  ) : null}
                  {targetService ? (
                    <div className="cu-summary-list__row">
                      <span>Target service</span>
                      <strong>{targetService}</strong>
                    </div>
                  ) : null}
                  {targetRemote ? (
                    <div className="cu-summary-list__row">
                      <span>Target remote</span>
                      <strong>{targetRemote}</strong>
                    </div>
                  ) : null}
                  <div className="cu-summary-list__row">
                    <span>Lifecycle points</span>
                    <strong>{lifecyclePoints.length > 0 ? lifecyclePoints.join(', ') : '—'}</strong>
                  </div>
                  {hookMeta?.path ? (
                    <div className="cu-summary-list__row">
                      <span>Path</span>
                      <strong>{hookMeta.path}</strong>
                    </div>
                  ) : null}
                </div>

                {/* Grouped rather than left as four loose checkboxes: they are a
                    single decision, and fail mode below is constrained by it. */}
                <fieldset className="cu-form-section__group">
                  <legend className="cu-form-section__subheading">Capabilities</legend>
                  <p className="cu-form-section__description">{capabilitiesDescription}</p>
                  {HOOK_CAPABILITY_OPTIONS.map(option => {
                    const outsideCeiling = !!ceiling && !ceiling.includes(option.value)
                    const declared = declaredCapabilities.includes(option.value)
                    const suffix = outsideCeiling
                      ? declared
                        ? " (required by this hook, but outside the agent's ceiling)"
                        : " (outside the agent's ceiling)"
                      : declared
                        ? ' (required by this hook)'
                        : ''
                    return (
                      <CheckboxField
                        key={option.value}
                        label={option.label}
                        description={`${option.description}${suffix}`}
                        checked={capabilities.has(option.value)}
                        disabled={outsideCeiling}
                        onChange={() => toggleCapability(option.value)}
                      />
                    )
                  })}
                  {/* Always mounted, so ticking a box announces the change. A
                      live region added to the DOM already populated announces
                      nothing. */}
                  <div role="status">
                    <DegradedGrantNotices
                      enforced={missingEnforced}
                      unenforced={missingUnenforced}
                    />
                  </div>
                </fieldset>

                <Field
                  htmlFor="hif-order"
                  label="Order"
                  description={
                    ORDER_HINT_LABELS[authorOrderHint]
                      ? `Lower runs first. Defaults to 100 when left blank. ${ORDER_HINT_LABELS[authorOrderHint]}`
                      : 'Lower runs first. Defaults to 100 when left blank.'
                  }
                  error={orderValid ? undefined : 'Order must be a number.'}
                >
                  <TextInput
                    id="hif-order"
                    type="number"
                    value={order}
                    invalid={!orderValid}
                    onChange={event => setOrder(event.target.value)}
                    placeholder={String(DEFAULT_HOOK_ORDER)}
                  />
                </Field>
                <Field
                  htmlFor="hif-failmode"
                  label="Fail mode"
                  description={
                    mustFailClosed
                      ? 'A hook that may deny must fail closed.'
                      : authorFailMode
                        ? `Fail open lets calls proceed when the hook errors; fail closed blocks them. The author suggests fail ${authorFailMode}.`
                        : 'Fail open lets calls proceed when the hook errors; fail closed blocks them.'
                  }
                >
                  <SelectInput
                    id="hif-failmode"
                    value={effectiveFailMode}
                    disabled={mustFailClosed}
                    onChange={event => setFailMode(event.target.value as 'open' | 'closed')}
                  >
                    <option value="open">Fail open</option>
                    <option value="closed">Fail closed</option>
                  </SelectInput>
                </Field>
              </FormSection>
            </>
          ) : null}

          {step === 1 ? (
            <>
              <div className="cu-agent-review">
                Guardrail hook <b>{entry.name}</b> v{entry.version} will be installed on agent{' '}
                <b>{hostRef || '-'}</b> with{' '}
                <b>
                  {capabilities.size > 0 ? [...capabilities].join(', ') : 'no extra capabilities'}
                </b>
                , order <b>{order.trim() === '' ? DEFAULT_HOOK_ORDER : order}</b>, fail mode{' '}
                <b>{effectiveFailMode}</b>.
              </div>
              <DegradedGrantNotices enforced={missingEnforced} unenforced={missingUnenforced} />
            </>
          ) : null}

          {error ? (
            <div className="cu-banner cu-banner--error" role="alert">
              {error}
            </div>
          ) : null}

          <div className="cu-create-actions">
            <Button
              type="button"
              variant="ghost"
              size="sm"
              onClick={() => (step === 0 ? onCancel() : setStep(current => current - 1))}
              disabled={installing}
            >
              {step === 0 ? 'Cancel' : 'Back'}
            </Button>
            {step < STEPS.length - 1 ? (
              <Button type="submit" variant="primary" size="sm" disabled={!canContinue}>
                Continue
              </Button>
            ) : (
              <Button type="submit" variant="primary" size="sm" disabled={!canSubmit}>
                {installing ? 'Installing...' : 'Install'}
              </Button>
            )}
          </div>
        </form>
      )}
    </CreateStepFlow>
  )
}