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.tsindex 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.tsxindex 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 = falsesetStep(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>-<FormSectiontitle="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."><FieldhtmlFor="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 }: HookInstallFordescription={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.'}><SelectInputdiff --git a/control-ui/components/__tests__/HookInstallForm.test.tsx b/control-ui/components/__tests__/HookInstallForm.test.tsxnew file mode 100644index 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.tsindex 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?: stringcredentialSchema?: CredentialSchemadefaultConfig?: 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+ }+ }})| nullartifact_refs: Record<string, unknown> | nulldiff --git a/control-ui/package-lock.json b/control-ui/package-lock.jsonindex 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.jsonindex 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",