@kindgi/guardrails 0.0.0-bootstrap.0 → 0.1.0

package/src/guardrail.schema.json

@@ -0,0 +1,261 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/guardrail.schema.json",
+  "$comment": "schema-version: 1.1.0",
+  "title": "Guardrail",
+  "description": "An assertion about agent behavior. Enforced at runtime (halt / retry / escalate / log-only / compensate per guardrail) AND in CI (blocks builds). Same definition, two enforcement paths — no drift between what tests check and what prod enforces. Zero-LLM checks are default (fast, deterministic); LLM-judge scorers are an opt-in class with explicit cost declaration. Schema-version 1.1.0 matches the `Guardrail` type: `check` is required, a `retry` action needs `maxAttempts`, `kind` and `on-violation` accept any non-empty string (the built-ins are listed as `examples`), and `sandbox` / `limits` / `network` / `needsSpec` are allowed.",
+  "type": "object",
+  "required": ["id", "kind", "check", "action"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique guardrail identifier."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable name."
+    },
+    "description": {
+      "type": "string",
+      "description": "What this guardrail guarantees, and what happens if violated."
+    },
+    "kind": {
+      "type": "string",
+      "minLength": 1,
+      "examples": ["zero-llm", "llm-judge", "external"],
+      "description": "How the guardrail is checked. Open string: the engine dispatches it to the execution strategy registered for that kind, and `defineGuardrail` requires a registered check of the same kind. Built-in kinds: 'zero-llm' = pure function over run trace (default, fast, deterministic). 'llm-judge' = uses a model to score (opt-in, costs money). 'external' = evaluated outside the engine by a caller-registered strategy (the built-in 'external' strategy returns an error). Adapters can register strategies for their own kinds."
+    },
+    "check": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Id of the check in the CheckRegistry. For zero-llm: a built-in check ('must-cite', 'never-call-tool', 'max-tool-calls', 'output-matches', 'tool-order', 'required-substring', 'forbidden-substring') or a custom check id. For llm-judge: the id of a registered check of kind 'llm-judge' (the judge is configured by config and judgeCapabilities). For external and adapter kinds: an id the kind's strategy understands. Required since schema-version 1.1.0 (`defineGuardrail` already failed without a registered check)."
+    },
+    "config": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Check-specific configuration. Interpreted by the check implementation."
+    },
+    "action": {
+      "$ref": "#/$defs/Action"
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["info", "warn", "error", "critical"],
+      "default": "error"
+    },
+    "scope": {
+      "$ref": "#/$defs/Scope",
+      "description": "When this guardrail applies: 'always' (every run), 'ci-only' (blocks CI, not runtime), 'runtime-only' (runtime enforcement, not CI), or a per-agent/per-flow selector."
+    },
+    "budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "For llm-judge guardrails: cost budget per invocation. Declarative — not enforced by the runtime.",
+      "properties": {
+        "maxCostUsd": {
+          "type": "number",
+          "minimum": 0
+        },
+        "maxLatencyMs": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "sandbox": {
+      "type": "string",
+      "enum": ["none", "context-isolated", "strict"],
+      "description": "Isolation posture the runtime enforces around the check's handler. Same values as a tool's `sandbox`. Added in schema-version 1.1.0."
+    },
+    "limits": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Sandbox-enforced resource caps while the check runs. Same shape as a tool's `limits`. Added in schema-version 1.1.0.",
+      "properties": {
+        "memMB": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "cpuMs": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "required": ["memMB", "cpuMs"]
+    },
+    "network": {
+      "type": "object",
+      "description": "Network egress policy the sandbox honors while the check runs. Discriminated on `kind`; same shape as a tool's `network`. Added in schema-version 1.1.0.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": ["none", "unrestricted"]
+            }
+          },
+          "required": ["kind"]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "allowlist"
+            },
+            "hosts": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "required": ["kind", "hosts"]
+        }
+      ]
+    },
+    "needsSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Typed discriminated needs of the check (env / secrets / config / capabilities / bindings). Same shape as a tool's `needsSpec`. Added in schema-version 1.1.0.",
+      "properties": {
+        "env": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object"
+          }
+        },
+        "secrets": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object"
+          }
+        },
+        "config": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object"
+          }
+        },
+        "capabilities": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "bindings": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "codeArtifactRef": {
+      "description": "Handler-artifact pointer for the guardrail's check implementation. Discriminated on `kind`: `oci` is the deploy-pipeline shape (image + module path + artifactVersion); `filesystem` is the local-development shape — absolute host path at the check module. Production servers SHOULD reject `filesystem`.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "oci" },
+            "imageRef": { "type": "string", "minLength": 1 },
+            "modulePath": { "type": "string", "minLength": 1 },
+            "artifactVersion": { "type": "string", "minLength": 1 }
+          },
+          "required": ["kind", "imageRef", "modulePath", "artifactVersion"]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "filesystem" },
+            "modulePath": { "type": "string", "minLength": 1 }
+          },
+          "required": ["kind", "modulePath"]
+        }
+      ]
+    },
+    "judgeCapabilities": {
+      "type": "object",
+      "description": "For llm-judge guardrails: capability declaration for the judge model. Routed through `@kindgi/capabilities` over the providers bound for evaluation; when the caller passes a tenant policy (an agent turn passes its own), the judge is routed under it. BYO judges supported.",
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "Action": {
+      "type": "object",
+      "required": ["on-violation"],
+      "additionalProperties": false,
+      "properties": {
+        "on-violation": {
+          "type": "string",
+          "minLength": 1,
+          "examples": ["halt", "retry", "escalate", "log-only", "compensate"],
+          "description": "What happens when the guardrail fires. Open string: any non-empty name is accepted here, and an action handler registered under that name applies it; when the caller evaluates with an action-handler registry, a name with no handler fails with `unknown-action`. Built-in actions: 'halt' = fail the run. 'retry' = re-execute the step (needs `retry.maxAttempts`). 'escalate' = route to HITL review. 'log-only' = record but don't block. 'compensate' = invoke a compensation action."
+        },
+        "retry": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "For on-violation = 'retry'.",
+          "required": ["maxAttempts"],
+          "properties": {
+            "maxAttempts": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10
+            }
+          }
+        },
+        "escalateTo": {
+          "type": "string",
+          "description": "For on-violation = 'escalate': reviewer role or queue id."
+        },
+        "compensateWith": {
+          "type": "string",
+          "description": "For on-violation = 'compensate': tool id to invoke as compensation."
+        }
+      }
+    },
+    "Scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "when": {
+          "type": "string",
+          "enum": ["always", "ci-only", "runtime-only"],
+          "default": "always"
+        },
+        "agents": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Agent ids this guardrail applies to. Empty = all agents."
+        },
+        "flows": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Flow ids this guardrail applies to. Empty = all flows."
+        },
+        "tenants": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Tenant ids this guardrail applies to. Empty = all tenants."
+        }
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+export { GUARDRAIL_SCHEMA_URI, defineGuardrail, validateGuardrailSpec } from './define.js';
+export { defineCheck } from './define-check.js';
+export type { DefineCheckSpec, DefinedCheck, InferCheckConfig } from './define-check.js';
+export { BUILT_IN_CHECK_IDS, createCheckRegistry } from './checks.js';
+export {
+  BUILT_IN_ACTION_HANDLERS,
+  compensateHandler,
+  createActionHandlerRegistry,
+  escalateHandler,
+  haltHandler,
+  logOnlyHandler,
+  noopHandler,
+  retryHandler,
+} from './action-handler.js';
+export type {
+  ActionContext,
+  ActionHandler,
+  ActionHandlerRegistry,
+  ActionResult,
+} from './action-handler.js';
+export { builtInStrategies, evaluateAll, evaluateGuardrail, violations } from './engine.js';
+export type { EvaluationOutcome } from './engine.js';
+export {
+  createExecutionStrategyRegistry,
+  externalStrategy,
+  makeLlmJudgeStrategy,
+  zeroLlmStrategy,
+} from './execution-strategy.js';
+export type {
+  ExecutionStrategy,
+  ExecutionStrategyRegistry,
+  StrategyError,
+  StrategyResult,
+} from './execution-strategy.js';
+export { invokeJudge } from './judge.js';
+export type { LlmJudgeConfig } from './judge.js';
+export type {
+  Action,
+  Budget,
+  BuiltInGuardrailKind,
+  BuiltInOnViolation,
+  CheckFunction,
+  CheckRegistry,
+  CheckResult,
+  CodeArtifactRef,
+  EvaluationBindings,
+  EvaluationResult,
+  Guardrail,
+  GuardrailKind,
+  GuardrailSeverity,
+  JsonSchema,
+  ModelCallRecord,
+  NetworkPolicy,
+  OnViolation,
+  RegisteredCheck,
+  RunTrace,
+  RuntimeLimits,
+  SandboxMode,
+  Scope,
+  ScopeWhen,
+  ToolCallRecord,
+  ToolResultRecord,
+  TypedNeeds,
+} from './types.js';
+export { BUILT_IN_GUARDRAIL_KINDS, BUILT_IN_ON_VIOLATIONS } from './types.js';
+export type {
+  InvalidCheckConfigError,
+  InvalidCheckDefinitionError,
+  InvalidGuardrailError,
+  GuardrailError,
+  JudgeMissingError,
+  JudgeRoutingError,
+  ScopeMismatchError,
+  UnknownActionError,
+  UnknownCheckError,
+} from './errors.js';

package/src/judge.ts

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { route } from '@kindgi/capabilities';
+import type { Capability, ModelInfo, ModelProvider } from '@kindgi/capabilities';
+
+import type { JudgeMissingError, JudgeRoutingError } from './errors.js';
+import type { CheckResult, EvaluationBindings, RunTrace } from './types.js';
+
+/**
+ * Configuration for an llm-judge guardrail, read from the guardrail's
+ * `config`. `invokeJudge` builds the prompt around `rubric`.
+ */
+export interface LlmJudgeConfig {
+  /** The rubric prompt — what the judge model evaluates against. */
+  readonly rubric: string;
+  /**
+   * How the judge should respond. `'pass-fail'` (default) expects a
+   * response starting with PASS or FAIL and a reason. `'score'` expects
+   * a numeric score in [0, 1] on the first line, compared to `threshold`.
+   */
+  readonly responseFormat?: 'pass-fail' | 'score';
+  /** For `'score'` format — pass threshold (inclusive). Default `0.5`. */
+  readonly threshold?: number;
+  /** Optional override for the model's temperature. */
+  readonly temperature?: number;
+}
+
+/**
+ * Invoke an LLM judge to evaluate a guardrail. Resolves a model via
+ * the capability router (or uses `bindings.judgeProvider` if set), sends
+ * a structured judgment prompt including the run trace + rubric, parses
+ * the response.
+ */
+export async function invokeJudge(
+  config: LlmJudgeConfig,
+  capability: Capability,
+  trace: RunTrace,
+  bindings: EvaluationBindings,
+): Promise<CheckResult | { readonly error: JudgeMissingError | JudgeRoutingError }> {
+  const provider = await resolveJudgeProvider(capability, trace, bindings);
+  if ('error' in provider) return provider;
+
+  const responseFormat = config.responseFormat ?? 'pass-fail';
+  const rubric = config.rubric;
+  const prompt = buildJudgePrompt(rubric, responseFormat, trace);
+
+  const result = await provider.provider.invoke({
+    model: provider.model.name,
+    messages: [
+      {
+        role: 'system',
+        content:
+          responseFormat === 'pass-fail'
+            ? 'You are an evaluator. Respond starting with PASS or FAIL on the first line, then a brief reason on the next line. No preamble.'
+            : 'You are an evaluator. Respond with a numeric score from 0 to 1 on the first line, then a brief reason on the next line. No preamble.',
+      },
+      { role: 'user', content: prompt },
+    ],
+    ...(config.temperature !== undefined && { temperature: config.temperature }),
+    maxOutputTokens: 256,
+    ...(bindings.abortSignal !== undefined && { abortSignal: bindings.abortSignal }),
+  });
+
+  const text = result.message.content.trim();
+  return parseJudgeResponse(text, responseFormat, config.threshold);
+}
+
+interface ResolvedProvider {
+  readonly provider: ModelProvider;
+  readonly model: ModelInfo;
+  readonly reason: string;
+}
+
+async function resolveJudgeProvider(
+  capability: Capability,
+  trace: RunTrace,
+  bindings: EvaluationBindings,
+): Promise<ResolvedProvider | { readonly error: JudgeMissingError | JudgeRoutingError }> {
+  if (bindings.judgeProvider !== undefined && bindings.tenantPolicy !== undefined) {
+    // Override under a tenant policy: route over the override alone, so
+    // the policy (and the judge capability) still apply.
+    const decision = route({
+      capability,
+      providers: [bindings.judgeProvider],
+      tenantPolicy: bindings.tenantPolicy,
+    });
+    if (decision.kind === 'err') {
+      const err: JudgeRoutingError = {
+        code: 'judge-routing-failed',
+        message: `Explicit judgeProvider "${bindings.judgeProvider.metadata.id}" is not allowed for this tenant: ${decision.error.message}`,
+        guardrailId: '<unknown>' as never,
+        cause: decision.error,
+      };
+      return { error: err };
+    }
+    return {
+      provider: decision.value.provider,
+      model: decision.value.model,
+      reason: `explicit judgeProvider override; ${decision.value.reason}`,
+    };
+  }
+  if (bindings.judgeProvider !== undefined) {
+    // Direct provider override without a tenant policy — no routing
+    // decision, so pick the provider's first advertised model. Callers
+    // who need a specific model within the override should go through
+    // `providerRegistry` + the router.
+    const provider = bindings.judgeProvider;
+    const first = provider.metadata.models[0];
+    if (first === undefined) {
+      const err: JudgeRoutingError = {
+        code: 'judge-routing-failed',
+        message: `Explicit judgeProvider "${provider.metadata.id}" exposes zero models`,
+        guardrailId: '<unknown>' as never,
+        cause: {
+          code: 'capability-unsatisfiable',
+          message: 'judgeProvider has no models',
+          reasons: [],
+        },
+      };
+      return { error: err };
+    }
+    return { provider, model: first, reason: 'explicit judgeProvider override' };
+  }
+  if (bindings.providerRegistry === undefined) {
+    const err: JudgeMissingError = {
+      code: 'judge-missing',
+      message:
+        'llm-judge guardrail evaluated without providerRegistry or judgeProvider in bindings',
+      guardrailId: '<unknown>' as never,
+    };
+    return { error: err };
+  }
+  const decision = route({
+    capability,
+    providers: bindings.providerRegistry.list(trace.tenantId),
+    ...(bindings.tenantPolicy !== undefined && { tenantPolicy: bindings.tenantPolicy }),
+  });
+  if (decision.kind === 'err') {
+    const err: JudgeRoutingError = {
+      code: 'judge-routing-failed',
+      message: `Judge routing failed: ${decision.error.message}`,
+      guardrailId: '<unknown>' as never,
+      cause: decision.error,
+    };
+    return { error: err };
+  }
+  return {
+    provider: decision.value.provider,
+    model: decision.value.model,
+    reason: decision.value.reason,
+  };
+}
+
+function buildJudgePrompt(rubric: string, format: 'pass-fail' | 'score', trace: RunTrace): string {
+  const lines = [
+    'Evaluate the following agent run against the rubric.',
+    '',
+    '=== Rubric ===',
+    rubric,
+    '',
+    '=== Run output ===',
+    trace.output ?? '<empty>',
+    '',
+    '=== Tool calls ===',
+    trace.toolCalls.length === 0
+      ? '<none>'
+      : trace.toolCalls.map((c) => `- ${c.toolName}(${JSON.stringify(c.arguments)})`).join('\n'),
+    '',
+    format === 'pass-fail'
+      ? 'Respond PASS or FAIL then reason.'
+      : 'Respond with a score in [0, 1] then reason.',
+  ];
+  return lines.join('\n');
+}
+
+function parseJudgeResponse(
+  raw: string,
+  format: 'pass-fail' | 'score',
+  threshold: number | undefined,
+): CheckResult {
+  if (format === 'pass-fail') {
+    const upper = raw.toUpperCase();
+    if (upper.startsWith('PASS')) {
+      const reasonLine = raw.split(/\r?\n/)[1]?.trim() ?? '';
+      const result: CheckResult = { passed: true, judgeResponse: raw };
+      return reasonLine.length > 0 ? { ...result, reason: reasonLine } : result;
+    }
+    if (upper.startsWith('FAIL')) {
+      const reasonLine = raw.split(/\r?\n/)[1]?.trim() ?? '';
+      return {
+        passed: false,
+        reason: reasonLine.length > 0 ? reasonLine : 'judge returned FAIL',
+        judgeResponse: raw,
+      };
+    }
+    return {
+      passed: false,
+      reason: `judge response did not start with PASS/FAIL: ${raw.slice(0, 80)}`,
+      judgeResponse: raw,
+    };
+  }
+  // score format
+  const firstLine = raw.split(/\r?\n/)[0]?.trim() ?? '';
+  const score = Number.parseFloat(firstLine);
+  if (!Number.isFinite(score)) {
+    return {
+      passed: false,
+      reason: `judge did not return a numeric score: ${firstLine}`,
+      judgeResponse: raw,
+    };
+  }
+  const cutoff = threshold ?? 0.5;
+  const reasonLine = raw.split(/\r?\n/)[1]?.trim() ?? '';
+  return {
+    passed: score >= cutoff,
+    reason: reasonLine.length > 0 ? reasonLine : `score=${score}, threshold=${cutoff}`,
+    judgeResponse: raw,
+    attributes: { score, threshold: cutoff },
+  };
+}