@handlebar/governance-schema 0.0.6-dev.5 → 0.0.6-dev.7

package/dist/index.js

@@ -8,7 +8,6 @@ var __export = (target, all) => {
       set: (newValue) => all[name] = () => newValue
     });
 };
-
 // node_modules/zod/v4/classic/external.js
 var exports_external = {};
 __export(exports_external, {
@@ -12574,6 +12573,9 @@ function date4(params) {
 
 // node_modules/zod/v4/classic/external.js
 config(en_default());
+// node_modules/zod/index.js
+var zod_default = exports_external;
+
 // src/enduser.types.ts
 var EndUserConfigSchema = exports_external.object({
   externalId: exports_external.string(),
@@ -12597,11 +12599,7 @@ var AuditEnvelopeSchema = exports_external.object({
   runId: exports_external.string(),
   stepIndex: exports_external.number().min(0).optional(),
   decisionId: exports_external.string().optional(),
-  user: exports_external.object({
-    userId: exports_external.string().optional(),
-    userCategory: exports_external.string().optional(),
-    sessionId: exports_external.string().optional()
-  }).optional(),
+  enduserExternalId: exports_external.string().optional(),
   otel: exports_external.object({
     traceId: exports_external.string().optional(),
     spanId: exports_external.string().optional()
@@ -12649,6 +12647,14 @@ var MessageEventSchema = AuditEnvelopeSchema.extend({
 });
 
 // src/audit/governance-actions.ts
+var SignalSchema = exports_external.object({
+  key: exports_external.string().max(256),
+  args: exports_external.array(exports_external.string().max(256)).max(100).optional(),
+  result: exports_external.union([
+    exports_external.object({ ok: exports_external.literal(false), error: exports_external.string().optional() }),
+    exports_external.object({ ok: exports_external.literal(true), value: exports_external.string().max(256) })
+  ])
+});
 var AppliedActionSchema = exports_external.object({
   type: exports_external.custom(),
   ruleId: exports_external.string()
@@ -12658,7 +12664,8 @@ var GovernanceDecisionSchema = exports_external.object({
   code: exports_external.custom(),
   matchedRuleIds: exports_external.array(exports_external.string()),
   appliedActions: exports_external.array(AppliedActionSchema),
-  reason: exports_external.optional(exports_external.string())
+  reason: exports_external.optional(exports_external.string()),
+  signals: exports_external.array(SignalSchema).max(100).optional()
 });
 
 // src/audit/run-metrics.ts
@@ -12675,13 +12682,61 @@ var AgentMetrics = exports_external.object({
   custom: CustomAgentMetrics
 });
 
-// src/audit/events.ts
-var CountersSchema = exports_external.record(exports_external.string(), exports_external.union([exports_external.string(), exports_external.number()]));
-var ToolMetaSchema = exports_external.object({
-  redacted: exports_external.boolean(),
-  redactedFields: exports_external.array(exports_external.string()).optional(),
-  sizeBytesApprox: exports_external.number().min(0).optional()
+// src/audit/events.tools.ts
+var CountersSchema = zod_default.record(zod_default.string(), zod_default.union([zod_default.string(), zod_default.number()]));
+var ToolMetaSchema = zod_default.object({
+  redacted: zod_default.boolean(),
+  redactedFields: zod_default.array(zod_default.string()).optional(),
+  sizeBytesApprox: zod_default.number().min(0).optional()
+});
+var ToolIdentitySchema = zod_default.object({
+  name: zod_default.string(),
+  categories: zod_default.array(zod_default.string()).optional()
+});
+var ToolArgsSchema = zod_default.record(zod_default.string(), zod_default.unknown());
+var SubjectSchema = zod_default.object({
+  subjectType: zod_default.string().max(256),
+  role: zod_default.string().max(256).optional(),
+  value: zod_default.string().max(256),
+  idSystem: zod_default.string().max(256).optional()
+});
+var HitlMetaSchema = zod_default.object({
+  hitlActionId: zod_default.string().optional(),
+  fingerprint: zod_default.string().optional(),
+  status: zod_default.enum(["none", "pending", "approved", "denied"]).optional()
+});
+var ToolDecisionEventSchema = AuditEnvelopeSchema.extend({
+  kind: zod_default.literal("tool.decision"),
+  data: GovernanceDecisionSchema.extend({
+    tool: ToolIdentitySchema,
+    args: ToolArgsSchema.optional(),
+    argsMeta: ToolMetaSchema.optional(),
+    hitl: HitlMetaSchema.optional(),
+    subjects: zod_default.array(SubjectSchema).max(100).optional(),
+    signals: zod_default.array(SignalSchema).max(100).optional(),
+    counters: CountersSchema.optional(),
+    latencyMs: zod_default.number().min(0).optional()
+  })
+});
+var ToolResultEventSchema = AuditEnvelopeSchema.extend({
+  kind: zod_default.literal("tool.result"),
+  data: zod_default.object({
+    tool: ToolIdentitySchema,
+    hitl: HitlMetaSchema.optional(),
+    outcome: zod_default.enum(["success", "error"]),
+    durationMs: zod_default.number().min(0).optional(),
+    counters: CountersSchema.optional(),
+    metrics: AgentMetrics.optional(),
+    error: zod_default.object({
+      name: zod_default.string().optional(),
+      message: zod_default.string().optional(),
+      stack: zod_default.string().optional()
+    }).optional(),
+    resultMeta: ToolMetaSchema.optional()
+  })
 });
+
+// src/audit/events.ts
 var RunStartedEventSchema = AuditEnvelopeSchema.extend({
   kind: exports_external.literal("run.started"),
   data: exports_external.object({
@@ -12714,44 +12769,6 @@ var RunStartedEventSchema = AuditEnvelopeSchema.extend({
     }).optional()
   })
 });
-var ToolIdentitySchema = exports_external.object({
-  name: exports_external.string(),
-  categories: exports_external.array(exports_external.string()).optional()
-});
-var ToolArgsSchema = exports_external.record(exports_external.string(), exports_external.unknown());
-var HitlMetaSchema = exports_external.object({
-  hitlActionId: exports_external.string().optional(),
-  fingerprint: exports_external.string().optional(),
-  status: exports_external.enum(["none", "pending", "approved", "denied"]).optional()
-});
-var ToolDecisionEventSchema = AuditEnvelopeSchema.extend({
-  kind: exports_external.literal("tool.decision"),
-  data: GovernanceDecisionSchema.extend({
-    tool: ToolIdentitySchema,
-    args: ToolArgsSchema.optional(),
-    argsMeta: ToolMetaSchema.optional(),
-    hitl: HitlMetaSchema.optional(),
-    counters: CountersSchema.optional(),
-    latencyMs: exports_external.number().min(0).optional()
-  })
-});
-var ToolResultEventSchema = AuditEnvelopeSchema.extend({
-  kind: exports_external.literal("tool.result"),
-  data: exports_external.object({
-    tool: ToolIdentitySchema,
-    hitl: HitlMetaSchema.optional(),
-    outcome: exports_external.enum(["success", "error"]),
-    durationMs: exports_external.number().min(0).optional(),
-    counters: CountersSchema.optional(),
-    metrics: AgentMetrics.optional(),
-    error: exports_external.object({
-      name: exports_external.string().optional(),
-      message: exports_external.string().optional(),
-      stack: exports_external.string().optional()
-    }).optional(),
-    resultMeta: ToolMetaSchema.optional()
-  })
-});
 var RunEndedEventSchema = AuditEnvelopeSchema.extend({
   kind: exports_external.literal("run.ended"),
   data: exports_external.object({
@@ -12778,24 +12795,13 @@ 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,
+  SubjectSchema,
+  SignalSchema,
   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, SignalBinding } 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,26 @@
+import type { z } from "zod";
+import type { InbuiltAgentMetricKind } from "../audit/run-metrics";
+import type { Glob } from "./common";
+import type { RuleEffectKind } from "./effects";
+type MetricRef = {
+    kind: "inbuilt";
+    key: z.infer<typeof InbuiltAgentMetricKind>;
+} | {
+    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,43 @@
+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;
+};
+export 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;
+};

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;
+};