@handlebar/governance-schema 0.1.1-beta.1 → 0.3.0-dev.0

package/README.md

@@ -1,24 +1,94 @@
-# Handlebar Governance Schema
+# Handlebar, Agent Control Layer 
 
-Schemas and types for [Handlebar] rules.
+[Handlebar] is a runtime control layer for your AI agents.
 
-## Getting started
+Enforce deterministic rules on your agents as they act,
+so you can guarantee they don't violate your team's policies.
 
-This package should be used alongside a framework-specific Handlebar SDK,
-such as [ai-sdk-v5](https://github.com/gethandlebar/handlebar-js/blob/main/packages/ai-sdk-v5/).
-Refer to that package's README for more information.
+This package provides the policy and event types that Handlebar manages.
 
-## Contributing
+| Without Handlebar | With Handlebar |
+|:------|:------|
+| "Whoops the agent deleted prod DB" | Deterministically block dangerous tool actions. Full auditability into what your agent _tried_ to do.  |
+| "Our costs are ballooning with no way to control them" | Track token usage and USD spend, and set hard limits on your agents. When the limit is reached, Handlebar can block the agent from taking further actions. |
+| "Someone convinced the agent to leak another user's emails" | Limit tool permissions to the user. |
+| "The agent is going off-the-rails and spamming heavy APIs" | Set rate limits on tool use and prevent runaway actions |
+| "We can't be sure the agent isn't leaking sensitive data" | Enforce hard data boundaries between tools and your output. Filter PII before it leaks through agent context |
 
-We welcome contributions from the community: bug reports, feedback, feature requests
-Please refer to [CONTRIBUTING.md][root_contributing]
-for ways you can help,
-and guidelines.
+## Features
 
-## About Handlebar
+- Collects auditable event logs of your agent's actions
+- Block dangerous tools use (e.g. `send_email(internalAddress) -> PASS | send_email(unknownperson@randomaddress.ru) -> BLOCK`)
+- Block dangerous tool chaining (e.g. `get_pii` -> `send_slack_message -> BLOCK: risk of data exfil`)
+- Require human reviews on dangerous actions
+- Enforce hard cost budgets and token usage limits for your agents
+- Track usage from each enduser and enforce per-user budgets
+- Rate limit agent actions
 
-Find out more at [https://gethandlebar.com][handlebar]
+## How it works
 
-[handlebar]: https://gethandlebar.com
-[root_contributing]: https://github.com/gethandlebar/handlebar-js/blob/main/CONTRIBUTING.md
-[discord_invite]: https://discord.gg/Q6xwvccg
+1. Wrap a Handlebar client (this codebase) around your agent
+1. The client sends event logs of your agent's actions to the [Handlebar platform][platform], where you can analyse them
+1. As your agent receives an action from the LLM, Handlebar intercepts and evaluates the proposed action against your configured policies
+1. If there are violations, Handlebar either permits the action, blocks it, or exits the run
+
+## Get started
+
+You will need:
+
+- an agent...
+- Wrap your agent with a Handlebar client
+- Connect to the [Handlebar platform][platform]
+- Configure policies to enforce on your agent
+
+### Wrap your agent with Handlebar
+
+This repository is a monorepo containing installable packages
+for different JS/TS agent building frameworks. We provide some pre-built wrappers for agent frameworks,
+with more on the way soon. If your agent is not directly supported, you can still easily plug Handlebar into your agent.
+
+| Framework | Install command | Where to read more |
+|:---:|:---:|:---:|
+| Vercel ai **Version 5** | `bun i @handlebar/ai-sdk-v5` | [Vercel AI integration guide](../docs/integrations/vercel-ai-sdk.md) |
+| Vercel ai **Version >=6** | Soon... | |
+| Langchain | Soon... it's still being tested 😕 | See the [langchain integration guide](../docs/integrations/langchain.md) |
+| Openai agents | `bun i @handlebar/core` | See the [OpenAI integration guide](../docs/integrations/openai-agents.md)
+| Other JS/TS, and custom agents | `bun i @handlebar/core` | [`packages/core`](../packages/core) |
+| Python agents | Soon... | |
+
+### Connect your agent to the Handlebar platform
+
+The client SDKs interact with the Handlebar API to emit agent telemetry and event data it collects,
+and to evaluate your configured policies.
+
+Sign up at [`https://app.gethandlebar.com`][platform].\
+If you are waitlisted, [get in touch](#get-in-touch) with us to get access.
+
+Once on the platform, create an API key and activate your agent by setting the `HANDLEBAR_API_KEY` environment variable.
+
+### Configure policies to enforce on your agent
+
+On the [platform] you can create policies from simple templates: usage limits, dangerous tool use, GDPR, finance agents, and more.
+
+Alternatively, run the Handlebar claude code skill to generate rules custom to your agent, by running:
+
+```bash
+npx skills add gethandlebar/agent-skills
+```
+
+Go to the [skill repository](https://github.com/gethandlebar/agent-skills)
+for full instructions.
+
+## Get in touch
+
+Please [open an issue](https://github.com/gethandlebar/handlebar-js/issues/new) if you have any feedback, suggestions, or requests for framework support.
+Alternatively, [book a call][calendar] to talk to us about how Handlebar could help to protect your team's agents.
+
+## License
+
+Apache 2.0 [`LICENSE`](../LICENSE).
+
+[handlebar]: https://www.gethandlebar.com
+[platform]: https://app.gethandlebar.com
+[calendar]: https://calendly.com/arjun-handlebar/30min
+[docs]: https://handlebar.mintlify.app

package/dist/index.js

@@ -13785,12 +13785,7 @@ var RunStartedEventSchema = AuditEnvelopeSchema.extend({
 var RunEndedEventSchema = AuditEnvelopeSchema.extend({
   kind: exports_external.literal("run.ended"),
   data: exports_external.object({
-    status: exports_external.enum([
-      "error",
-      "success",
-      "timeout",
-      "interrupted"
-    ]),
+    status: exports_external.enum(["error", "success", "timeout", "interrupted"]),
     totalSteps: exports_external.number().min(0),
     summary: exports_external.string().optional()
   })
@@ -13886,10 +13881,10 @@ var MetricRefSchema = exports_external.discriminatedUnion("kind", [
 ]);
 var MetricWindowConditionSchema = exports_external.object({
   kind: exports_external.literal("metricWindow"),
-  scope: exports_external.enum(["agent", "agent_user"]),
+  scope: exports_external.enum(["run", "agent", "agent_user"]),
   metric: MetricRefSchema,
   aggregate: exports_external.enum(["sum", "avg", "max", "min", "count"]),
-  windowSeconds: exports_external.number().int().positive(),
+  windowSeconds: exports_external.number().int().positive().optional(),
   filter: exports_external.object({
     toolName: exports_external.union([GlobSchema, exports_external.array(GlobSchema).min(1)]).optional(),
     toolTag: exports_external.union([exports_external.string().min(1), exports_external.array(exports_external.string().min(1)).min(1)]).optional()
@@ -13899,6 +13894,53 @@ var MetricWindowConditionSchema = exports_external.object({
   onMissing: RuleEffectKindSchema.optional()
 }).strict();
 
+// src/rules/sensitive.ts
+var SensitiveDataDetectorSchema = exports_external.enum([
+  "email",
+  "email_domain",
+  "phone",
+  "credit_card",
+  "iban",
+  "uk_nino",
+  "ip_address",
+  "url",
+  "jwt",
+  "private_key",
+  "secret_key"
+]);
+var SubConditionValueSchema = exports_external.union([
+  exports_external.string().min(1),
+  exports_external.array(exports_external.string().min(1)).min(1)
+]);
+var SensitiveDataSubConditionSchema = exports_external.discriminatedUnion("check", [
+  exports_external.object({
+    check: exports_external.literal("domain"),
+    op: exports_external.enum(["eq", "neq", "endsWith", "in"]),
+    value: SubConditionValueSchema
+  }).strict(),
+  exports_external.object({
+    check: exports_external.literal("tld"),
+    op: exports_external.enum(["eq", "neq", "in"]),
+    value: SubConditionValueSchema
+  }).strict(),
+  exports_external.object({
+    check: exports_external.literal("scheme"),
+    op: exports_external.enum(["eq", "neq", "in"]),
+    value: SubConditionValueSchema
+  }).strict()
+]);
+var SensitiveDataDetectorEntrySchema = exports_external.object({
+  detector: SensitiveDataDetectorSchema,
+  subCondition: SensitiveDataSubConditionSchema.optional()
+}).strict();
+var SensitiveDataConditionSchema = exports_external.object({
+  kind: exports_external.literal("sensitiveData"),
+  target: exports_external.literal("toolArg"),
+  path: exports_external.string().min(1).max(200).optional(),
+  op: exports_external.enum(["anyOf", "allOf"]).default("anyOf"),
+  detectors: exports_external.array(SensitiveDataDetectorEntrySchema).min(1)
+}).strict();
+
 // src/rules/signals.ts
 var RequireSubjectConditionSchema = exports_external.object({
   kind: exports_external.literal("requireSubject"),
@@ -13931,13 +13973,20 @@ var SignalConditionSchema = exports_external.object({
 // src/rules/time.ts
 var DaySchema = exports_external.enum(["mon", "tue", "wed", "thu", "fri", "sat", "sun"]);
 var TimeHHMMSchema = exports_external.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, 'Expected time in "HH:MM" 24-hour format');
-var TimeGateConditionSchema = exports_external.object({
-  kind: exports_external.literal("timeGate"),
-  timezone: exports_external.object({
+var TimezoneSchema = exports_external.discriminatedUnion("source", [
+  exports_external.object({
     source: exports_external.literal("enduserTag"),
     tag: exports_external.string().min(1),
     fallback: exports_external.literal("org").optional()
   }).strict(),
+  exports_external.object({
+    source: exports_external.literal("static"),
+    tz: exports_external.string().min(1)
+  }).strict()
+]);
+var TimeGateConditionSchema = exports_external.object({
+  kind: exports_external.literal("timeGate"),
+  timezone: TimezoneSchema,
   windows: exports_external.array(exports_external.object({
     days: exports_external.array(DaySchema).min(1),
     start: TimeHHMMSchema,
@@ -13965,28 +14014,43 @@ var ToolNameConditionSchema = exports_external.discriminatedUnion("op", [
     value: exports_external.array(exports_external.string().min(1)).min(1)
   }).strict()
 ]);
-var ToolArgConditionSchema = exports_external.discriminatedUnion("type", [
-  exports_external.object({
-    kind: exports_external.literal("toolArg"),
-    type: exports_external.literal("string"),
-    op: exports_external.enum(["eq", "neq", "contains", "startsWith", "endsWith", "in"]),
-    path: exports_external.string().min(1).max(100),
-    value: exports_external.string().min(1).max(1000)
-  }),
-  exports_external.object({
-    kind: exports_external.literal("toolArg"),
-    type: exports_external.literal("number"),
-    op: exports_external.enum(["eq", "neq", "lt", "lte", "gt", "gte"]),
-    path: exports_external.string().min(1).max(100),
-    value: exports_external.number()
-  }),
+var ToolArgConditionSchema = exports_external.union([
+  exports_external.discriminatedUnion("type", [
+    exports_external.object({
+      kind: exports_external.literal("toolArg"),
+      type: exports_external.literal("string"),
+      op: exports_external.enum([
+        "eq",
+        "neq",
+        "contains",
+        "startsWith",
+        "endsWith",
+        "in",
+        "regex"
+      ]),
+      path: exports_external.string().min(1).max(100).optional(),
+      value: exports_external.string().min(1).max(1000)
+    }),
+    exports_external.object({
+      kind: exports_external.literal("toolArg"),
+      type: exports_external.literal("number"),
+      op: exports_external.enum(["eq", "neq", "lt", "lte", "gt", "gte"]),
+      path: exports_external.string().min(1).max(100).optional(),
+      value: exports_external.number()
+    }),
+    exports_external.object({
+      kind: exports_external.literal("toolArg"),
+      type: exports_external.literal("boolean"),
+      op: exports_external.literal("eq"),
+      path: exports_external.string().min(1).max(100).optional(),
+      value: exports_external.boolean()
+    })
+  ]),
   exports_external.object({
     kind: exports_external.literal("toolArg"),
-    type: exports_external.literal("boolean"),
-    op: exports_external.literal("eq"),
-    path: exports_external.string().min(1).max(100),
-    value: exports_external.boolean()
-  })
+    op: exports_external.enum(["exists", "notExists"]),
+    path: exports_external.string().min(1).max(100)
+  }).strict()
 ]);
 var ToolTagConditionSchema = exports_external.discriminatedUnion("op", [
   exports_external.object({
@@ -14005,10 +14069,22 @@ var ToolTagConditionSchema = exports_external.discriminatedUnion("op", [
     tags: exports_external.array(exports_external.string().min(1)).min(1)
   }).strict()
 ]);
+var SequenceEntrySchema = exports_external.union([
+  GlobSchema,
+  exports_external.object({
+    by: exports_external.literal("toolName"),
+    patterns: exports_external.array(GlobSchema).min(1)
+  }).strict(),
+  exports_external.object({
+    by: exports_external.literal("toolTag"),
+    tags: exports_external.array(exports_external.string().min(1)).min(1),
+    op: exports_external.enum(["anyOf", "allOf"]).optional()
+  }).strict()
+]);
 var SequenceConditionSchema = exports_external.object({
   kind: exports_external.literal("sequence"),
-  mustHaveCalled: exports_external.array(GlobSchema).min(1).optional(),
-  mustNotHaveCalled: exports_external.array(GlobSchema).min(1).optional()
+  mustHaveCalled: exports_external.array(SequenceEntrySchema).min(1).optional(),
+  mustNotHaveCalled: exports_external.array(SequenceEntrySchema).min(1).optional()
 }).strict().refine((v) => v.mustHaveCalled?.length || v.mustNotHaveCalled?.length, "sequence requires mustHaveCalled and/or mustNotHaveCalled");
 var MaxCallsSelectorSchema = exports_external.discriminatedUnion("by", [
   exports_external.object({ by: exports_external.literal("toolName"), patterns: exports_external.array(GlobSchema).min(1) }).strict(),
@@ -14020,7 +14096,10 @@ var MaxCallsSelectorSchema = exports_external.discriminatedUnion("by", [
 var MaxCallsConditionSchema = exports_external.object({
   kind: exports_external.literal("maxCalls"),
   selector: MaxCallsSelectorSchema,
-  max: exports_external.number().int().nonnegative()
+  max: exports_external.number().int().nonnegative(),
+  windowSeconds: exports_external.number().int().positive().optional(),
+  per: exports_external.enum(["agent", "agent_user"]).optional(),
+  tagFilter: exports_external.array(exports_external.string().min(1)).min(1).optional()
 }).strict();
 
 // src/rules/condition.ts
@@ -14036,17 +14115,19 @@ var BaseRuleConditionSchema = exports_external.union([
   MetricWindowConditionSchema,
   TimeGateConditionSchema,
   RequireSubjectConditionSchema,
-  SignalConditionSchema
+  SignalConditionSchema,
+  SensitiveDataConditionSchema
 ]);
+var LazyRuleConditionSchema = exports_external.lazy(() => RuleConditionSchema);
 var AndConditionSchema = exports_external.object({
   kind: exports_external.literal("and"),
-  all: exports_external.array(BaseRuleConditionSchema).min(1)
+  all: exports_external.array(LazyRuleConditionSchema).min(1)
 }).strict();
 var OrConditionSchema = exports_external.object({
   kind: exports_external.literal("or"),
-  any: exports_external.array(BaseRuleConditionSchema).min(1)
+  any: exports_external.array(LazyRuleConditionSchema).min(1)
 }).strict();
-var NotConditionSchema = exports_external.object({ kind: exports_external.literal("not"), not: BaseRuleConditionSchema }).strict();
+var NotConditionSchema = exports_external.object({ kind: exports_external.literal("not"), not: LazyRuleConditionSchema }).strict();
 var RuleConditionSchema = exports_external.union([
   BaseRuleConditionSchema,
   AndConditionSchema,