@namzu/sdk 2.0.0 → 3.1.0

package/src/types/errors/__tests__/catalog.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest'
+
+import { ProviderError } from '../../provider/errors.js'
+import { DEFAULT_ERROR_RULES, explainError, factsOf, readHint, withHint } from '../catalog.js'
+import { NamzuError } from '../index.js'
+
+/**
+ * A failure surfaced as whatever prose the vendor SDK happened to write:
+ * no stable id to grep in logs, no instruction on what to change, and no
+ * growth point — a newly-observed failure shape could only be given
+ * curated copy by editing the classifier itself.
+ *
+ * Classification and remediation are separate jobs. The first is
+ * structural and belongs at the boundary; the second is editorial and
+ * belongs in a list a human appends to. `DoctorCheckResult` already
+ * carried `message` and `remediation` as separate fields — `namzu doctor`
+ * was simply the only surface that got either.
+ */
+
+const providerError = (code: string, status?: number) =>
+	new ProviderError({
+		code: code as never,
+		message: 'the vendor wrote this',
+		providerId: 'test',
+		...(status !== undefined ? { status } : {}),
+	})
+
+describe('explaining a failure', () => {
+	it('gives a stale key an id and something to do about it', () => {
+		const explanation = explainError(providerError('auth', 401))
+
+		expect(explanation?.id).toBe('provider.auth')
+		expect(explanation?.hint).toMatch(/API key/)
+		// Not the vendor's sentence: the point is copy an operator can act
+		// on, keyed by an id they can grep for.
+		expect(explanation?.message).not.toContain('the vendor wrote this')
+	})
+
+	it('separates a permission failure from an authentication one', () => {
+		// The provider codes collapse 401 and 403, but the two call for
+		// different actions and the status still tells them apart.
+		expect(explainError(providerError('auth', 403))?.id).toBe('provider.permission')
+		expect(explainError(providerError('auth', 401))?.id).toBe('provider.auth')
+	})
+
+	it('recognises the failures an operator hits first', () => {
+		expect(explainError(providerError('rate_limit', 429))?.id).toBe('provider.rate_limit')
+		expect(explainError(providerError('context_length_exceeded'))?.id).toBe(
+			'provider.context_overflow',
+		)
+		expect(explainError(providerError('overloaded', 529))?.id).toBe('provider.unavailable')
+		expect(explainError(providerError('network'))?.id).toBe('provider.network')
+		expect(explainError(providerError('not_found', 404))?.id).toBe('provider.model_not_found')
+	})
+
+	it('says nothing rather than inventing advice', () => {
+		// A generic fallback would send the reader somewhere specific and
+		// wrong, which is worse than admitting the failure is unfamiliar.
+		expect(explainError(new Error('something nobody has characterised'))).toBeNull()
+	})
+
+	it('matches on structure, not on vendor prose', () => {
+		// Vendor copy changes without warning and differs per SDK version,
+		// so a rule keyed to it silently stops matching.
+		const reworded = providerError('rate_limit', 429)
+		Object.defineProperty(reworded, 'message', { value: 'completely different wording' })
+		expect(explainError(reworded)?.id).toBe('provider.rate_limit')
+	})
+
+	it('takes the first matching rule, so a rule can be as specific as it likes', () => {
+		const ids = DEFAULT_ERROR_RULES.map((rule) => rule.id)
+		expect(ids.indexOf('provider.permission')).toBeLessThan(ids.indexOf('provider.auth'))
+	})
+})
+
+describe('a hint attached where the failure was raised', () => {
+	it('wins over a rule matched on a status code', () => {
+		// Code that raised the failure knows more about it than a generic
+		// rule ever will — a container that has not been built, a daemon
+		// that is not running.
+		const err = withHint(providerError('rate_limit', 429), 'the sandbox worker is not running')
+		const explanation = explainError(err)
+
+		expect(explanation?.id).toBe('hint.from_throw_site')
+		expect(explanation?.hint).toBe('the sandbox worker is not running')
+	})
+
+	it('survives being read back off a plain throwable', () => {
+		expect(readHint(withHint(new Error('boom'), 'check the socket path'))).toBe(
+			'check the socket path',
+		)
+	})
+
+	it('does not change the message or the type', () => {
+		// Baking remediation into the message is what made it impossible to
+		// separate again — a surface could not render one without the other.
+		const original = new NamzuError({ code: 'storage_error', message: 'write failed' })
+		const hinted = withHint(original, 'the run directory is not writable')
+
+		expect(hinted).toBe(original)
+		expect(hinted.message).toBe('write failed')
+		expect(hinted instanceof NamzuError).toBe(true)
+	})
+
+	it('is not enumerable, so it cannot leak into a serialized error', () => {
+		const err = withHint(new Error('boom'), 'a hint')
+		expect(Object.keys(err)).not.toContain('hint')
+	})
+
+	it('ignores an empty or non-string hint', () => {
+		expect(readHint(withHint(new Error('boom'), ''))).toBeUndefined()
+		expect(readHint({ hint: 42 })).toBeUndefined()
+		expect(readHint(null)).toBeUndefined()
+	})
+})
+
+describe('the facts a rule matches on', () => {
+	it('reads a provider classification', () => {
+		const facts = factsOf(providerError('rate_limit', 429))
+		expect(facts).toMatchObject({ code: 'rate_limit', status: 429 })
+	})
+
+	it('reads a namzu code', () => {
+		expect(factsOf(new NamzuError({ code: 'tool_error', message: 'x' })).code).toBe('tool_error')
+	})
+
+	it('still produces facts for something that was never an Error', () => {
+		expect(factsOf('just a string').message).toBe('just a string')
+	})
+})

package/src/types/errors/__tests__/errors.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest'
+
+import { ProviderError } from '../../provider/errors.js'
+import { NamzuError, isNamzuError, toPlatformError } from '../index.js'
+
+/**
+ * `PlatformError` was declared and never constructed — a shape nothing
+ * produced and nothing consumed — while the runtime threw bare `Error`
+ * everywhere. A caller catching a failure from `query()` could not tell
+ * "the model rate-limited us" from "the run was configured wrong" from
+ * "that checkpoint does not exist". Matching on message text was the only
+ * recourse, and message text is not an interface.
+ */
+
+describe('NamzuError', () => {
+	it('is an Error, so code that only knows about Error still works', () => {
+		const err = new NamzuError({ code: 'invalid_config', message: 'no model' })
+		expect(err).toBeInstanceOf(Error)
+		expect(err.message).toBe('no model')
+		expect(err.stack).toBeDefined()
+	})
+
+	it('preserves the cause chain', () => {
+		const root = new Error('ENOENT')
+		const err = new NamzuError({ code: 'storage_error', message: 'write failed', cause: root })
+		expect(err.cause).toBe(root)
+	})
+
+	it('defaults `retryable` per code, and lets a caller override it', () => {
+		expect(new NamzuError({ code: 'invalid_config', message: 'x' }).retryable).toBe(false)
+		expect(new NamzuError({ code: 'storage_error', message: 'x' }).retryable).toBe(true)
+		expect(
+			new NamzuError({ code: 'invalid_config', message: 'x', retryable: true }).retryable,
+		).toBe(true)
+	})
+
+	it('narrows through `isNamzuError`', () => {
+		expect(isNamzuError(new NamzuError({ code: 'unknown', message: 'x' }))).toBe(true)
+		expect(isNamzuError(new Error('x'))).toBe(false)
+		expect(isNamzuError('x')).toBe(false)
+	})
+})
+
+describe('toPlatformError', () => {
+	it('gives a host ONE shape regardless of what was thrown', () => {
+		// Which is the entire point: without this, "handle errors from the
+		// SDK" means writing the same instanceof ladder in every caller.
+		for (const thrown of [
+			new NamzuError({ code: 'plugin_error', message: 'a' }),
+			new ProviderError({ code: 'rate_limit', message: 'b' }),
+			new Error('c'),
+			'not even an error',
+		]) {
+			const platform = toPlatformError(thrown)
+			expect(typeof platform.code).toBe('string')
+			expect(typeof platform.message).toBe('string')
+			expect(typeof platform.retryable).toBe('boolean')
+		}
+	})
+
+	it('carries a NamzuError through unchanged', () => {
+		const err = new NamzuError({
+			code: 'not_found',
+			message: 'Checkpoint not found: cp_1',
+			details: { checkpointId: 'cp_1' },
+		})
+		expect(toPlatformError(err)).toEqual({
+			code: 'not_found',
+			message: 'Checkpoint not found: cp_1',
+			details: { checkpointId: 'cp_1' },
+			retryable: false,
+		})
+	})
+
+	it('keeps a ProviderError`s classification instead of recomputing it', () => {
+		// The provider taxonomy already knows things this one does not —
+		// which status codes back off, what the server asked for.
+		const err = new ProviderError({
+			code: 'rate_limit',
+			message: 'slow down',
+			providerId: 'anthropic',
+			status: 429,
+			retryAfterMs: 3_000,
+		})
+
+		expect(toPlatformError(err)).toEqual({
+			code: 'provider_error',
+			message: 'slow down',
+			details: {
+				providerCode: 'rate_limit',
+				providerId: 'anthropic',
+				status: 429,
+				retryAfterMs: 3_000,
+			},
+			retryable: true,
+		})
+	})
+
+	it('does not claim a non-retryable provider failure is retryable', () => {
+		const err = new ProviderError({ code: 'auth', message: 'bad key' })
+		expect(toPlatformError(err).retryable).toBe(false)
+	})
+
+	it('reports a plain Error honestly as `unknown` rather than guessing', () => {
+		expect(toPlatformError(new Error('something broke'))).toEqual({
+			code: 'unknown',
+			message: 'something broke',
+			retryable: false,
+		})
+	})
+
+	it('does not lose a thrown non-Error', () => {
+		// Rare, and usually a bug elsewhere — but dropping it is worse than
+		// reporting it as-is.
+		expect(toPlatformError({ weird: true }).message).toBe('[object Object]')
+		expect(toPlatformError(undefined).message).toBe('undefined')
+	})
+})

package/src/types/errors/catalog.ts

@@ -0,0 +1,211 @@
+import { ProviderError } from '../provider/errors.js'
+import { isNamzuError } from './index.js'
+
+/**
+ * An ordered rule layer between a caught throwable and the operator.
+ *
+ * A failure surfaced as whatever prose the vendor SDK happened to write:
+ * no stable id to grep for in logs, and no instruction on what to change.
+ * There was also no growth point — a newly-observed failure shape could
+ * only be given curated copy by editing the classifier itself, which mixes
+ * "what kind of failure is this" with "what should a person do about it".
+ *
+ * The two are separate jobs. Classification is structural and belongs at
+ * the boundary; remediation is editorial and belongs in a list a human
+ * appends to. `DoctorCheckResult` already proves the pattern is native
+ * here: it carries `message` and `remediation` as separate fields, and
+ * `namzu doctor` has been the only surface that got either.
+ *
+ * Rules match on STRUCTURAL signals — code, status, error name, an
+ * explicit `hint` own-property from the throw site — never on volatile
+ * vendor prose, which changes without warning and differs per SDK version.
+ */
+
+/** What a rule knows about a failure, flattened for matching. */
+export interface ErrorFacts {
+	/** namzu or provider code, whichever classification produced one. */
+	readonly code?: string
+	readonly status?: number
+	/** Constructor name, for a throwable neither classifier recognised. */
+	readonly name?: string
+	readonly message: string
+	/** Server-directed backoff, when one was parsed. */
+	readonly retryAfterMs?: number
+	/** A hint the throw site attached directly. See {@link readHint}. */
+	readonly hint?: string
+}
+
+export interface ErrorCatalogRule {
+	/**
+	 * Stable id. Appears in logs and in operator output, so it is greppable
+	 * and can be linked to. Never renamed once shipped — a rule whose
+	 * meaning changes gets a new id.
+	 */
+	readonly id: string
+	readonly when: (facts: ErrorFacts) => boolean
+	/** What happened, in an operator's terms rather than the vendor's. */
+	readonly message: string
+	/** What to change. Separate from `message` so a surface can override it. */
+	readonly hint: string
+}
+
+export interface ErrorExplanation {
+	readonly id: string
+	readonly message: string
+	readonly hint: string
+}
+
+/**
+ * A hint attached at the throw site.
+ *
+ * Infrastructure code knows things the classifier cannot infer — that a
+ * daemon is not running, that a socket path is wrong — and had no channel
+ * to say so except by baking prose into the message, where it cannot be
+ * separated from the failure again. An own-property survives every
+ * `instanceof` check and every rethrow, and rules can pass it through
+ * under a stable id.
+ */
+export function readHint(err: unknown): string | undefined {
+	if (typeof err !== 'object' || err === null) return undefined
+	const hint = (err as { hint?: unknown }).hint
+	return typeof hint === 'string' && hint.length > 0 ? hint : undefined
+}
+
+/** Attach a hint to a throwable without changing its message or type. */
+export function withHint<E>(err: E, hint: string): E {
+	if (typeof err === 'object' && err !== null) {
+		Object.defineProperty(err, 'hint', { value: hint, enumerable: false, configurable: true })
+	}
+	return err
+}
+
+/** Flatten a throwable into the shape rules match on. */
+export function factsOf(err: unknown): ErrorFacts {
+	const hint = readHint(err)
+	const message = err instanceof Error ? err.message : String(err)
+
+	if (err instanceof ProviderError) {
+		return {
+			code: err.code,
+			message,
+			name: err.name,
+			...(err.status !== undefined ? { status: err.status } : {}),
+			...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
+			...(hint !== undefined ? { hint } : {}),
+		}
+	}
+
+	if (isNamzuError(err)) {
+		const status = err.details?.status
+		return {
+			code: err.code,
+			message,
+			name: err.name,
+			...(typeof status === 'number' ? { status } : {}),
+			...(hint !== undefined ? { hint } : {}),
+		}
+	}
+
+	return {
+		message,
+		...(err instanceof Error ? { name: err.name } : {}),
+		...(hint !== undefined ? { hint } : {}),
+	}
+}
+
+/**
+ * The seed rules.
+ *
+ * Ordered, first match wins — so a rule may be as specific as it likes
+ * without having to exclude everything below it. Three to start, chosen
+ * because they are the failures an operator hits first and the ones where
+ * the vendor's own words help least.
+ */
+export const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[] = [
+	{
+		id: 'hint.from_throw_site',
+		// Highest precedence on purpose: code that raised the failure knows
+		// more about it than a rule matching on a status code ever will.
+		when: (facts) => facts.hint !== undefined,
+		message: '',
+		hint: '',
+	},
+	{
+		// Before the generic auth rule: the codes collapse 401 and 403 into
+		// one, but the two call for different actions and the status still
+		// separates them when the provider sent it.
+		id: 'provider.permission',
+		when: (facts) => facts.status === 403,
+		message: 'The credentials are valid but not permitted to use this model.',
+		hint: 'The key authenticated, so this is an entitlement rather than a secret problem: check the model name and whether the account has access to it.',
+	},
+	{
+		id: 'provider.auth',
+		when: (facts) => facts.code === 'auth' || facts.status === 401,
+		message: 'The provider rejected the credentials for this run.',
+		hint: 'Check that the API key is set, is not expired, and belongs to the account the model is billed to. Retrying will not help until it changes.',
+	},
+	{
+		id: 'provider.rate_limit',
+		when: (facts) => facts.code === 'rate_limit' || facts.status === 429,
+		message: 'The provider is rate limiting this run.',
+		hint: 'Automatic retries with backoff have already been exhausted. Lower concurrency, or wait for the quota window to reset before resuming.',
+	},
+	{
+		id: 'provider.context_overflow',
+		when: (facts) => facts.code === 'context_length_exceeded',
+		message: 'The prompt is larger than the model can accept.',
+		hint: 'Compaction ran and could not make enough room. Lower `compactionConfig.triggerThreshold`, reduce `keepRecentMessages`, or cap large tool outputs so history stops growing faster than it can be shed.',
+	},
+	{
+		id: 'provider.unavailable',
+		when: (facts) =>
+			facts.code === 'server_error' ||
+			facts.code === 'overloaded' ||
+			(facts.status !== undefined && facts.status >= 500),
+		message: 'The provider is failing on its own side.',
+		hint: 'Nothing in the run is wrong. Resume from the last checkpoint once the provider recovers.',
+	},
+	{
+		id: 'provider.network',
+		when: (facts) => facts.code === 'network' || facts.code === 'timeout',
+		message: 'The provider could not be reached.',
+		hint: 'Check network reachability and any proxy or firewall between this host and the provider endpoint, then resume from the last checkpoint.',
+	},
+	{
+		id: 'provider.model_not_found',
+		when: (facts) => facts.code === 'not_found' || facts.status === 404,
+		message: 'The provider does not recognise the model or endpoint requested.',
+		hint: "Check `runConfig.model` against the provider's current model list — a model id that was valid can be retired, and a deployment-scoped provider needs the deployment name rather than the base model name.",
+	},
+	{
+		id: 'provider.content_filter',
+		when: (facts) => facts.code === 'content_filter',
+		message: 'The provider refused the request on safety grounds.',
+		hint: "This is the provider's policy decision, not a namzu one, and resending the same prompt cannot change it. The refusal usually names the category it triggered.",
+	},
+]
+
+/**
+ * Explain a failure, or return `null` when no rule claims it.
+ *
+ * `null` rather than a generic fallback: inventing advice for a failure
+ * nobody has characterised is worse than saying nothing, because it sends
+ * the reader somewhere specific and wrong.
+ */
+export function explainError(
+	err: unknown,
+	rules: readonly ErrorCatalogRule[] = DEFAULT_ERROR_RULES,
+): ErrorExplanation | null {
+	const facts = factsOf(err)
+	for (const rule of rules) {
+		if (!rule.when(facts)) continue
+		// The throw-site rule carries no copy of its own — it exists to give
+		// a hint written at the raise point precedence over a generic one.
+		if (rule.id === 'hint.from_throw_site') {
+			return { id: rule.id, message: facts.message, hint: facts.hint ?? '' }
+		}
+		return { id: rule.id, message: rule.message, hint: rule.hint }
+	}
+	return null
+}

package/src/types/errors/index.ts

@@ -0,0 +1,121 @@
+import type { PlatformError } from '../common/index.js'
+import { ProviderError } from '../provider/errors.js'
+
+/**
+ * What went wrong, at the granularity a HOST actually branches on.
+ *
+ * `PlatformError` was declared and never constructed — a shape nothing
+ * produced and nothing consumed. Meanwhile the runtime threw bare `Error`
+ * everywhere, so a caller catching a failure from `query()` could not tell
+ * "the model rate-limited us" from "the run was configured wrong" from
+ * "that checkpoint does not exist". The only recourse was matching on
+ * message text, which is not an interface.
+ *
+ * The union stays small on purpose: each member exists because a caller
+ * does something DIFFERENT about it. `provider_error` carries the finer
+ * {@link ProviderErrorCode} in `details` rather than being fanned out
+ * here, because that taxonomy answers the runtime's questions, not a
+ * host's.
+ */
+export type NamzuErrorCode =
+	/** The run was set up wrong — missing model, contradictory options. Retrying cannot help. */
+	| 'invalid_config'
+	/** The upstream model call failed. `details.providerCode` narrows it. */
+	| 'provider_error'
+	/** A tool could not be executed or resolved. */
+	| 'tool_error'
+	/** A referenced checkpoint, run or emergency dump does not exist. */
+	| 'not_found'
+	/** A plugin hook failed or refused. */
+	| 'plugin_error'
+	/** The provider or environment cannot do what the run requires. */
+	| 'capability_unavailable'
+	/** Persistence (checkpoint store, run store, workspace) failed. */
+	| 'storage_error'
+	/** Unclassified. Treated as non-retryable. */
+	| 'unknown'
+
+export interface NamzuErrorInit {
+	readonly code: NamzuErrorCode
+	readonly message: string
+	readonly details?: Record<string, unknown>
+	/** Defaults per code; pass explicitly to override. */
+	readonly retryable?: boolean
+	readonly cause?: unknown
+}
+
+/** Codes for which the same operation may succeed if repeated. */
+const RETRYABLE: ReadonlySet<NamzuErrorCode> = new Set<NamzuErrorCode>(['storage_error'])
+
+/**
+ * A runtime failure a host can branch on.
+ *
+ * Implements {@link PlatformError} so the declared shape finally has a
+ * producer, and extends `Error` so it still behaves like one everywhere
+ * that only knows about `Error` — stack, `instanceof`, `cause`.
+ */
+export class NamzuError extends Error implements PlatformError {
+	readonly code: NamzuErrorCode
+	readonly details: Record<string, unknown> | undefined
+	readonly retryable: boolean
+
+	constructor(init: NamzuErrorInit) {
+		super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined)
+		this.name = 'NamzuError'
+		this.code = init.code
+		this.details = init.details
+		this.retryable = init.retryable ?? RETRYABLE.has(init.code)
+	}
+}
+
+export function isNamzuError(err: unknown): err is NamzuError {
+	return err instanceof NamzuError
+}
+
+/**
+ * Normalize ANYTHING thrown into the declared shape.
+ *
+ * This is what makes `PlatformError` worth having: a host wraps one call
+ * and gets a consistent `{ code, message, details, retryable }` no matter
+ * what came out — a `NamzuError`, a `ProviderError`, a plain `Error` from
+ * a dependency, or a thrown string. Without it, "handle errors from the
+ * SDK" means writing the same defensive `instanceof` ladder in every
+ * caller.
+ *
+ * A `ProviderError` keeps its classification: its code lands in
+ * `details.providerCode` and its `retryable` verdict is preserved rather
+ * than recomputed, because that verdict already encodes what the provider
+ * taxonomy knows and this one does not.
+ */
+export function toPlatformError(err: unknown): PlatformError {
+	if (isNamzuError(err)) {
+		return {
+			code: err.code,
+			message: err.message,
+			...(err.details ? { details: err.details } : {}),
+			retryable: err.retryable,
+		}
+	}
+
+	if (err instanceof ProviderError) {
+		return {
+			code: 'provider_error',
+			message: err.message,
+			details: {
+				providerCode: err.code,
+				...(err.providerId !== undefined ? { providerId: err.providerId } : {}),
+				...(err.status !== undefined ? { status: err.status } : {}),
+				...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
+			},
+			retryable: err.retryable,
+		}
+	}
+
+	if (err instanceof Error) {
+		return { code: 'unknown', message: err.message, retryable: false }
+	}
+
+	// A thrown non-Error is rare and usually a bug elsewhere, but losing it
+	// entirely is worse than reporting it as-is.
+	return { code: 'unknown', message: String(err), retryable: false }
+}

package/src/types/guardrail/index.ts

@@ -0,0 +1,62 @@
+import type { RunId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
+
+/**
+ * Guardrails inspect what goes INTO a run and what comes OUT of it.
+ *
+ * namzu had three good gates on tool calls — probe veto, `VerificationGate`,
+ * HITL review — and they all point the same way: they protect the world
+ * from the agent. Nothing protected the user from the agent's own output,
+ * and nothing looked at the prompt before the run started.
+ *
+ * The concrete failure: an agent reads a credential file, the read is
+ * allowed (it is a legitimate file), the secret enters context, and it is
+ * repeated in the final answer. Every existing gate is upstream of that
+ * and none of them fire.
+ */
+
+export interface InputGuardrailContext {
+	readonly runId: RunId
+	/** The messages the run is about to start with. */
+	readonly messages: readonly Message[]
+	/** The assembled system prompt, when there is one. */
+	readonly systemPrompt?: string
+}
+
+export interface OutputGuardrailContext {
+	readonly runId: RunId
+	/** The run's final assistant text. */
+	readonly output: string
+	/** Full message history, for a guardrail that needs the conversation. */
+	readonly messages: readonly Message[]
+}
+
+/**
+ * What a guardrail decided.
+ *
+ * `rewrite` matters as much as `tripwire`: a PII policy usually wants to
+ * redact an account number, not throw the whole answer away. A gate that
+ * can only abort forces every redaction use case to be implemented
+ * somewhere else.
+ */
+export type GuardrailVerdict =
+	| { readonly action: 'pass' }
+	| { readonly action: 'block'; readonly reason: string }
+	| { readonly action: 'rewrite'; readonly output: string; readonly reason?: string }
+
+export type InputGuardrail = (
+	ctx: InputGuardrailContext,
+) => GuardrailVerdict | Promise<GuardrailVerdict>
+
+export type OutputGuardrail = (
+	ctx: OutputGuardrailContext,
+) => GuardrailVerdict | Promise<GuardrailVerdict>
+
+/** Convenience: a named guardrail, so a block can say which rule tripped. */
+export interface NamedGuardrail<T> {
+	readonly name: string
+	readonly check: T
+}
+
+export type InputGuardrailSpec = InputGuardrail | NamedGuardrail<InputGuardrail>
+export type OutputGuardrailSpec = OutputGuardrail | NamedGuardrail<OutputGuardrail>