@animalabs/agent-framework 0.5.6 → 0.6.0

package/src/gate/event-gate.ts

@@ -12,7 +12,8 @@
  */
 
 import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
+import { GateScript } from './gate-script.js';
 
 import type { ToolDefinition } from '../types/events.js';
 import type {
@@ -89,6 +90,9 @@ interface CompiledPolicy {
   channelRegex?: RegExp;
   mountRegex?: RegExp;
   pathRegex?: RegExp;
+  tagsAnyRe?: RegExp[];
+  tagsAllRe?: RegExp[];
+  tagsNoneRe?: RegExp[];
 }
 
 interface PolicyStats {
@@ -170,8 +174,8 @@ function validateConfig(raw: unknown): GateConfig {
   const obj = raw as Record<string, unknown>;
 
   const defaultBehavior = obj.default ?? 'always';
-  if (defaultBehavior !== 'always' && defaultBehavior !== 'skip') {
-    throw new Error(`gate.json "default" must be "always" or "skip", got: ${defaultBehavior}`);
+  if (defaultBehavior !== 'always' && defaultBehavior !== 'defer' && defaultBehavior !== 'skip') {
+    throw new Error(`gate.json "default" must be "always", "defer", or "skip", got: ${defaultBehavior}`);
   }
 
   const policies: GatePolicy[] = [];
@@ -197,7 +201,7 @@ function validatePolicy(raw: unknown): GatePolicy {
 
   // Validate behavior
   let behavior: GateBehavior;
-  if (obj.behavior === 'always' || obj.behavior === 'skip') {
+  if (obj.behavior === 'always' || obj.behavior === 'defer' || obj.behavior === 'skip') {
     behavior = obj.behavior;
   } else if (obj.behavior && typeof obj.behavior === 'object') {
     const b = obj.behavior as Record<string, unknown>;
@@ -247,7 +251,7 @@ function validatePolicy(raw: unknown): GatePolicy {
       }
       behavior = { passive_sample: out };
     } else {
-      throw new Error(`Policy "${obj.name}": unknown behavior — expected always | skip | { debounce } | { rate_limit } | { passive_sample }`);
+      throw new Error(`Policy "${obj.name}": unknown behavior — expected always | defer | skip | { debounce } | { rate_limit } | { passive_sample }`);
     }
   } else {
     behavior = 'always';
@@ -266,6 +270,14 @@ function validatePolicy(raw: unknown): GatePolicy {
       const fields = m.metadataTrue.filter((s): s is string => typeof s === 'string' && s.length > 0);
       if (fields.length > 0) match.metadataTrue = fields;
     }
+    const tagList = (v: unknown): string[] | undefined => {
+      if (!Array.isArray(v)) return undefined;
+      const out = v.filter((s): s is string => typeof s === 'string' && s.length > 0);
+      return out.length > 0 ? out : undefined;
+    };
+    const tagsAny = tagList(m.tagsAny); if (tagsAny) match.tagsAny = tagsAny;
+    const tagsAll = tagList(m.tagsAll); if (tagsAll) match.tagsAll = tagsAll;
+    const tagsNone = tagList(m.tagsNone); if (tagsNone) match.tagsNone = tagsNone;
     if (m.filter && typeof m.filter === 'object') {
       const f = m.filter as Record<string, unknown>;
       if ((f.type === 'text' || f.type === 'regex') && typeof f.pattern === 'string') {
@@ -299,6 +311,8 @@ function validatePolicy(raw: unknown): GatePolicy {
 export class EventGate {
   private configPath: string;
   private config: GateConfig;
+  /** Optional agent-authored programmable gate (gate.js). */
+  private gateScript: GateScript;
   private compiledPolicies: CompiledPolicy[] = [];
   private configMtime: number = 0;
   private lastReloadCheck: number = 0;
@@ -330,6 +344,20 @@ export class EventGate {
   private defaultSkipped = 0;
   private defaultByEventType = new Map<string, { triggered: number; skipped: number }>();
 
+  // Sleep state (set via the `sleep` tool). Passive: evaluate() suppresses
+  // non-privileged wakes while now() < sleepUntil. No timer — after expiry the
+  // next event evaluates normally.
+  private sleepUntil = 0;
+  private sleepNote: string | undefined;
+  private sleepSuppressed = 0;
+
+  // Privileged users who may wake the agent through sleep. Hot-reloaded from
+  // privilegedUsersPath on change.
+  private privilegedUsersPath: string | undefined;
+  private privilegedUserIds = new Set<string>();
+  private privilegedMtime = 0;
+  private lastPrivilegedCheck = 0;
+
   // Dependency-injected callbacks
   private emitTrace: (event: TraceEventLike) => void;
   private addMessageFn: (participant: string, content: Array<{ type: 'text'; text: string }>, metadata?: Record<string, unknown>) => unknown;
@@ -342,19 +370,24 @@ export class EventGate {
   constructor(opts: {
     configPath: string;
     initialConfig?: GateConfig;
+    privilegedUsersPath?: string;
     emitTrace: (event: TraceEventLike) => void;
     addMessage: (participant: string, content: Array<{ type: 'text'; text: string }>, metadata?: Record<string, unknown>) => unknown;
     requestInference: (agentName: string, reason: string, source: string) => void;
     getAgentNames: () => string[];
     /** Optional clock — defaults to Date.now. Tests inject for deterministic time. */
     now?: () => number;
+    /** Per-event timeout (ms) for the optional gate.js script. Default 50. */
+    scriptTimeoutMs?: number;
   }) {
     this.configPath = opts.configPath;
+    this.privilegedUsersPath = opts.privilegedUsersPath;
     this.emitTrace = opts.emitTrace;
     this.addMessageFn = opts.addMessage;
     this.requestInferenceFn = opts.requestInference;
     this.getAgentNamesFn = opts.getAgentNames;
     this.now = opts.now ?? (() => Date.now());
+    this.loadPrivileged();
 
     // Seed or reconcile the on-disk config.
     //
@@ -400,6 +433,14 @@ export class EventGate {
     // Load config
     this.config = this.loadConfig() ?? opts.initialConfig ?? { ...DEFAULT_CONFIG };
     this.compiledPolicies = this.compilePolicies(this.config);
+
+    // Programmable gate: an optional agent-authored `gate.js` next to gate.json.
+    // Absent ⇒ inactive (zero overhead beyond a throttled stat check).
+    this.gateScript = new GateScript(
+      join(dirname(this.configPath), 'gate.js'),
+      opts.scriptTimeoutMs ?? 50,
+      this.now,
+    );
   }
 
   // =========================================================================
@@ -449,6 +490,9 @@ export class EventGate {
       if (policy.match.pathGlob) {
         compiled.pathRegex = compileGlob(policy.match.pathGlob);
       }
+      if (policy.match.tagsAny) compiled.tagsAnyRe = policy.match.tagsAny.map(compileGlob);
+      if (policy.match.tagsAll) compiled.tagsAllRe = policy.match.tagsAll.map(compileGlob);
+      if (policy.match.tagsNone) compiled.tagsNoneRe = policy.match.tagsNone.map(compileGlob);
       return compiled;
     });
   }
@@ -517,6 +561,105 @@ export class EventGate {
     }
   }
 
+  // =========================================================================
+  // Runtime policy mutation (backs wake_add_rule / wake_remove_rule)
+  // =========================================================================
+
+  /**
+   * Add or replace (upsert) a single policy in gate.json and apply it live.
+   *
+   * The raw policy is validated with the SAME `validatePolicy` used when loading
+   * gate.json — an invalid shape throws (nothing is written) and the caller
+   * surfaces it as a tool error. On success the policy is persisted to gate.json
+   * (so it survives restart and is visible to `workspace--edit _config/gate.json`)
+   * and the in-memory config is swapped in immediately, so the rule takes effect
+   * without waiting for the throttled mtime reload.
+   *
+   * The freshest on-disk config is re-read first, so a concurrent operator edit
+   * isn't clobbered. A policy with the same `name` is replaced IN PLACE (order
+   * preserved); otherwise it is appended, or prepended when `position:'prepend'`
+   * — first match wins, so a wake rule that must beat a broad defer/debounce
+   * belongs at the front.
+   */
+  addPolicy(rawPolicy: unknown, options?: { position?: 'append' | 'prepend' }): GatePolicy {
+    const policy = validatePolicy(rawPolicy);
+    const current = this.loadConfig() ?? this.config;
+    const policies = [...current.policies];
+    const idx = policies.findIndex((p) => p.name === policy.name);
+    if (idx >= 0) {
+      policies[idx] = policy;
+    } else if (options?.position === 'prepend') {
+      policies.unshift(policy);
+    } else {
+      policies.push(policy);
+    }
+    this.writeConfig({ ...current, policies });
+    this.emitTrace({
+      type: 'gate:policy-added',
+      configPath: this.configPath,
+      policyName: policy.name,
+      replaced: idx >= 0,
+      timestamp: Date.now(),
+    });
+    return policy;
+  }
+
+  /**
+   * Remove a policy by name from gate.json and clear its live state. Any pending
+   * debounce batch is delivered first (matching reloadIfChanged's removal path,
+   * so buffered events aren't silently dropped). Returns false if no policy of
+   * that name exists (nothing written). Freshest on-disk config is re-read first
+   * (see addPolicy).
+   */
+  removePolicy(name: string): boolean {
+    const current = this.loadConfig() ?? this.config;
+    if (!current.policies.some((p) => p.name === name)) {
+      return false;
+    }
+    // Deliver any pending debounce batch, then drop timers/buckets/counters.
+    this.clearPolicyState(name, { deliverPendingDebounce: true });
+    this.stats.delete(name);
+    const policies = current.policies.filter((p) => p.name !== name);
+    this.writeConfig({ ...current, policies });
+    this.emitTrace({
+      type: 'gate:policy-removed',
+      configPath: this.configPath,
+      policyName: name,
+      timestamp: Date.now(),
+    });
+    return true;
+  }
+
+  /**
+   * List the current policy names (freshest on-disk view). Cheap helper for
+   * tools/UX that want to show what's active without the full status payload.
+   */
+  listPolicyNames(): string[] {
+    const current = this.loadConfig() ?? this.config;
+    return current.policies.map((p) => p.name);
+  }
+
+  /**
+   * Persist a config to gate.json and apply it in memory together: write the
+   * file, swap in the compiled policies, and sync `configMtime` to the new file
+   * so `reloadIfChanged` doesn't redundantly re-parse identical content. Throws
+   * if the write fails (disk/permission) — callers surface it as a tool error.
+   */
+  private writeConfig(config: GateConfig): void {
+    mkdirSync(dirname(this.configPath), { recursive: true });
+    writeFileSync(this.configPath, JSON.stringify(config, null, 2) + '\n');
+    this.config = config;
+    this.compiledPolicies = this.compilePolicies(config);
+    this.configSource = 'file';
+    this.configErrors = [];
+    this.lastReloadTimestamp = Date.now();
+    try {
+      this.configMtime = statSync(this.configPath).mtimeMs;
+    } catch {
+      // A failed stat only risks one redundant reload; keep the old mtime.
+    }
+  }
+
   // =========================================================================
   // Policy matching — first match wins
   // =========================================================================
@@ -587,6 +730,16 @@ export class EventGate {
       if (!anyTrue) return false;
     }
 
+    // Tag matching (MCPL RFC-001). Patterns are globs; `tags` is the event's
+    // (implication-expanded) tag set. A pattern "matches" if it matches ANY tag.
+    if (compiled.tagsAnyRe || compiled.tagsAllRe || compiled.tagsNoneRe) {
+      const tags = info.tags ?? [];
+      const patternHits = (re: RegExp): boolean => tags.some(t => re.test(t));
+      if (compiled.tagsAnyRe && !compiled.tagsAnyRe.some(patternHits)) return false;
+      if (compiled.tagsAllRe && !compiled.tagsAllRe.every(patternHits)) return false;
+      if (compiled.tagsNoneRe && compiled.tagsNoneRe.some(patternHits)) return false;
+    }
+
     return true;
   }
 
@@ -597,7 +750,41 @@ export class EventGate {
   evaluate(info: GateEventInfo): GateDecision {
     this.reloadIfChanged();
 
-    const policy = this.matchPolicy(info);
+    // Sleep suppression: while asleep, drop EXTERNAL wakes. Two things still
+    // rouse the agent — its own heartbeat (an internal clock, not an outside
+    // interruption: each tick lets the agent reconsider and optionally `wake`)
+    // and a privileged user's ping. The event always enters context regardless
+    // (the gate only governs inference triggering).
+    if (this.sleepUntil > this.now()) {
+      this.reloadPrivilegedIfChanged();
+      const isHeartbeat =
+        info.metadata?.source === 'heartbeat' || info.serverId === 'heartbeat';
+      const authorId = this.extractAuthorId(info.metadata);
+      const privileged = authorId !== null && this.privilegedUserIds.has(authorId);
+      if (!isHeartbeat && !privileged) {
+        this.sleepSuppressed++;
+        this.totalEvaluations++;
+        this.emitTrace({
+          type: 'gate:decision',
+          eventType: info.eventType,
+          serverId: info.serverId || undefined,
+          channelId: info.channelId || undefined,
+          matchedPolicy: 'asleep',
+          trigger: false,
+          behavior: 'skip',
+          timestamp: this.now(),
+        });
+        return { trigger: false, policyName: 'asleep', behavior: 'skip' };
+      }
+      // Privileged author — fall through to normal policy evaluation.
+    }
+
+    // Programmable gate (gate.js) takes precedence when present and returns a
+    // behavior; null/undefined (inactive, error, or a deliberate pass) falls
+    // through to the declarative gate.json policies below.
+    const scripted = this.gateScript.evaluate(info);
+    const policy: GatePolicy | null =
+      scripted != null ? { name: 'gate.js', match: {}, behavior: scripted } : this.matchPolicy(info);
     const decision = this.computeDecision(policy, info);
 
     this.totalEvaluations++;
@@ -650,8 +837,9 @@ export class EventGate {
       timestamp: this.now(),
     });
 
-    if (policy.behavior === 'skip') {
-      return { trigger: false, policyName: policy.name, behavior: 'skip' };
+    if (policy.behavior === 'defer' || policy.behavior === 'skip') {
+      // Report the configured name faithfully ('defer' or legacy 'skip').
+      return { trigger: false, policyName: policy.name, behavior: policy.behavior };
     }
 
     if (policy.behavior === 'always') {
@@ -808,6 +996,7 @@ export class EventGate {
         serverId: (metadata.serverId as string) ?? '',
         channelId: (metadata.channelId as string) ?? '',
         metadata,
+        tags: Array.isArray(metadata.tags) ? (metadata.tags as string[]) : undefined,
       });
       return decision.trigger;
     };
@@ -927,9 +1116,93 @@ export class EventGate {
   // Tool: gate:status
   // =========================================================================
 
+  // =========================================================================
+  // Sleep
+  // =========================================================================
+
+  /** Begin (or extend) a sleep window of `seconds`. Returns the wake time. */
+  setSleep(seconds: number, note?: string): { until: number } {
+    const ms = Math.max(0, Math.floor(seconds * 1000));
+    this.sleepUntil = this.now() + ms;
+    this.sleepNote = note;
+    this.sleepSuppressed = 0;
+    this.reloadPrivilegedIfChanged();
+    this.emitTrace({
+      type: 'gate:decision',
+      eventType: 'sleep:set',
+      matchedPolicy: 'asleep',
+      trigger: false,
+      behavior: 'skip',
+      timestamp: this.now(),
+    });
+    return { until: this.sleepUntil };
+  }
+
+  /** End sleep immediately. Returns true if the agent was asleep. */
+  clearSleep(): boolean {
+    const wasAsleep = this.sleepUntil > this.now();
+    this.sleepUntil = 0;
+    this.sleepNote = undefined;
+    return wasAsleep;
+  }
+
+  /** Current sleep state, or null if awake. */
+  getSleepState(): { until: number; remainingMs: number; note?: string; suppressed: number } | null {
+    const remainingMs = this.sleepUntil - this.now();
+    if (remainingMs <= 0) return null;
+    return { until: this.sleepUntil, remainingMs, note: this.sleepNote, suppressed: this.sleepSuppressed };
+  }
+
+  /** Author id from an event's metadata, across the discord ingest shapes. */
+  private extractAuthorId(metadata?: Record<string, unknown>): string | null {
+    if (!metadata) return null;
+    const author = metadata.author as { id?: unknown } | undefined;
+    if (author && author.id != null) return String(author.id);
+    if (metadata.authorId != null) return String(metadata.authorId);
+    return null;
+  }
+
+  /** Load the privileged-users file (bare array or { userIds: [...] }). */
+  private loadPrivileged(): void {
+    if (!this.privilegedUsersPath) return;
+    try {
+      if (!existsSync(this.privilegedUsersPath)) {
+        this.privilegedUserIds = new Set();
+        this.privilegedMtime = 0;
+        return;
+      }
+      this.privilegedMtime = statSync(this.privilegedUsersPath).mtimeMs;
+      const raw = JSON.parse(readFileSync(this.privilegedUsersPath, 'utf8'));
+      const ids = Array.isArray(raw) ? raw : Array.isArray(raw?.userIds) ? raw.userIds : [];
+      this.privilegedUserIds = new Set(ids.map((x: unknown) => String(x)));
+    } catch (err) {
+      this.configErrors.push(
+        `Failed to load privileged-users file: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  /** Throttled mtime-based reload of the privileged-users file. */
+  private reloadPrivilegedIfChanged(): void {
+    if (!this.privilegedUsersPath) return;
+    const now = this.now();
+    if (now - this.lastPrivilegedCheck < RELOAD_THROTTLE_MS) return;
+    this.lastPrivilegedCheck = now;
+    try {
+      if (!existsSync(this.privilegedUsersPath)) {
+        if (this.privilegedUserIds.size > 0) this.privilegedUserIds = new Set();
+        return;
+      }
+      const mtime = statSync(this.privilegedUsersPath).mtimeMs;
+      if (mtime !== this.privilegedMtime) this.loadPrivileged();
+    } catch {
+      /* leave the last-known set in place on a transient stat/read error */
+    }
+  }
+
   getToolDefinition(): ToolDefinition {
     return {
-      name: 'gate:status',
+      name: 'gate_status',
       description: 'Show the current EventGate configuration, per-policy match counts, debounce state, and any config errors.',
       inputSchema: {
         type: 'object',
@@ -976,11 +1249,25 @@ export class EventGate {
     const byEventType: Record<string, { triggered: number; skipped: number }> = {};
     for (const [k, v] of this.defaultByEventType) byEventType[k] = { ...v };
 
+    const sleepState = this.getSleepState();
+
     return {
+      ...(sleepState
+        ? {
+            sleep: {
+              until: sleepState.until,
+              remainingMs: sleepState.remainingMs,
+              note: sleepState.note,
+              suppressed: sleepState.suppressed,
+              privilegedCount: this.privilegedUserIds.size,
+            },
+          }
+        : {}),
       configPath: this.configPath,
       configSource: this.configSource,
       lastReloadTimestamp: this.lastReloadTimestamp,
       default: this.config.default ?? 'always',
+      script: this.gateScript.status(),
       policies,
       errors: [...this.configErrors],
       totalEvaluations: this.totalEvaluations,
@@ -997,6 +1284,7 @@ export class EventGate {
   // =========================================================================
 
   dispose(): void {
+    this.gateScript.dispose();
     for (const state of this.debounceTimers.values()) {
       clearTimeout(state.timer);
     }

package/src/gate/gate-script-worker.ts

@@ -0,0 +1,73 @@
+/**
+ * Worker that runs the agent-authored `gate.js` decision function.
+ *
+ * The agent is trusted (it already has shell + filesystem), so this is NOT a
+ * security sandbox — it's a *robustness* boundary: running the script on a
+ * separate thread lets the main thread time it out (Atomics.wait) so an
+ * accidental infinite loop degrades to "fall through to declarative policies"
+ * instead of freezing the agent's own event loop.
+ *
+ * Protocol:
+ *   - on startup we import `gate.js` and post `{ type: 'ready', error? }`.
+ *   - per event the parent posts `{ type: 'eval', event }`; we run the script
+ *     and write the JSON result into the shared buffer, flip the control word,
+ *     and notify. The parent is blocked in Atomics.wait until then (or times out).
+ *
+ * `gate.js` shape (ESM): `export default (event) => behavior | null` where
+ * behavior is a GateBehavior ('always' | 'defer' | { debounce } | …) and null
+ * means "let the declarative gate.json policies decide". Sync or async.
+ */
+import { parentPort, workerData } from 'node:worker_threads';
+import { pathToFileURL } from 'node:url';
+
+interface WorkerData {
+  scriptPath: string;
+  sab: SharedArrayBuffer;
+}
+const { scriptPath, sab } = workerData as WorkerData;
+const ctrl = new Int32Array(sab, 0, 2); // [0]=status (0 pending, 1 done), [1]=result byte length
+const data = new Uint8Array(sab, 8);
+const enc = new TextEncoder();
+
+type DecideFn = (event: unknown) => unknown;
+let fn: DecideFn | null = null;
+
+// Load eagerly and announce readiness, so the parent doesn't time out (and
+// pointlessly respawn) while a cold dynamic import is still in flight.
+void (async () => {
+  let error: string | null = null;
+  try {
+    const mod = (await import(pathToFileURL(scriptPath).href)) as Record<string, unknown>;
+    const f = (mod.default ?? mod.decide ?? mod.gate) as unknown;
+    if (typeof f !== 'function') {
+      error = 'gate.js must export a default function: (event) => behavior | null';
+    } else {
+      fn = f as DecideFn;
+    }
+  } catch (e) {
+    error = (e as Error)?.message ?? String(e);
+  }
+  parentPort?.postMessage({ type: 'ready', error });
+})();
+
+function writeResult(obj: unknown): void {
+  const bytes = enc.encode(JSON.stringify(obj));
+  const n = Math.min(bytes.length, data.length);
+  data.set(bytes.subarray(0, n));
+  Atomics.store(ctrl, 1, n);
+  Atomics.store(ctrl, 0, 1);
+  Atomics.notify(ctrl, 0);
+}
+
+parentPort?.on('message', (msg: { type?: string; event?: unknown }) => {
+  if (msg?.type !== 'eval') return;
+  void (async () => {
+    if (!fn) return writeResult({ behavior: null }); // load failed → fall through
+    try {
+      const r = await fn(msg.event); // sync OR async decision functions
+      writeResult({ behavior: r ?? null });
+    } catch (e) {
+      writeResult({ error: (e as Error)?.message ?? String(e) });
+    }
+  })();
+});