@handlebar/governance-schema 0.0.1

package/dist/rules/action.types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Actions to take when a rule matches.
+ * - Future: extend with "log", "notify", "humanInTheLoop", etc.
+ */
+export type RuleAction = {
+    type: "block";
+} | {
+    type: "allow";
+};

package/dist/rules/condition.types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Strongly-typed rule condition/action schema for rule enforcement.
+ *
+ * Notes:
+ * - Conditions are composable via AND / OR / NOT
+ * - Actions are currently limited to "block" and "allow" but are modeled for future extension
+ */
+/**
+ * Case-insensitive glob pattern (e.g. "search-*", "*-prod", "exact-name")
+ */
+export type Glob = string;
+/**
+ * JSON-safe value for condition parameters and custom function args.
+ */
+export type JSONValue = string | number | boolean | null | {
+    [k: string]: JSONValue;
+} | JSONValue[];
+/**
+ * Match on a tool's name.
+ * - glob comparator supports wildcard matching
+ * - in comparator permits list membership check
+ */
+export type ToolNameCondition = {
+    kind: "toolName";
+    op: "eq" | "neq" | "contains" | "startsWith" | "endsWith" | "glob";
+    value: string | Glob;
+} | {
+    kind: "toolName";
+    op: "in";
+    value: (string | Glob)[];
+};
+/**
+ * Match on tool tags present on the tool.
+ * - has: single tag must be present
+ * - anyOf: at least one tag present
+ * - allOf: every provided tag must be present
+ */
+export type ToolTagCondition = {
+    kind: "toolTag";
+    op: "has";
+    tag: string;
+} | {
+    kind: "toolTag";
+    op: "anyOf";
+    tags: string[];
+} | {
+    kind: "toolTag";
+    op: "allOf";
+    tags: string[];
+};
+/**
+ * Scope for execution time measurement.
+ * - "tool": the single tool call duration
+ * - "total": end-to-end agent run (from start to now)
+ */
+export type ExecutionTimeScope = "tool" | "total";
+/**
+ * Match against execution time thresholds (milliseconds).
+ */
+export type ExecutionTimeCondition = {
+    kind: "executionTime";
+    scope: ExecutionTimeScope;
+    op: "gt" | "gte" | "lt" | "lte" | "eq" | "neq";
+    ms: number;
+};
+/**
+ * Enforce sequencing constraints within the current run history.
+ * - mustHaveCalled: all listed tool name patterns must have been called earlier
+ * - mustNotHaveCalled: none of the listed patterns may have been called earlier
+ */
+export type SequenceCondition = {
+    kind: "sequence";
+    mustHaveCalled?: Glob[];
+    mustNotHaveCalled?: Glob[];
+};
+/**
+ * Select tools for counting within a run.
+ * - by toolName: count calls whose name matches any provided glob patterns
+ * - by toolTag: count calls whose tool includes any of the provided tags
+ */
+export type MaxCallsSelector = {
+    by: "toolName";
+    patterns: Glob[];
+} | {
+    by: "toolTag";
+    tags: string[];
+};
+/**
+ * Assert a maximum number of calls within a run for the selected tools (inclusive).
+ */
+export type MaxCallsCondition = {
+    kind: "maxCalls";
+    selector: MaxCallsSelector;
+    max: number;
+};
+/**
+ * Delegate condition evaluation to a user-defined function.
+ * - `name` is resolved by the host SDK/application
+ * - `args` is an opaque, JSON-serializable payload consumed by user code
+ */
+export type CustomFunctionCondition = {
+    kind: "custom";
+    name: string;
+    args?: JSONValue;
+};
+export type AndCondition = {
+    kind: "and";
+    all: RuleCondition[];
+};
+export type OrCondition = {
+    kind: "or";
+    any: RuleCondition[];
+};
+export type NotCondition = {
+    kind: "not";
+    not: RuleCondition;
+};
+/**
+ * The full condition algebra supported by the rule engine.
+ */
+export type RuleCondition = ToolNameCondition | ToolTagCondition | ExecutionTimeCondition | SequenceCondition | MaxCallsCondition | CustomFunctionCondition | AndCondition | OrCondition | NotCondition;

package/dist/rules/constructors.d.ts

@@ -0,0 +1,55 @@
+import type { RuleAction } from "./action.types";
+import type { Glob, JSONValue, RuleCondition } from "./condition.types";
+import type { Rule, RuleConfig, RuleWhen } from "./rule.types";
+export declare const and: (...all: RuleCondition[]) => RuleCondition;
+export declare const or: (...any: RuleCondition[]) => RuleCondition;
+export declare const not: (cond: RuleCondition) => RuleCondition;
+export declare const toolName: {
+    eq: (value: string | Glob) => RuleCondition;
+    neq: (value: string | Glob) => RuleCondition;
+    glob: (value: Glob) => RuleCondition;
+    in: (values: (string | Glob)[]) => RuleCondition;
+    startsWith: (value: string) => RuleCondition;
+    endsWith: (value: string) => RuleCondition;
+    contains: (value: string) => RuleCondition;
+};
+export declare const toolTag: {
+    has: (tag: string) => RuleCondition;
+    anyOf: (tags: string[]) => RuleCondition;
+    allOf: (tags: string[]) => RuleCondition;
+};
+export declare const execTime: {
+    gt: (scope: "tool" | "total", ms: number) => RuleCondition;
+    gte: (scope: "tool" | "total", ms: number) => RuleCondition;
+    lt: (scope: "tool" | "total", ms: number) => RuleCondition;
+    lte: (scope: "tool" | "total", ms: number) => RuleCondition;
+};
+export declare const sequence: (opts: {
+    mustHaveCalled?: Glob[];
+    mustNotHaveCalled?: Glob[];
+}) => RuleCondition;
+export declare const maxCalls: (opts: {
+    selector: {
+        by: "toolName";
+        patterns: Glob[];
+    } | {
+        by: "toolTag";
+        tags: string[];
+    };
+    max: number;
+}) => RuleCondition;
+export declare const custom: (name: string, args?: JSONValue) => RuleCondition;
+export declare const block: () => RuleAction;
+export declare const allow: () => RuleAction;
+type BaseRuleInput = {
+    priority: number;
+    if: RuleCondition;
+    then: RuleAction[];
+};
+export declare const rule: ((when: RuleWhen, input: BaseRuleInput) => RuleConfig) & {
+    pre: (input: BaseRuleInput) => RuleConfig;
+    post: (input: BaseRuleInput) => RuleConfig;
+    both: (input: BaseRuleInput) => RuleConfig;
+};
+export declare function configToRule(config: RuleConfig): Rule;
+export {};

package/dist/rules/rule.types.d.ts

@@ -0,0 +1,34 @@
+import z from "zod";
+import type { RuleAction } from "./action.types";
+import type { RuleCondition } from "./condition.types";
+/**
+ * Timing for rule evaluation relative to tool call lifecycle.
+ * - pre: evaluate before the tool executes
+ * - post: evaluate after the tool executes
+ * - both: evaluate both pre and post
+ */
+export type RuleWhen = "pre" | "post" | "both";
+/**
+ * A single rule definition combining condition, actions, timing, and priority.
+ * This can be stored as JSONB or constructed/transmitted over the wire.
+ */
+export declare const RuleConfigSchema: z.ZodObject<{
+    priority: z.ZodNumber;
+    when: z.ZodCustom<RuleWhen, RuleWhen>;
+    condition: z.ZodCustom<RuleCondition, RuleCondition>;
+    actions: z.ZodArray<z.ZodCustom<RuleAction, RuleAction>>;
+}, z.core.$strip>;
+/**
+ * Rule object coming from API.
+ */
+export declare const RuleSchema: z.ZodIntersection<z.ZodObject<{
+    id: z.ZodUUID;
+    policy_id: z.ZodUUID;
+}, z.core.$strip>, z.ZodObject<{
+    priority: z.ZodNumber;
+    when: z.ZodCustom<RuleWhen, RuleWhen>;
+    condition: z.ZodCustom<RuleCondition, RuleCondition>;
+    actions: z.ZodArray<z.ZodCustom<RuleAction, RuleAction>>;
+}, z.core.$strip>>;
+export type RuleConfig = z.infer<typeof RuleConfigSchema>;
+export type Rule = z.infer<typeof RuleSchema>;

package/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "@handlebar/governance-schema",
+	"version": "0.0.1",
+	"private": false,
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"license": "Apache-2.0",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "bun run build.ts && tsc -p tsconfig.json"
+	},
+	"keywords": [
+		"llm",
+		"agent",
+		"agentic",
+		"ai",
+		"sdk",
+		"governance",
+		"tool-calling",
+		"mcp",
+		"handlebar"
+	],
+	"dependencies": {
+		"zod": "^4.1.12"
+	}
+}