@handlebar/governance-schema 0.0.6-dev.4 → 0.0.6-dev.6

package/dist/audit/events.d.ts

@@ -192,7 +192,7 @@ export declare const ToolResultEventSchema: z.ZodObject<{
                 duration_ms: "duration_ms";
                 records_in: "records_in";
                 records_out: "records_out";
-            }>, z.ZodObject<{
+            }> & z.core.$partial, z.ZodObject<{
                 value: z.ZodNumber;
                 unit: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
@@ -471,7 +471,7 @@ export declare const AuditEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 duration_ms: "duration_ms";
                 records_in: "records_in";
                 records_out: "records_out";
-            }>, z.ZodObject<{
+            }> & z.core.$partial, z.ZodObject<{
                 value: z.ZodNumber;
                 unit: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;

package/dist/audit/run-metrics.d.ts

@@ -14,7 +14,7 @@ export declare const AgentMetrics: z.ZodObject<{
         duration_ms: "duration_ms";
         records_in: "records_in";
         records_out: "records_out";
-    }>, z.ZodObject<{
+    }> & z.core.$partial, z.ZodObject<{
         value: z.ZodNumber;
         unit: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;

package/dist/index.d.ts

@@ -4,6 +4,4 @@ export * from "./audit/events.llm";
 export * from "./audit/run-metrics";
 export * from "./audit/governance-actions";
 export type { EndUserConfig, EndUserGroupConfig } from "./enduser.types";
-export * from "./rules/action.types";
-export * from "./rules/condition.types";
-export * from "./rules/rule.types";
+export * from "./rules";

package/dist/index.js

@@ -12668,7 +12668,7 @@ var AgentMetricInfo = exports_external.object({
   value: exports_external.number(),
   unit: exports_external.string().min(1).max(64).optional()
 });
-var InbuiltAgentMetrics = exports_external.record(InbuiltAgentMetricKind, AgentMetricInfo);
+var InbuiltAgentMetrics = exports_external.partialRecord(InbuiltAgentMetricKind, AgentMetricInfo);
 var CustomAgentMetrics = exports_external.record(CustomAgentMetricKind, AgentMetricInfo);
 var AgentMetrics = exports_external.object({
   inbuilt: InbuiltAgentMetrics,
@@ -12778,24 +12778,11 @@ var AuditEventSchema = exports_external.discriminatedUnion("kind", [
   ErrorEventSchema,
   MessageEventSchema
 ]);
-// src/rules/rule.types.ts
-var RuleConfigSchema = exports_external.object({
-  priority: exports_external.number().min(0),
-  when: exports_external.custom(),
-  condition: exports_external.custom(),
-  actions: exports_external.array(exports_external.custom())
-});
-var RuleSchema = exports_external.object({
-  id: exports_external.uuid({ version: "v7" }),
-  policy_id: exports_external.uuid({ version: "v7" })
-}).and(RuleConfigSchema);
 export {
   ToolResultEventSchema,
   ToolDecisionEventSchema,
   RunStartedEventSchema,
   RunEndedEventSchema,
-  RuleSchema,
-  RuleConfigSchema,
   MessageSchema,
   MessageRoleSchema,
   MessageKindSchema,

package/dist/rules/common.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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[];

package/dist/rules/condition.d.ts

@@ -0,0 +1,19 @@
+import type { CustomFunctionCondition } from "./custom";
+import type { MetricWindowCondition } from "./metrics";
+import type { EndUserTagCondition } from "./enduser";
+import type { RequireSubjectCondition, SignalCondition } from "./signals";
+import type { TimeGateCondition, ExecutionTimeCondition } from "./time";
+import type { MaxCallsCondition, SequenceCondition, ToolNameCondition, ToolTagCondition } from "./tools";
+export type AndCondition = {
+    kind: "and";
+    all: RuleCondition[];
+};
+export type OrCondition = {
+    kind: "or";
+    any: RuleCondition[];
+};
+export type NotCondition = {
+    kind: "not";
+    not: RuleCondition;
+};
+export type RuleCondition = ToolNameCondition | ToolTagCondition | EndUserTagCondition | ExecutionTimeCondition | SequenceCondition | MaxCallsCondition | CustomFunctionCondition | MetricWindowCondition | TimeGateCondition | RequireSubjectCondition | SignalCondition | AndCondition | OrCondition | NotCondition;

package/dist/rules/custom.d.ts

@@ -0,0 +1,11 @@
+import type { JSONValue } from "./common";
+/**
+ * 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;
+};

package/dist/rules/effects.d.ts

@@ -0,0 +1,18 @@
+export type RuleEffectKind = "allow" | "hitl" | "block";
+/**
+ * Direct impact of a rule breach.
+ *
+ * RuleEffect has an immediate impact on the agent run/tool action.
+ * This is in contract to side effects (yet to be defined),
+ * which would include "log" or "modify context".
+ */
+export type RuleEffect = {
+    type: "allow";
+    reason?: string;
+} | {
+    type: "hitl";
+    reason?: string;
+} | {
+    type: "block";
+    reason?: string;
+};

package/dist/rules/enduser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Match on arbitrary tags assigned to the enduser.
+ * "enduser" in this context means the users of a Handlebar user.
+ * - has: existence AND truthiness of the tag. E.g. "has:tier" would be false if "tier=0", "tier=false", or no "tier" tag exists.
+ * - hasValue: tag exists and has an exact given value
+ */
+export type EndUserTagCondition = {
+    kind: "enduserTag";
+    op: "has";
+    tag: string;
+} | {
+    kind: "enduserTag";
+    op: "hasValue";
+    tag: string;
+    value: string;
+} | {
+    kind: "enduserTag";
+    op: "hasValueAny";
+    tag: string;
+    values: string[];
+};

package/dist/rules/index.d.ts

@@ -0,0 +1,10 @@
+export type { RuleCondition } from "./condition";
+export type { RulePhase, RuleSelector, Rule } from "./rule";
+export type { RuleEffect, RuleEffectKind } from "./effects";
+export type { RequireSubjectCondition, SignalCondition } from "./signals";
+export type { TimeGateCondition, ExecutionTimeCondition, ExecutionTimeScope } from "./time";
+export type { MetricWindowCondition } from "./metrics";
+export type { CustomFunctionCondition } from "./custom";
+export type { EndUserTagCondition } from "./enduser";
+export type { MaxCallsCondition, MaxCallsSelector, SequenceCondition, ToolNameCondition, ToolTagCondition } from "./tools";
+export type { Glob, JSONValue } from "./common";

package/dist/rules/metrics.d.ts

@@ -0,0 +1,24 @@
+import type { Glob } from "./common";
+import type { RuleEffectKind } from "./effects";
+type MetricRef = {
+    kind: "inbuilt";
+    key: "bytes_in" | "bytes_out" | "records_in" | "records_out" | "duration_ms";
+} | {
+    kind: "custom";
+    key: string;
+};
+export type MetricWindowCondition = {
+    kind: "metricWindow";
+    scope: "agent" | "agent_user";
+    metric: MetricRef;
+    aggregate: "sum" | "avg" | "max" | "min" | "count";
+    windowSeconds: number;
+    filter?: {
+        toolName?: Glob | Glob[];
+        toolTag?: string | string[];
+    };
+    op: "gt" | "gte" | "lt" | "lte" | "eq" | "neq";
+    value: number;
+    onMissing?: RuleEffectKind;
+};
+export {};

package/dist/rules/rule.d.ts

@@ -0,0 +1,23 @@
+import type { Glob } from "./common";
+import type { RuleCondition } from "./condition";
+import type { RuleEffectKind, RuleEffect } from "./effects";
+export type RulePhase = "tool.before" | "tool.after";
+export type RuleSelector = {
+    phase: RulePhase;
+    tool?: {
+        name?: Glob | Glob[];
+        tagsAll?: string[];
+        tagsAny?: string[];
+    };
+};
+export type Rule = {
+    id: string;
+    policyId: string;
+    enabled: boolean;
+    priority: number;
+    name: string;
+    selector: RuleSelector;
+    condition: RuleCondition;
+    effect: RuleEffect;
+    onMissing?: RuleEffectKind;
+};

package/dist/rules/signals.d.ts

@@ -0,0 +1,44 @@
+import type { JSONValue } from "./common";
+import type { RuleEffectKind } from "./effects";
+/**
+ * Requires the existence of subject data at runtime.
+ *
+ * Handlebar is agnostic to the source of the data,
+ * so long as it is present in the engine runtime.
+ */
+export type RequireSubjectCondition = {
+    kind: "requireSubject";
+    subjectType: string;
+    idSystem?: string;
+};
+type SignalBinding = {
+    from: "endUserId";
+} | {
+    from: "endUserTag";
+    tag: string;
+} | {
+    from: "toolName";
+} | {
+    from: "toolTag";
+    tag: string;
+} | {
+    from: "toolArg";
+    path: string;
+} | {
+    from: "subject";
+    subjectType: string;
+    role?: string;
+    field?: "id" | "idSystem";
+} | {
+    from: "const";
+    value: JSONValue;
+};
+export type SignalCondition = {
+    kind: "signal";
+    key: string;
+    args: Record<string, SignalBinding>;
+    op: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "nin";
+    value: JSONValue;
+    onMissing?: RuleEffectKind;
+};
+export {};

package/dist/rules/time.d.ts

@@ -0,0 +1,28 @@
+export type TimeGateCondition = {
+    kind: "timeGate";
+    timezone: {
+        source: "endUserTag";
+        tag: string;
+        fallback?: "org";
+    };
+    windows: Array<{
+        days: ("mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun")[];
+        start: string;
+        end: 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;
+};

package/dist/rules/tools.d.ts

@@ -0,0 +1,64 @@
+import type { Glob } from "./common";
+/**
+ * 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[];
+};
+/**
+* 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;
+};

package/dist/rules/v2/common.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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[];

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

@@ -0,0 +1,19 @@
+import type { CustomFunctionCondition } from "./custom";
+import type { MetricWindowCondition } from "./metrics";
+import type { EndUserTagCondition } from "./enduser";
+import type { RequireSubjectCondition, SignalCondition } from "./signals";
+import type { TimeGateCondition, ExecutionTimeCondition } from "./time";
+import type { MaxCallsCondition, SequenceCondition, ToolNameCondition, ToolTagCondition } from "./tools";
+export type AndCondition = {
+    kind: "and";
+    all: RuleConditionV2[];
+};
+export type OrCondition = {
+    kind: "or";
+    any: RuleConditionV2[];
+};
+export type NotCondition = {
+    kind: "not";
+    not: RuleConditionV2;
+};
+export type RuleConditionV2 = ToolNameCondition | ToolTagCondition | EndUserTagCondition | ExecutionTimeCondition | SequenceCondition | MaxCallsCondition | CustomFunctionCondition | MetricWindowCondition | TimeGateCondition | RequireSubjectCondition | SignalCondition | AndCondition | OrCondition | NotCondition;

package/dist/rules/v2/custom.d.ts

@@ -0,0 +1,11 @@
+import type { JSONValue } from "./common";
+/**
+ * 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;
+};

package/dist/rules/v2/effects.d.ts

@@ -0,0 +1,18 @@
+export type RuleEffectKind = "allow" | "hitl" | "block";
+/**
+ * Direct impact of a rule breach.
+ *
+ * RuleEffect has an immediate impact on the agent run/tool action.
+ * This is in contract to side effects (yet to be defined),
+ * which would include "log" or "modify context".
+ */
+export type RuleEffectV2 = {
+    type: "allow";
+    reason?: string;
+} | {
+    type: "hitl";
+    reason?: string;
+} | {
+    type: "block";
+    reason?: string;
+};

package/dist/rules/v2/enduser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Match on arbitrary tags assigned to the enduser.
+ * "enduser" in this context means the users of a Handlebar user.
+ * - has: existence AND truthiness of the tag. E.g. "has:tier" would be false if "tier=0", "tier=false", or no "tier" tag exists.
+ * - hasValue: tag exists and has an exact given value
+ */
+export type EndUserTagCondition = {
+    kind: "enduserTag";
+    op: "has";
+    tag: string;
+} | {
+    kind: "enduserTag";
+    op: "hasValue";
+    tag: string;
+    value: string;
+} | {
+    kind: "enduserTag";
+    op: "hasValueAny";
+    tag: string;
+    values: string[];
+};

package/dist/rules/v2/index.d.ts

@@ -0,0 +1,10 @@
+export type { RuleConditionV2 } from "./condition";
+export type { RulePhase, RuleSelector, RuleV2 } from "./rule";
+export type { RuleEffectV2, RuleEffectKind } from "./effects";
+export type { RequireSubjectCondition, SignalCondition } from "./signals";
+export type { TimeGateCondition, ExecutionTimeCondition, ExecutionTimeScope } from "./time";
+export type { MetricWindowCondition } from "./metrics";
+export type { CustomFunctionCondition } from "./custom";
+export type { EndUserTagCondition } from "./enduser";
+export type { MaxCallsCondition, MaxCallsSelector, SequenceCondition, ToolNameCondition, ToolTagCondition } from "./tools";
+export type { Glob, JSONValue } from "./common";

package/dist/rules/v2/logical_conditions.d.ts

@@ -0,0 +1,13 @@
+import type { RuleConditionV2 } from "./condition";
+export type AndCondition = {
+    kind: "and";
+    all: RuleConditionV2[];
+};
+export type OrCondition = {
+    kind: "or";
+    any: RuleConditionV2[];
+};
+export type NotCondition = {
+    kind: "not";
+    not: RuleConditionV2;
+};

package/dist/rules/v2/metrics.d.ts

@@ -0,0 +1,24 @@
+import type { Glob } from "./common";
+import type { RuleEffectKind } from "./effects";
+type MetricRef = {
+    kind: "inbuilt";
+    key: "bytes_in" | "bytes_out" | "records_in" | "records_out" | "duration_ms";
+} | {
+    kind: "custom";
+    key: string;
+};
+export type MetricWindowCondition = {
+    kind: "metricWindow";
+    scope: "agent" | "agent_user";
+    metric: MetricRef;
+    aggregate: "sum" | "avg" | "max" | "min" | "count";
+    windowSeconds: number;
+    filter?: {
+        toolName?: Glob | Glob[];
+        toolTag?: string | string[];
+    };
+    op: "gt" | "gte" | "lt" | "lte" | "eq" | "neq";
+    value: number;
+    onMissing?: RuleEffectKind;
+};
+export {};

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

@@ -0,0 +1,23 @@
+import type { Glob } from "./common";
+import type { RuleConditionV2 } from "./condition";
+import type { RuleEffectKind, RuleEffectV2 } from "./effects";
+export type RulePhase = "tool.before" | "tool.after";
+export type RuleSelector = {
+    phase: RulePhase;
+    tool?: {
+        name?: Glob | Glob[];
+        tagsAll?: string[];
+        tagsAny?: string[];
+    };
+};
+export type RuleV2 = {
+    id: string;
+    policyId: string;
+    enabled: boolean;
+    priority: number;
+    name: string;
+    selector: RuleSelector;
+    condition: RuleConditionV2;
+    effect: RuleEffectV2;
+    onMissing?: RuleEffectKind;
+};

package/dist/rules/v2/signals.d.ts

@@ -0,0 +1,44 @@
+import type { JSONValue } from "./common";
+import type { RuleEffectKind } from "./effects";
+/**
+ * Requires the existence of subject data at runtime.
+ *
+ * Handlebar is agnostic to the source of the data,
+ * so long as it is present in the engine runtime.
+ */
+export type RequireSubjectCondition = {
+    kind: "requireSubject";
+    subjectType: string;
+    idSystem?: string;
+};
+type SignalBinding = {
+    from: "endUserId";
+} | {
+    from: "endUserTag";
+    tag: string;
+} | {
+    from: "toolName";
+} | {
+    from: "toolTag";
+    tag: string;
+} | {
+    from: "toolArg";
+    path: string;
+} | {
+    from: "subject";
+    subjectType: string;
+    role?: string;
+    field?: "id" | "idSystem";
+} | {
+    from: "const";
+    value: JSONValue;
+};
+export type SignalCondition = {
+    kind: "signal";
+    key: string;
+    args: Record<string, SignalBinding>;
+    op: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "nin";
+    value: JSONValue;
+    onMissing?: RuleEffectKind;
+};
+export {};

package/dist/rules/v2/time.d.ts

@@ -0,0 +1,28 @@
+export type TimeGateCondition = {
+    kind: "timeGate";
+    timezone: {
+        source: "endUserTag";
+        tag: string;
+        fallback?: "org";
+    };
+    windows: Array<{
+        days: ("mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun")[];
+        start: string;
+        end: 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;
+};

package/dist/rules/v2/tools.d.ts

@@ -0,0 +1,64 @@
+import type { Glob } from "./common";
+/**
+ * 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[];
+};
+/**
+* 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;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@handlebar/governance-schema",
-	"version": "0.0.6-dev.4",
+	"version": "0.0.6-dev.6",
 	"private": false,
 	"type": "module",
 	"main": "./dist/index.cjs",