Skip to content

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

TypeScript

feat(control-ui): pre-fill guardrail install from the author's declarations

Andy Paviaed16e5fc05fc
diff --git a/control-ui/components/HookInstallForm/constants.ts b/control-ui/components/HookInstallForm/constants.ts
index a940184cf..74d87f184 100644
--- a/control-ui/components/HookInstallForm/constants.ts
+++ b/control-ui/components/HookInstallForm/constants.ts
@@ -34,6 +34,21 @@ export const ALL_HOOK_CAPABILITIES: HookCapability[] = HOOK_CAPABILITY_OPTIONS.m
// Default installation order applied by the backend when none is supplied.
export const DEFAULT_HOOK_ORDER = 100
+// `hook_meta.authorDefaults.orderHint` is a word ("early", "late"), while the
+// CRD's `order` is an integer. There is no published mapping between them, so
+// the hint is shown to the operator rather than silently converted to a number.
+//
+// Null-prototype on purpose: the key is a publisher-supplied string off the
+// registry entry, so an inherited key (`toString`, `constructor`, …) would
+// otherwise resolve to a function and be rendered as if it were a real hint.
+export const ORDER_HINT_LABELS: Record<string, string> = Object.assign(
+ Object.create(null) as Record<string, string>,
+ {
+ early: 'The author suggests running this hook early.',
+ late: 'The author suggests running this hook late.',
+ }
+)
+
// Friendly copy for the coded error bodies the install-hook route returns
// ({ error, reason? }). Any reason string from the backend is appended verbatim.
export const HOOK_INSTALL_ERROR_LABELS: Record<string, string> = {
diff --git a/control-ui/components/HookInstallForm/index.tsx b/control-ui/components/HookInstallForm/index.tsx
index f52bc2f95..85ac944ea 100644
--- a/control-ui/components/HookInstallForm/index.tsx
+++ b/control-ui/components/HookInstallForm/index.tsx
@@ -13,6 +13,7 @@ import {
DEFAULT_HOOK_ORDER,
HOOK_CAPABILITY_OPTIONS,
HOOK_INSTALL_ERROR_LABELS,
+ ORDER_HINT_LABELS,
} from './constants'
import type { HookInstallFormProps } from './types'
@@ -85,14 +86,36 @@ export function HookInstallForm({ entry, onCancel, onInstalled }: HookInstallFor
: ''
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({})
- setCapabilities(new Set())
+ // 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('open')
+ setFailMode(authorFailMode ?? 'open')
setLoading(true)
;(async () => {
try {
@@ -132,6 +155,14 @@ export function HookInstallForm({ entry, onCancel, onInstalled }: HookInstallFor
})
}, [ceiling])
+ // 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]
+ )
+
// 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
@@ -263,42 +294,6 @@ export function HookInstallForm({ entry, onCancel, onInstalled }: HookInstallFor
</div>
</FormSection>
- <FormSection
- title="Hook details"
- description="These facts come from the Marketplace entry and are applied as-is."
- >
- <div className="cu-summary-list">
- {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>
- </FormSection>
-
<FormSection
title="Target agent"
description="Choose the agent to bind this hook to."
@@ -356,38 +351,90 @@ export function HookInstallForm({ entry, onCancel, onInstalled }: HookInstallFor
</FormSection>
) : null}
- <FormSection
- title="Capabilities"
- description={
- ceiling
- ? "Only the capabilities within this agent's capability ceiling can be granted."
- : 'Grant only the capabilities this hook needs.'
- }
- >
- {HOOK_CAPABILITY_OPTIONS.map(option => {
- const outsideCeiling = !!ceiling && !ceiling.includes(option.value)
- return (
- <CheckboxField
- key={option.value}
- label={option.label}
- description={
- outsideCeiling
- ? `${option.description} (outside the agent's ceiling)`
- : option.description
- }
- checked={capabilities.has(option.value)}
- disabled={outsideCeiling}
- onChange={() => toggleCapability(option.value)}
- />
- )
- })}
- </FormSection>
+ {/* 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>
+ <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">
+ {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."
+ : ceiling
+ ? "Only the capabilities within this agent's capability ceiling can be granted."
+ : 'Grant only the capabilities this hook needs.'}
+ </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)}
+ />
+ )
+ })}
+ {missingDeclared.length > 0 ? (
+ <div className="cu-banner cu-banner--warning" role="status">
+ This hook needs {missingDeclared.join(', ')} to function. Without{' '}
+ {missingDeclared.length > 1 ? 'them' : 'it'}, it installs and reports Ready,
+ but the actions it takes are discarded.
+ </div>
+ ) : null}
+ </fieldset>
- <FormSection title="Execution" description="How this hook is ordered and fails.">
<Field
htmlFor="hif-order"
label="Order"
- description="Lower runs first. Defaults to 100 when left blank."
+ 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
@@ -405,7 +452,9 @@ export function HookInstallForm({ entry, onCancel, onInstalled }: HookInstallFor
description={
mustFailClosed
? 'A hook that may deny must fail closed.'
- : 'Fail open lets calls proceed when the hook errors; fail closed blocks them.'
+ : 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
diff --git a/control-ui/components/__tests__/HookInstallForm.test.tsx b/control-ui/components/__tests__/HookInstallForm.test.tsx
new file mode 100644
index 000000000..9cdc2dd8d
--- /dev/null
+++ b/control-ui/components/__tests__/HookInstallForm.test.tsx
@@ -0,0 +1,200 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render as rtlRender, screen, waitFor } from '@testing-library/react'
+import * as api from '../../lib/api'
+import type { RegistryEntry } from '../../lib/api'
+import { HookInstallForm } from '../HookInstallForm'
+import { ToastProvider } from '../Toast'
+
+vi.mock('../../lib/api', () => ({
+ getHosts: vi.fn(),
+ getRegistryCredentialSchema: vi.fn(),
+ installHookFromRegistry: vi.fn(),
+}))
+
+function entryWith(hookMeta: Record<string, unknown>): RegistryEntry {
+ return {
+ name: '@acme1/token-compactor',
+ version: '0.2.3',
+ entry_type: 'llm-hook',
+ description: 'Compacts prompts.',
+ hook_meta: {
+ target: { image: { ref: 'zot.local/acme1/token-compactor@sha256:abc', port: 8080 } },
+ lifecyclePoints: ['preCall'],
+ ...hookMeta,
+ },
+ } as unknown as RegistryEntry
+}
+
+/** A Host whose guardrails ceiling allows `ceiling`, or none when null. */
+function host(name: string, ceiling: string[] | null) {
+ return { metadata: { name }, spec: ceiling ? { guardrails: { capabilityCeiling: ceiling } } : {} }
+}
+
+function render(ui: React.ReactNode) {
+ return rtlRender(<ToastProvider>{ui}</ToastProvider>)
+}
+
+function capabilityBox(label: string): HTMLInputElement {
+ // CheckboxField renders the label text alongside its input.
+ return screen.getByRole('checkbox', { name: new RegExp(label, 'i') }) as HTMLInputElement
+}
+
+/**
+ * Capabilities, order, and fail mode live inside the "Advanced details"
+ * disclosure, so none of them are in the DOM until it is open. Idempotent on
+ * purpose: if the section ever ships open by default, an unconditional click
+ * would close it and fail every test here for an unrelated reason.
+ */
+async function openAdvanced() {
+ const toggle = await screen.findByRole('button', { name: /advanced details/i })
+ if (toggle.getAttribute('aria-expanded') !== 'true') fireEvent.click(toggle)
+ await waitFor(() =>
+ expect(screen.getByRole('checkbox', { name: /may deny/i })).toBeInTheDocument()
+ )
+}
+
+afterEach(cleanup)
+beforeEach(() => {
+ vi.clearAllMocks()
+ vi.mocked(api.getRegistryCredentialSchema).mockResolvedValue({ keys: [] } as never)
+ vi.mocked(api.getHosts).mockResolvedValue({ items: [host('agent-a', null)] } as never)
+})
+
+const noop = () => undefined
+
+describe('HookInstallForm — author declarations', () => {
+ it('pre-ticks the capabilities the author declares', async () => {
+ render(
+ <HookInstallForm
+ entry={entryWith({ requiredCapabilities: ['may_rewrite'] })}
+ onCancel={noop}
+ onInstalled={noop}
+ />
+ )
+ await openAdvanced()
+ await waitFor(() => expect(capabilityBox('May rewrite').checked).toBe(true))
+ expect(capabilityBox('May deny').checked).toBe(false)
+ expect(screen.getByText(/required by this hook/i)).toBeInTheDocument()
+ })
+
+ it('leaves everything unticked when the author declares nothing', async () => {
+ render(<HookInstallForm entry={entryWith({})} onCancel={noop} onInstalled={noop} />)
+ await openAdvanced()
+ expect(capabilityBox('May rewrite').checked).toBe(false)
+ expect(capabilityBox('May deny').checked).toBe(false)
+ expect(screen.queryByText(/required by this hook/i)).toBeNull()
+ })
+
+ it('applies the author fail mode', async () => {
+ render(
+ <HookInstallForm
+ entry={entryWith({ authorDefaults: { failMode: 'closed' } })}
+ onCancel={noop}
+ onInstalled={noop}
+ />
+ )
+ await openAdvanced()
+ const select = await screen.findByLabelText(/fail mode/i)
+ await waitFor(() => expect(select).toHaveValue('closed'))
+ })
+
+ it('shows the order hint without inventing a numeric order', async () => {
+ render(
+ <HookInstallForm
+ entry={entryWith({ authorDefaults: { orderHint: 'early' } })}
+ onCancel={noop}
+ onInstalled={noop}
+ />
+ )
+ await openAdvanced()
+ expect(await screen.findByText(/suggests running this hook early/i)).toBeInTheDocument()
+ // `order` stays the backend default — the hint is a word, not a number.
+ expect(await screen.findByLabelText(/^order$/i)).toHaveValue(100)
+ })
+
+ it('ignores an order hint naming an inherited object key', async () => {
+ // `orderHint: "toString"` used to resolve to Object.prototype.toString off
+ // the label map and render as if it were a real hint.
+ render(
+ <HookInstallForm
+ entry={entryWith({ authorDefaults: { orderHint: 'toString' } })}
+ onCancel={noop}
+ onInstalled={noop}
+ />
+ )
+ await openAdvanced()
+ const order = await screen.findByLabelText(/^order$/i)
+ expect(order).toHaveValue(100)
+ expect(screen.queryByText(/native code/i)).toBeNull()
+ expect(screen.queryByText(/the author suggests/i)).toBeNull()
+ })
+
+ it('ignores capability values outside the known set', async () => {
+ render(
+ <HookInstallForm
+ entry={entryWith({ requiredCapabilities: ['not_a_capability', 'may_deny'] })}
+ onCancel={noop}
+ onInstalled={noop}
+ />
+ )
+ await openAdvanced()
+ await waitFor(() => expect(capabilityBox('May deny').checked).toBe(true))
+ expect(capabilityBox('May rewrite').checked).toBe(false)
+ })
+
+ it('survives a malformed declaration rather than breaking the page', async () => {
+ render(
+ <HookInstallForm
+ entry={entryWith({ requiredCapabilities: 'may_deny' })}
+ onCancel={noop}
+ onInstalled={noop}
+ />
+ )
+ await openAdvanced()
+ await waitFor(() => expect(capabilityBox('May deny')).toBeInTheDocument())
+ expect(capabilityBox('May deny').checked).toBe(false)
+ })
+})
+
+describe('HookInstallForm — declaration never escapes the ceiling', () => {
+ it('does not grant a declared capability the agent forbids, and says so', async () => {
+ vi.mocked(api.getHosts).mockResolvedValue({
+ items: [host('agent-a', ['may_add_context'])],
+ } as never)
+ render(
+ <HookInstallForm
+ entry={entryWith({ requiredCapabilities: ['may_deny'] })}
+ onCancel={noop}
+ onInstalled={noop}
+ />
+ )
+ await openAdvanced()
+ // Declared, but outside the ceiling: unticked, disabled, and flagged.
+ await waitFor(() => expect(capabilityBox('May deny')).toBeDisabled())
+ expect(capabilityBox('May deny').checked).toBe(false)
+ // The declared-but-forbidden one is marked as both, not merely forbidden.
+ expect(
+ screen.getByText(/required by this hook, but outside the agent's ceiling/i)
+ ).toBeInTheDocument()
+ expect(screen.getByText(/needs may_deny to function/i)).toBeInTheDocument()
+ })
+
+ it('a declared may_deny still forces fail closed, as a manual tick does', async () => {
+ render(
+ <HookInstallForm
+ entry={entryWith({
+ requiredCapabilities: ['may_deny'],
+ // The author asks for fail open; may_deny overrides it.
+ authorDefaults: { failMode: 'open' },
+ })}
+ onCancel={noop}
+ onInstalled={noop}
+ />
+ )
+ await openAdvanced()
+ await waitFor(() => expect(capabilityBox('May deny').checked).toBe(true))
+ const select = await screen.findByLabelText(/fail mode/i)
+ expect(select).toHaveValue('closed')
+ expect(select).toBeDisabled()
+ })
+})
diff --git a/control-ui/lib/api.ts b/control-ui/lib/api.ts
index 84ba05af0..ca9746a85 100644
--- a/control-ui/lib/api.ts
+++ b/control-ui/lib/api.ts
@@ -3023,11 +3023,29 @@ export type RegistryEntry = {
service?: { name?: string; namespace?: string; port?: number }
remote?: { baseUrl?: string }
}
- lifecyclePoints?: string[] // "preCall" | "moderate" | "postCallSuccess" | "onError"
+ // The CRD enumerates six: the four LLM-lane points below plus the tool
+ // lane's preToolUse/postToolUse.
+ lifecyclePoints?: string[] // "preCall" | "moderate" | "postCallSuccess" | "onError" | "preToolUse" | "postToolUse"
path?: string
credentialSchema?: CredentialSchema
defaultConfig?: Record<string, unknown>
requiredEgress?: unknown
+ // What the hook author says the hook needs to function. Advisory: it
+ // seeds the install form, but the operator's selection is the grant and
+ // stays bounded by Host.spec.guardrails.capabilityCeiling.
+ requiredCapabilities?: HookCapability[]
+ // The author's suggested runtime posture, used to pre-fill the install
+ // form. `orderHint` is a word, not the CRD's numeric `order`.
+ authorDefaults?: {
+ failMode?: 'open' | 'closed'
+ orderHint?: string
+ timeoutMs?: number
+ onUnavailable?: {
+ mode?: 'strict' | 'breaker'
+ failureThreshold?: number
+ cooldownMs?: number
+ }
+ }
})
| null
artifact_refs: Record<string, unknown> | null
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index 4ac83d4a1..accdf57c0 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.450",
+ "version": "0.1.451",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.450",
+ "version": "0.1.451",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/llm-providers": "file:../packages/llm-providers",
diff --git a/control-ui/package.json b/control-ui/package.json
index 5fef329e3..1efd79c00 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.450",
+ "version": "0.1.451",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",