@animalabs/agent-framework 0.5.7 → 0.6.2

package/dist/src/gate/event-gate.d.ts

@@ -11,7 +11,7 @@
  * inference tokens, not whether the agent should know about the event.
  */
 import type { ToolDefinition } from '../types/events.js';
-import type { GateConfig, GateDecision, GateEventInfo, GateStatus } from './types.js';
+import type { GateConfig, GatePolicy, GateDecision, GateEventInfo, GateStatus } from './types.js';
 export type { GateConfig, GateOptions, GateDecision, GateEventInfo } from './types.js';
 interface TraceEventLike {
     type: string;
@@ -20,6 +20,8 @@ interface TraceEventLike {
 export declare class EventGate {
     private configPath;
     private config;
+    /** Optional agent-authored programmable gate (gate.js). */
+    private gateScript;
     private compiledPolicies;
     private configMtime;
     private lastReloadCheck;
@@ -41,6 +43,8 @@ export declare class EventGate {
     private sleepUntil;
     private sleepNote;
     private sleepSuppressed;
+    private sleepTimer;
+    private sleepAgent;
     private privilegedUsersPath;
     private privilegedUserIds;
     private privilegedMtime;
@@ -65,10 +69,51 @@ export declare 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;
     });
     private loadConfig;
     private compilePolicies;
     private reloadIfChanged;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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[];
+    /**
+     * 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;
     private matchPolicy;
     private compiledMatches;
     evaluate(info: GateEventInfo): GateDecision;
@@ -101,14 +146,31 @@ export declare class EventGate {
     private deliverEvents;
     onInferenceStarted(agentName: string): void;
     onInferenceEnded(agentName: string): void;
+    /** Live inference-gating snapshot for diagnostics (e.g. a SIGUSR2 dump).
+     *  A non-empty `inferring` with a stale timestamp + growing `bufferedEvents`
+     *  is the signature of the wake-wedge: an agent stuck mid-"inference" so all
+     *  incoming events buffer and never trigger. */
+    inferenceDiagnostics(): {
+        inferring: string[];
+        bufferedEvents: number;
+        sleepUntil: number;
+    };
     /** Called internally when debounce fires during inference. */
     private bufferForInference;
     /** Begin (or extend) a sleep window of `seconds`. Returns the wake time. */
-    setSleep(seconds: number, note?: string): {
+    setSleep(seconds: number, note?: string, agentName?: string): {
         until: number;
     };
     /** End sleep immediately. Returns true if the agent was asleep. */
     clearSleep(): boolean;
+    /**
+     * Self-wake handler: fired by the sleepTimer when a sleep window elapses.
+     * Clears the sleep state and requests an inference so the agent wakes on its
+     * own — this is what makes `sleep(N)` a real "wake me in N seconds" rather
+     * than just a suppression window. No-op if sleep was already cleared (via
+     * `wake`) or re-armed to a later time by a fresh `sleep` call.
+     */
+    private wakeFromSleep;
     /** Current sleep state, or null if awake. */
     getSleepState(): {
         until: number;

package/dist/src/gate/event-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-gate.d.ts","sourceRoot":"","sources":["../../../src/gate/event-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EACV,UAAU,EAIV,YAAY,EACZ,aAAa,EAEb,UAAU,EACX,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAyEvF,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAiMD,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,gBAAgB,CAAwB;IAChD,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,YAAY,CAA6C;IACjE,OAAO,CAAC,mBAAmB,CAAuB;IAClD,OAAO,CAAC,YAAY,CAAgB;IAGpC,OAAO,CAAC,cAAc,CAAoC;IAG1D,OAAO,CAAC,gBAAgB,CAA8C;IAEtE,OAAO,CAAC,qBAAqB,CAA0C;IAEvE,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,kBAAkB,CAA6B;IAGvD,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,eAAe,CAAsB;IAG7C,OAAO,CAAC,KAAK,CAAkC;IAG/C,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,kBAAkB,CAA6D;IAKvF,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,eAAe,CAAK;IAI5B,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,iBAAiB,CAAqB;IAC9C,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,mBAAmB,CAAK;IAGhC,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,YAAY,CAAuH;IAC3I,OAAO,CAAC,kBAAkB,CAA8D;IACxF,OAAO,CAAC,eAAe,CAAiB;IACxC;8DAC0D;IAC1D,OAAO,CAAC,GAAG,CAAe;gBAEd,IAAI,EAAE;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,CAAC,EAAE,UAAU,CAAC;QAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,SAAS,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;QAC3C,UAAU,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;QACjI,gBAAgB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;QAC9E,aAAa,EAAE,MAAM,MAAM,EAAE,CAAC;QAC9B,kFAAkF;QAClF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;KACpB;IA4DD,OAAO,CAAC,UAAU;IAyBlB,OAAO,CAAC,eAAe;IAsBvB,OAAO,CAAC,eAAe;IAoEvB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,eAAe;IAgEvB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY;IA+D3C,OAAO,CAAC,eAAe;IAqDvB,2DAA2D;IAC3D,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,cAAc;IA0CtB,OAAO,CAAC,kBAAkB;IAuB1B;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAQnB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAsBxB;;;OAGG;IACH,uBAAuB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO;IAiB1F,OAAO,CAAC,cAAc;IAuBtB,OAAO,CAAC,YAAY;IA8BpB,OAAO,CAAC,aAAa;IAwBrB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI3C,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAezC,8DAA8D;IAC9D,OAAO,CAAC,kBAAkB;IAiB1B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;IAiB3D,mEAAmE;IACnE,UAAU,IAAI,OAAO;IAOrB,6CAA6C;IAC7C,aAAa,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAMjG,4EAA4E;IAC5E,OAAO,CAAC,eAAe;IAQvB,yEAAyE;IACzE,OAAO,CAAC,cAAc;IAmBtB,iEAAiE;IACjE,OAAO,CAAC,yBAAyB;IAiBjC,iBAAiB,IAAI,cAAc;IAU7B,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAKxF,SAAS,IAAI,UAAU;IAmEvB,OAAO,IAAI,IAAI;CAWhB"}
+{"version":3,"file":"event-gate.d.ts","sourceRoot":"","sources":["../../../src/gate/event-gate.ts"],"names":[],"mappings":"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"}

package/dist/src/gate/event-gate.js

@@ -11,7 +11,8 @@
  * inference tokens, not whether the agent should know about the event.
  */
 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';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -99,8 +100,8 @@ function validateConfig(raw) {
     }
     const obj = raw;
     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 = [];
     if (Array.isArray(obj.policies)) {
@@ -120,7 +121,7 @@ function validatePolicy(raw) {
     }
     // Validate behavior
     let behavior;
-    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') {
@@ -174,7 +175,7 @@ function validatePolicy(raw) {
             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 {
@@ -199,6 +200,21 @@ function validatePolicy(raw) {
             if (fields.length > 0)
                 match.metadataTrue = fields;
         }
+        const tagList = (v) => {
+            if (!Array.isArray(v))
+                return undefined;
+            const out = v.filter((s) => 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;
             if ((f.type === 'text' || f.type === 'regex') && typeof f.pattern === 'string') {
@@ -233,6 +249,8 @@ function validatePolicy(raw) {
 export class EventGate {
     configPath;
     config;
+    /** Optional agent-authored programmable gate (gate.js). */
+    gateScript;
     compiledPolicies = [];
     configMtime = 0;
     lastReloadCheck = 0;
@@ -258,12 +276,16 @@ export class EventGate {
     defaultTriggered = 0;
     defaultSkipped = 0;
     defaultByEventType = new Map();
-    // 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.
+    // Sleep state (set via the `sleep` tool). evaluate() suppresses non-privileged
+    // wakes while now() < sleepUntil. A self-wake timer (sleepTimer) fires an
+    // inference when the window expires, so `sleep(N)` means "wake me in N
+    // seconds" rather than merely lifting suppression and waiting for an external
+    // event.
     sleepUntil = 0;
     sleepNote;
     sleepSuppressed = 0;
+    sleepTimer = null;
+    sleepAgent;
     // Privileged users who may wake the agent through sleep. Hot-reloaded from
     // privilegedUsersPath on change.
     privilegedUsersPath;
@@ -332,6 +354,9 @@ 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);
     }
     // =========================================================================
     // Config loading
@@ -382,6 +407,12 @@ 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;
         });
     }
@@ -447,6 +478,103 @@ 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, options) {
+        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) {
+        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() {
+        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.
+     */
+    writeConfig(config) {
+        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
     // =========================================================================
     matchPolicy(info) {
@@ -511,6 +639,18 @@ 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) => 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;
     }
     // =========================================================================
@@ -545,7 +685,11 @@ 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 = scripted != null ? { name: 'gate.js', match: {}, behavior: scripted } : this.matchPolicy(info);
         const decision = this.computeDecision(policy, info);
         this.totalEvaluations++;
         if (!policy) {
@@ -592,8 +736,9 @@ export class EventGate {
             source: info.serverId || undefined,
             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') {
             this.applyResets(policy);
@@ -729,6 +874,7 @@ export class EventGate {
                 serverId: metadata.serverId ?? '',
                 channelId: metadata.channelId ?? '',
                 metadata,
+                tags: Array.isArray(metadata.tags) ? metadata.tags : undefined,
             });
             return decision.trigger;
         };
@@ -812,6 +958,17 @@ export class EventGate {
             queueMicrotask(() => this.deliverEvents(events));
         }
     }
+    /** Live inference-gating snapshot for diagnostics (e.g. a SIGUSR2 dump).
+     *  A non-empty `inferring` with a stale timestamp + growing `bufferedEvents`
+     *  is the signature of the wake-wedge: an agent stuck mid-"inference" so all
+     *  incoming events buffer and never trigger. */
+    inferenceDiagnostics() {
+        return {
+            inferring: [...this.inferring],
+            bufferedEvents: this.inferenceBuffer.length,
+            sleepUntil: this.sleepUntil,
+        };
+    }
     // =========================================================================
     // Inference buffer cap
     // =========================================================================
@@ -831,11 +988,18 @@ export class EventGate {
     // Sleep
     // =========================================================================
     /** Begin (or extend) a sleep window of `seconds`. Returns the wake time. */
-    setSleep(seconds, note) {
+    setSleep(seconds, note, agentName) {
         const ms = Math.max(0, Math.floor(seconds * 1000));
         this.sleepUntil = this.now() + ms;
         this.sleepNote = note;
+        this.sleepAgent = agentName;
         this.sleepSuppressed = 0;
+        // Arm the self-wake: when the window elapses, clear sleep and request an
+        // inference so the agent resumes on its own (not dependent on a heartbeat
+        // tick or an incoming message). Cancelled by clearSleep()/`wake`.
+        if (this.sleepTimer)
+            clearTimeout(this.sleepTimer);
+        this.sleepTimer = setTimeout(() => this.wakeFromSleep('sleep-expired'), ms);
         this.reloadPrivilegedIfChanged();
         this.emitTrace({
             type: 'gate:decision',
@@ -852,8 +1016,42 @@ export class EventGate {
         const wasAsleep = this.sleepUntil > this.now();
         this.sleepUntil = 0;
         this.sleepNote = undefined;
+        this.sleepAgent = undefined;
+        if (this.sleepTimer) {
+            clearTimeout(this.sleepTimer);
+            this.sleepTimer = null;
+        }
         return wasAsleep;
     }
+    /**
+     * Self-wake handler: fired by the sleepTimer when a sleep window elapses.
+     * Clears the sleep state and requests an inference so the agent wakes on its
+     * own — this is what makes `sleep(N)` a real "wake me in N seconds" rather
+     * than just a suppression window. No-op if sleep was already cleared (via
+     * `wake`) or re-armed to a later time by a fresh `sleep` call.
+     */
+    wakeFromSleep(reason) {
+        this.sleepTimer = null;
+        if (this.sleepUntil === 0 || this.sleepUntil > this.now())
+            return;
+        const note = this.sleepNote;
+        const agent = this.sleepAgent;
+        this.sleepUntil = 0;
+        this.sleepNote = undefined;
+        this.sleepAgent = undefined;
+        this.emitTrace({
+            type: 'gate:decision',
+            eventType: 'sleep:expired',
+            matchedPolicy: 'asleep',
+            trigger: true,
+            behavior: 'always',
+            timestamp: this.now(),
+        });
+        const detail = note ? `${reason}: ${note}` : reason;
+        const targets = agent ? [agent] : this.getAgentNamesFn();
+        for (const a of targets)
+            this.requestInferenceFn(a, detail, 'sleep');
+    }
     /** Current sleep state, or null if awake. */
     getSleepState() {
         const remainingMs = this.sleepUntil - this.now();
@@ -976,6 +1174,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,
@@ -990,6 +1189,7 @@ export class EventGate {
     // Cleanup
     // =========================================================================
     dispose() {
+        this.gateScript.dispose();
         for (const state of this.debounceTimers.values()) {
             clearTimeout(state.timer);
         }