DefineCheckSpec

The author-facing spec accepted by defineCheck. Extends RegisteredCheck with an optional configSchema slot that can be either a JSON Schema object or a Zod v4 schema. When set, defineCheck derives validateConfig from the schema — authors don't have to write it separately.

evaluate is typed against the schema-inferred config for Zod- authored checks; JSON-Schema-authored checks fall back to Readonly<Record<string, unknown>>.

Type Parameters

Type Parameter
TConfigSchema extends AnySchema

Properties

Property	Modifier	Type	Description
configSchema?	readonly	TConfigSchema	Config schema — Zod v4 or JSON Schema. When present, defineCheck derives RegisteredCheck.validateConfig from it, and defineGuardrail runs that against each Guardrail.config. Zod authors get schema-inferred config types on evaluate's first parameter.
evaluate	readonly	(config, trace, bindings) => Promise<CheckResult>	The check function. Signature: (config, trace, bindings) => Promise<CheckResult>. config is the guardrail's declared config (typed via configSchema when Zod-authored). trace is the accumulated RunTrace from the agent turn. bindings is the EvaluationBindings the caller passed to the engine ({} when none). Return {passed: true} or {passed: false, reason: string, ...}.
id	readonly	string	Check identifier. Referenced by Guardrail.check on the wire. Convention: dot-namespaced for pack-authored checks (e.g. 'acme.max-citations'); framework-shipped checks use stable ids like 'must-cite' / 'never-call-tool'.
kind	readonly	string	'zero-llm' — pure function over the trace (fast, deterministic, default). 'llm-judge' — uses a model (opt-in, costs money; needs bindings.providerRegistry or bindings.judgeProvider). 'external' — evaluated by a caller-registered strategy.
validateConfig?	readonly	(config) => string | undefined	Optional custom config validator. When configSchema is also set, both run — configSchema first, then this. undefined return means "config is valid"; non-undefined string is the error message.