@animalabs/agent-framework 0.5.7 → 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;
@@ -363,6 +377,8 @@ export class EventGate {
     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;
@@ -417,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,
+    );
   }
 
   // =========================================================================
@@ -466,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;
     });
   }
@@ -534,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
   // =========================================================================
@@ -604,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;
   }
 
@@ -643,7 +779,12 @@ export class EventGate {
       // Privileged author — fall through to normal policy evaluation.
     }
 
-    const policy = this.matchPolicy(info);
+    // 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++;
@@ -696,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') {
@@ -854,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;
     };
@@ -1124,6 +1267,7 @@ export class EventGate {
       configSource: this.configSource,
       lastReloadTimestamp: this.lastReloadTimestamp,
       default: this.config.default ?? 'always',
+      script: this.gateScript.status(),
       policies,
       errors: [...this.configErrors],
       totalEvaluations: this.totalEvaluations,
@@ -1140,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) });
+    }
+  })();
+});

package/src/gate/gate-script.ts

@@ -0,0 +1,180 @@
+/**
+ * GateScript — runs an agent-authored `gate.js` decision function on a worker
+ * thread, synchronously from the gate's perspective, with a hard timeout.
+ *
+ * The agent is trusted (shell + fs already), so this is a robustness seatbelt,
+ * not a security sandbox: a script that throws falls through to the declarative
+ * policies (and the error is surfaced via status()); a script that hangs is
+ * timed out (Atomics.wait), the wedged worker is terminated and respawned, and
+ * the event falls through — so a bad rule can't brick the agent's own attention.
+ *
+ * Sync model: the main thread posts the event then blocks in Atomics.wait until
+ * the worker writes the result into shared memory (or the timeout elapses).
+ * Node permits Atomics.wait on the main thread, so evaluate() stays synchronous
+ * and the rest of the EventGate is unchanged.
+ */
+import { Worker } from 'node:worker_threads';
+import { existsSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import type { GateBehavior, GateEventInfo } from './types.js';
+
+const WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), 'gate-script-worker.js');
+const SAB_SIZE = 16_384;
+const RELOAD_THROTTLE_MS = 1000;
+
+export interface GateScriptStatus {
+  active: boolean;
+  ready: boolean;
+  path: string;
+  runs: number;
+  errors: number;
+  timeouts: number;
+  lastError: string | null;
+}
+
+interface ScriptResult {
+  behavior?: GateBehavior | null;
+  error?: string;
+}
+
+export class GateScript {
+  private worker?: Worker;
+  private readonly sab = new SharedArrayBuffer(SAB_SIZE);
+  private readonly ctrl = new Int32Array(this.sab, 0, 2);
+  private readonly data = new Uint8Array(this.sab, 8);
+  private readonly dec = new TextDecoder();
+  private mtime = 0;
+  private lastCheck = 0;
+  private active = false;
+  private ready = false;
+  private lastError: string | null = null;
+  private runs = 0;
+  private errors = 0;
+  private timeouts = 0;
+
+  constructor(
+    private readonly scriptPath: string,
+    private readonly timeoutMs = 50,
+    private readonly now: () => number = Date.now,
+  ) {
+    this.reloadIfChanged();
+  }
+
+  /** Hot-reload: (re)spawn the worker when gate.js appears or changes; stop it
+   *  when the file is removed. Throttled like the gate's config reload. */
+  private reloadIfChanged(): void {
+    const t = this.now();
+    if (this.lastCheck !== 0 && t - this.lastCheck < RELOAD_THROTTLE_MS) return;
+    this.lastCheck = t;
+    if (!existsSync(this.scriptPath)) {
+      if (this.active) this.stop();
+      return;
+    }
+    let m = 0;
+    try {
+      m = statSync(this.scriptPath).mtimeMs;
+    } catch {
+      return;
+    }
+    if (this.active && m === this.mtime) return;
+    this.mtime = m;
+    this.spawn();
+  }
+
+  private spawn(): void {
+    this.stop();
+    try {
+      const w = new Worker(WORKER_PATH, {
+        workerData: { scriptPath: this.scriptPath, sab: this.sab },
+      });
+      w.on('message', (m: { type?: string; error?: string | null }) => {
+        if (m?.type === 'ready') {
+          this.ready = true; // load finished (with or without a load error)
+          if (m.error) this.lastError = m.error;
+        }
+      });
+      w.on('error', (e) => {
+        this.lastError = e.message;
+      });
+      w.unref(); // never keep the process alive on the gate script's account
+      this.worker = w;
+      this.active = true;
+      this.lastError = null;
+    } catch (e) {
+      this.lastError = (e as Error).message;
+      this.active = false;
+    }
+  }
+
+  private stop(): void {
+    if (this.worker) {
+      void this.worker.terminate().catch(() => {});
+      this.worker = undefined;
+    }
+    this.active = false;
+    this.ready = false;
+  }
+
+  /**
+   * Evaluate the script for one event.
+   *  - returns a GateBehavior → the script decided
+   *  - returns null → fall through to the declarative policies
+   *  - returns undefined → script inactive / errored / timed out (fall through)
+   */
+  evaluate(event: GateEventInfo): GateBehavior | null | undefined {
+    this.reloadIfChanged();
+    // Inactive, or the worker hasn't finished importing gate.js yet → fall
+    // through (don't time-out/respawn during a cold start).
+    if (!this.active || !this.worker || !this.ready) return undefined;
+
+    Atomics.store(this.ctrl, 0, 0);
+    try {
+      this.worker.postMessage({ type: 'eval', event });
+    } catch (e) {
+      this.lastError = (e as Error).message;
+      return undefined;
+    }
+
+    const r = Atomics.wait(this.ctrl, 0, 0, this.timeoutMs);
+    this.runs++;
+    if (r === 'timed-out') {
+      this.timeouts++;
+      this.lastError = `gate.js timed out (>${this.timeoutMs}ms) — terminated and restarted`;
+      this.spawn(); // kill the wedged worker, fresh one for next time
+      return undefined;
+    }
+
+    const len = Atomics.load(this.ctrl, 1);
+    let parsed: ScriptResult;
+    try {
+      parsed = JSON.parse(this.dec.decode(this.data.subarray(0, len))) as ScriptResult;
+    } catch {
+      this.errors++;
+      this.lastError = 'gate.js produced an unreadable result';
+      return undefined;
+    }
+    if (parsed.error) {
+      this.errors++;
+      this.lastError = parsed.error;
+      return undefined;
+    }
+    return parsed.behavior ?? null;
+  }
+
+  status(): GateScriptStatus {
+    return {
+      active: this.active,
+      ready: this.ready,
+      path: this.scriptPath,
+      runs: this.runs,
+      errors: this.errors,
+      timeouts: this.timeouts,
+      lastError: this.lastError,
+    };
+  }
+
+  dispose(): void {
+    this.stop();
+  }
+}

package/src/gate/types.ts

@@ -52,7 +52,8 @@ export interface PassiveSampleConfig {
 /** How a matching policy affects inference triggering. */
 export type GateBehavior =
   | 'always'    // Trigger inference immediately
-  | 'skip'      // Don't trigger inference (event still enters context)
+  | 'defer'     // Don't trigger inference (event still enters context). Preferred name.
+  | 'skip'      // Legacy alias for 'defer' (still accepted).
   | { debounce: number }                  // Batch events per-policy, deliver after delay (ms)
   | { rate_limit: RateLimitConfig }       // Token bucket per `keyBy`; deny when empty
   | { passive_sample: PassiveSampleConfig };  // Fire every Nth match
@@ -88,6 +89,17 @@ export interface GatePolicyMatch {
    * matches if any of those is set. Empty/omitted = no metadata constraint.
    */
   metadataTrue?: string[];
+  /**
+   * Tag matching (MCPL RFC-001 event tags). Globs allowed (e.g. `robotics:*`).
+   * Evaluated against the event's (implication-expanded) tag set:
+   *   tagsAny  — match if ANY listed pattern matches an event tag
+   *   tagsAll  — match only if EVERY listed pattern matches some event tag
+   *   tagsNone — match only if NO listed pattern matches any event tag
+   * Combined with the other fields by AND, like the rest of the match.
+   */
+  tagsAny?: string[];
+  tagsAll?: string[];
+  tagsNone?: string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -116,7 +128,7 @@ export interface GatePolicy {
 export interface GateConfig {
   policies: GatePolicy[];
   /** Behavior when no policy matches. Default: 'always'. */
-  default?: 'always' | 'skip';
+  default?: 'always' | 'defer' | 'skip';
 }
 
 // ---------------------------------------------------------------------------
@@ -163,6 +175,8 @@ export interface GateEventInfo {
   mount?: string;
   /** Mount-prefixed paths touched (for workspace:* events). */
   paths?: string[];
+  /** Event tags (MCPL RFC-001), already implication-expanded by the host. */
+  tags?: string[];
 }
 
 /** Per-policy runtime statistics (for gate:status). */
@@ -192,7 +206,9 @@ export interface GateStatus {
   configPath: string;
   configSource: 'file' | 'initial' | 'default';
   lastReloadTimestamp: number | null;
-  default: 'always' | 'skip';
+  default: 'always' | 'defer' | 'skip';
+  /** Status of the optional programmable gate (gate.js). */
+  script: import('./gate-script.js').GateScriptStatus;
   policies: GatePolicyStats[];
   errors: string[];
   /** Total events the gate has evaluated since startup. */