@animalabs/agent-framework 0.4.1 → 0.5.0

package/dist/src/gate/types.d.ts

@@ -5,9 +5,50 @@
  * against declarative policies to decide whether they should trigger inference.
  * Policies are read from a `gate.json` file with hot-reload support.
  */
+/**
+ * Token-bucket configuration for the `rate_limit` behavior.
+ *
+ * Each matching event consumes one token; events that arrive with an empty
+ * bucket are denied (decision: trigger=false). Tokens regenerate at one per
+ * `refillIntervalMs`, capped at `tokens`. Buckets are partitioned by the
+ * value of `keyBy` resolved against event metadata — so a per-user limit
+ * uses `keyBy: "senderId"`, a per-channel limit uses `keyBy: "channelId"`,
+ * etc. With no `keyBy` (or when the resolved value is missing), one shared
+ * bucket is used for the policy.
+ */
+export interface RateLimitConfig {
+    /** Max bucket capacity, also the initial fill. Must be > 0. */
+    tokens: number;
+    /** Milliseconds between token regenerations. Must be > 0. */
+    refillIntervalMs: number;
+    /**
+     * Metadata field name to partition buckets by. If absent or the metadata
+     * field is missing on a given event, all events share one bucket.
+     */
+    keyBy?: string;
+}
+/**
+ * Counter configuration for the `passive_sample` behavior.
+ *
+ * Increments a counter on every match. When the counter reaches `every`,
+ * the policy fires (trigger=true) and the counter resets to zero. Useful
+ * for "decide whether to act every Nth observation" — chat passive
+ * sampling, periodic analysis of sensor streams, etc. Counters are
+ * partitioned by `keyBy` the same way `rate_limit` buckets are.
+ */
+export interface PassiveSampleConfig {
+    /** Trigger every N-th match. Must be > 0. */
+    every: number;
+    /** Optional metadata field name for separate per-key counters. */
+    keyBy?: string;
+}
 /** How a matching policy affects inference triggering. */
 export type GateBehavior = 'always' | 'skip' | {
     debounce: number;
+} | {
+    rate_limit: RateLimitConfig;
+} | {
+    passive_sample: PassiveSampleConfig;
 };
 /** Criteria for matching an event. All specified fields must match (AND logic). */
 export interface GatePolicyMatch {
@@ -32,12 +73,26 @@ export interface GatePolicyMatch {
      * Supports `*` wildcard; not full gitignore syntax.
      */
     pathGlob?: string;
+    /**
+     * Match when ANY listed metadata field is truthy (Boolean(metadata[name])).
+     * Useful for OR-ing flag-style metadata, e.g.:
+     *   metadataTrue: ["isMention", "isPrivate", "isReplyToBot"]
+     * matches if any of those is set. Empty/omitted = no metadata constraint.
+     */
+    metadataTrue?: string[];
 }
 /** A single gate policy — one rule in the ordered policy list. */
 export interface GatePolicy {
     name: string;
     match: GatePolicyMatch;
     behavior: GateBehavior;
+    /**
+     * Names of other policies whose state to clear when THIS policy fires
+     * (decision.trigger === true). Lets you express interactions like "a
+     * direct invocation should reset the passive-sample counter", without
+     * coupling the behaviors to each other in code. Unknown names are ignored.
+     */
+    resets?: string[];
 }
 /** Top-level gate configuration, stored in gate.json. */
 export interface GateConfig {
@@ -83,6 +138,16 @@ export interface GatePolicyStats {
         pendingCount: number;
         nextDeliveryMs: number | null;
     };
+    /** Present for `rate_limit` behaviors. */
+    rateLimitState?: {
+        bucketCount: number;
+        deniedCount: number;
+    };
+    /** Present for `passive_sample` behaviors. */
+    passiveSampleState?: {
+        counterCount: number;
+        fireCount: number;
+    };
 }
 /** Full gate status returned by gate:status tool. */
 export interface GateStatus {

package/dist/src/gate/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/gate/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/gate/types.ts"],"names":[],"mappings":"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"}

package/dist/test/event-gate-rate-limit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=event-gate-rate-limit.test.d.ts.map

package/dist/test/event-gate-rate-limit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-gate-rate-limit.test.d.ts","sourceRoot":"","sources":["../../test/event-gate-rate-limit.test.ts"],"names":[],"mappings":""}