clementine-agent 1.0.81 → 1.0.82

package/dist/gateway/agent-heartbeat-manager.d.ts

@@ -19,15 +19,38 @@ export declare class AgentHeartbeatManager {
     private timer;
     private running;
     private ticking;
+    private readonly perAgentWatchers;
+    private goalTriggerWatcher;
+    private wakeDirWatcher;
+    private readonly pendingWakes;
     constructor(agentManager: AgentManager, gateway?: AgentHeartbeatGateway);
     start(): void;
     stop(): void;
+    /**
+     * Set up fs.watch on the directories that signal real work for an agent:
+     *
+     * - per-agent tasks dir (delegated tasks land here)
+     * - goal-triggers dir (any goal trigger; we route to the owner)
+     * - wake-sentinels dir (explicit wake_agent calls)
+     *
+     * On a relevant change, schedule a debounced wake for the matching
+     * scheduler. Failures here are non-fatal — polling still works.
+     */
+    private setupWatchers;
+    /** Watch a single agent's tasks directory. Idempotent. */
+    private watchAgentTasks;
+    private teardownWatchers;
+    /** Debounced wake — coalesce a burst of events into one markDue call. */
+    private scheduleWake;
+    /** Goal trigger landed — wake the owning agent. Non-Clementine owners only. */
+    private handleGoalTriggerEvent;
     /** Add/remove schedulers to match the current AgentManager listing. */
     private reconcile;
     /**
-     * One outer-loop tick. Reconcile the registry, then fire agents whose
-     * nextCheckAt has come due. Runs serially to avoid races on shared
-     * state (goals dir, cron runs dir).
+     * One outer-loop tick. Reconcile the registry, then fire all due agents
+     * concurrently. Each agent's tick is isolated by profile + idempotency-keyed
+     * filesystem writes, so parallel execution is safe — and 3+ specialists no
+     * longer queue behind each other.
      */
     private outerTick;
     /** Diagnostic helper for the dashboard / CLI. */

package/dist/gateway/agent-heartbeat-manager.js

@@ -10,10 +10,20 @@
  * out. Per-agent failures are caught so one buggy agent can't crash the
  * daemon or stall others.
  */
+import { existsSync, mkdirSync, watch } from 'node:fs';
+import path from 'node:path';
 import pino from 'pino';
+import { AGENTS_DIR, BASE_DIR } from '../config.js';
+import { listAllGoals } from '../tools/shared.js';
 import { AgentHeartbeatScheduler } from './agent-heartbeat-scheduler.js';
 const logger = pino({ name: 'clementine.agent-heartbeat-manager' });
 const OUTER_TICK_MS = 60_000;
+/**
+ * After a watched event fires, wait this long before actually waking the
+ * agent. Coalesces filesystem storms (a burst of file writes from one
+ * action shouldn't trigger N wake-ups).
+ */
+const WAKE_DEBOUNCE_MS = 3_000;
 export class AgentHeartbeatManager {
     agentManager;
     gateway;
@@ -21,6 +31,12 @@ export class AgentHeartbeatManager {
     timer = null;
     running = false;
     ticking = false;
+    // Per-directory fs.watch handles, indexed by slug for cleanup
+    perAgentWatchers = new Map();
+    goalTriggerWatcher = null;
+    wakeDirWatcher = null;
+    // Debounce wake-ups per slug so a burst of file events fires one tick.
+    pendingWakes = new Map();
     constructor(agentManager, gateway) {
         this.agentManager = agentManager;
         this.gateway = gateway ?? null;
@@ -30,6 +46,7 @@ export class AgentHeartbeatManager {
             return;
         this.running = true;
         this.reconcile();
+        this.setupWatchers();
         // Run an immediate tick so schedulers boot up without a 60s delay.
         this.outerTick().catch((err) => logger.error({ err }, 'Initial agent heartbeat tick failed'));
         this.timer = setInterval(() => {
@@ -45,9 +62,155 @@ export class AgentHeartbeatManager {
             clearInterval(this.timer);
             this.timer = null;
         }
+        this.teardownWatchers();
         this.schedulers.clear();
         logger.info('Agent heartbeat manager stopped');
     }
+    /**
+     * Set up fs.watch on the directories that signal real work for an agent:
+     *
+     * - per-agent tasks dir (delegated tasks land here)
+     * - goal-triggers dir (any goal trigger; we route to the owner)
+     * - wake-sentinels dir (explicit wake_agent calls)
+     *
+     * On a relevant change, schedule a debounced wake for the matching
+     * scheduler. Failures here are non-fatal — polling still works.
+     */
+    setupWatchers() {
+        // Per-agent task dirs
+        for (const [slug] of this.schedulers) {
+            this.watchAgentTasks(slug);
+        }
+        // Goal-triggers (one trigger per goal; we resolve owner → slug at fire time)
+        const triggerDir = path.join(BASE_DIR, 'cron', 'goal-triggers');
+        try {
+            mkdirSync(triggerDir, { recursive: true });
+            this.goalTriggerWatcher = watch(triggerDir, (eventType, filename) => {
+                if (eventType !== 'rename' || !filename || !filename.endsWith('.trigger.json'))
+                    return;
+                // Trigger filenames are idempotencyKey-based — we don't have a slug here,
+                // so wake any agent whose goal might match. Cheap enough: reconcile with
+                // listAllGoals once and wake the affected owners.
+                this.handleGoalTriggerEvent(filename);
+            });
+        }
+        catch (err) {
+            logger.warn({ err, triggerDir }, 'Failed to watch goal-triggers — falling back to polling');
+        }
+        // Wake sentinels (F3): wake_agent tool writes BASE_DIR/heartbeat/wake/<slug>.json
+        const wakeDir = path.join(BASE_DIR, 'heartbeat', 'wake');
+        try {
+            mkdirSync(wakeDir, { recursive: true });
+            this.wakeDirWatcher = watch(wakeDir, (eventType, filename) => {
+                if (eventType !== 'rename' || !filename)
+                    return;
+                if (!filename.endsWith('.json'))
+                    return;
+                const slug = filename.replace(/\.json$/, '');
+                // Consume the sentinel + wake the agent
+                try {
+                    // Use unlinkSync via require to keep top-level import surface tight
+                    // (already imported existsSync — we use it before unlink to be safe)
+                    const sentinelPath = path.join(wakeDir, filename);
+                    if (existsSync(sentinelPath)) {
+                        // best-effort: import unlinkSync inline
+                        // eslint-disable-next-line @typescript-eslint/no-var-requires
+                        const fs = require('node:fs');
+                        try {
+                            fs.unlinkSync(sentinelPath);
+                        }
+                        catch { /* ignore */ }
+                    }
+                }
+                catch { /* non-fatal */ }
+                this.scheduleWake(slug, 'wake-sentinel');
+            });
+        }
+        catch (err) {
+            logger.warn({ err, wakeDir }, 'Failed to watch wake-sentinels — wake_agent tool will be slower');
+        }
+    }
+    /** Watch a single agent's tasks directory. Idempotent. */
+    watchAgentTasks(slug) {
+        if (this.perAgentWatchers.has(slug))
+            return;
+        const tasksDir = path.join(AGENTS_DIR, slug, 'tasks');
+        try {
+            mkdirSync(tasksDir, { recursive: true });
+            const watcher = watch(tasksDir, (eventType, filename) => {
+                if (!filename || !filename.endsWith('.json'))
+                    return;
+                // Both 'rename' (create/delete) and 'change' can indicate new work
+                this.scheduleWake(slug, `task-${eventType}:${filename}`);
+            });
+            this.perAgentWatchers.set(slug, watcher);
+        }
+        catch (err) {
+            logger.debug({ err, slug, tasksDir }, 'Could not watch agent tasks dir — will rely on polling');
+        }
+    }
+    teardownWatchers() {
+        for (const [, w] of this.perAgentWatchers) {
+            try {
+                w.close();
+            }
+            catch { /* ignore */ }
+        }
+        this.perAgentWatchers.clear();
+        try {
+            this.goalTriggerWatcher?.close();
+        }
+        catch { /* ignore */ }
+        this.goalTriggerWatcher = null;
+        try {
+            this.wakeDirWatcher?.close();
+        }
+        catch { /* ignore */ }
+        this.wakeDirWatcher = null;
+        for (const [, t] of this.pendingWakes)
+            clearTimeout(t);
+        this.pendingWakes.clear();
+    }
+    /** Debounced wake — coalesce a burst of events into one markDue call. */
+    scheduleWake(slug, reason) {
+        const existing = this.pendingWakes.get(slug);
+        if (existing)
+            clearTimeout(existing);
+        const t = setTimeout(() => {
+            this.pendingWakes.delete(slug);
+            const scheduler = this.schedulers.get(slug);
+            if (!scheduler)
+                return;
+            scheduler.markDue();
+            logger.info({ slug, reason }, 'Agent heartbeat: woken by event');
+            // Don't await — let the next outerTick (within ≤60s, or instant when
+            // we trigger one ourselves) actually run the tick.
+            this.outerTick().catch((err) => logger.warn({ err, slug }, 'Triggered tick after wake failed'));
+        }, WAKE_DEBOUNCE_MS);
+        this.pendingWakes.set(slug, t);
+    }
+    /** Goal trigger landed — wake the owning agent. Non-Clementine owners only. */
+    handleGoalTriggerEvent(filename) {
+        try {
+            // We don't yet know which goal id the trigger references without reading
+            // the file (idempotencyKey-named). Read it, find the owner, wake them.
+            const triggerPath = path.join(BASE_DIR, 'cron', 'goal-triggers', filename);
+            if (!existsSync(triggerPath))
+                return; // file was already consumed by cron-scheduler
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const fs = require('node:fs');
+            const trigger = JSON.parse(fs.readFileSync(triggerPath, 'utf-8'));
+            if (!trigger.goalId)
+                return;
+            const lookup = listAllGoals().find((g) => g.goal && g.goal.id === trigger.goalId);
+            if (!lookup || !lookup.owner || lookup.owner === 'clementine')
+                return;
+            this.scheduleWake(lookup.owner, `goal-trigger:${trigger.goalId}`);
+        }
+        catch (err) {
+            logger.debug({ err, filename }, 'Failed to handle goal-trigger event — non-fatal');
+        }
+    }
     /** Add/remove schedulers to match the current AgentManager listing. */
     reconcile() {
         let active = [];
@@ -66,6 +229,9 @@ export class AgentHeartbeatManager {
         for (const slug of active) {
             if (!this.schedulers.has(slug)) {
                 this.schedulers.set(slug, new AgentHeartbeatScheduler(slug, this.agentManager, this.gateway ? { gateway: this.gateway } : {}));
+                // Start watching this agent's tasks dir if we're already running
+                if (this.running)
+                    this.watchAgentTasks(slug);
                 logger.info({ slug }, 'Agent heartbeat: registered scheduler');
             }
         }
@@ -73,14 +239,28 @@ export class AgentHeartbeatManager {
         for (const slug of [...this.schedulers.keys()]) {
             if (!activeSet.has(slug)) {
                 this.schedulers.delete(slug);
+                const watcher = this.perAgentWatchers.get(slug);
+                if (watcher) {
+                    try {
+                        watcher.close();
+                    }
+                    catch { /* ignore */ }
+                    this.perAgentWatchers.delete(slug);
+                }
+                const pending = this.pendingWakes.get(slug);
+                if (pending) {
+                    clearTimeout(pending);
+                    this.pendingWakes.delete(slug);
+                }
                 logger.info({ slug }, 'Agent heartbeat: deregistered scheduler');
             }
         }
     }
     /**
-     * One outer-loop tick. Reconcile the registry, then fire agents whose
-     * nextCheckAt has come due. Runs serially to avoid races on shared
-     * state (goals dir, cron runs dir).
+     * One outer-loop tick. Reconcile the registry, then fire all due agents
+     * concurrently. Each agent's tick is isolated by profile + idempotency-keyed
+     * filesystem writes, so parallel execution is safe — and 3+ specialists no
+     * longer queue behind each other.
      */
     async outerTick(now = new Date()) {
         if (this.ticking)
@@ -88,16 +268,21 @@ export class AgentHeartbeatManager {
         this.ticking = true;
         try {
             this.reconcile();
+            const due = [];
             for (const [slug, scheduler] of this.schedulers) {
+                if (scheduler.isDue(now))
+                    due.push({ slug, scheduler });
+            }
+            if (due.length === 0)
+                return;
+            await Promise.all(due.map(async ({ slug, scheduler }) => {
                 try {
-                    if (!scheduler.isDue(now))
-                        continue;
                     await scheduler.tick(now);
                 }
                 catch (err) {
                     logger.warn({ err, slug }, 'Agent heartbeat tick failed — continuing');
                 }
-            }
+            }));
         }
         finally {
             this.ticking = false;

package/dist/gateway/agent-heartbeat-scheduler.d.ts

@@ -73,6 +73,13 @@ export declare class AgentHeartbeatScheduler {
     };
     /** Schedule the next check explicitly. Clamped to [MIN, MAX] minutes. */
     setNextCheckIn(minutes: number, now?: Date): void;
+    /**
+     * Mark the agent as due for a tick right now. Used for event-driven wake-ups
+     * (a delegated task arrives, an explicit wake_agent call) — bypasses the
+     * MIN_INTERVAL_MIN clamp that setNextCheckIn applies, since this is "wake
+     * now" not "set future cadence."
+     */
+    markDue(now?: Date): void;
     getSlug(): string;
 }
 //# sourceMappingURL=agent-heartbeat-scheduler.d.ts.map

package/dist/gateway/agent-heartbeat-scheduler.js

@@ -286,6 +286,21 @@ export class AgentHeartbeatScheduler {
         };
         this.saveState(state);
     }
+    /**
+     * Mark the agent as due for a tick right now. Used for event-driven wake-ups
+     * (a delegated task arrives, an explicit wake_agent call) — bypasses the
+     * MIN_INTERVAL_MIN clamp that setNextCheckIn applies, since this is "wake
+     * now" not "set future cadence."
+     */
+    markDue(now = new Date()) {
+        const prior = this.loadState();
+        const state = {
+            ...prior,
+            slug: this.slug,
+            nextCheckAt: now.toISOString(),
+        };
+        this.saveState(state);
+    }
     getSlug() {
         return this.slug;
     }

package/dist/tools/agent-heartbeat-tools.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Clementine TypeScript — Agent Heartbeat MCP tools.
+ *
+ * `wake_agent` lets an agent (typically Clementine, but anyone permitted
+ * via `canMessage`) wake another agent's heartbeat right now instead of
+ * waiting for their poll cycle. Useful when you've just delegated work
+ * and want them to react in seconds, not minutes.
+ *
+ * Implementation: writes a sentinel file at
+ *   ~/.clementine/heartbeat/wake/<slug>.json
+ * which AgentHeartbeatManager watches via fs.watch (set up in start()).
+ * On detection it consumes the sentinel and calls scheduler.markDue(),
+ * which makes the agent due on the next outerTick (≤60s, usually within
+ * the WAKE_DEBOUNCE_MS window).
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAgentHeartbeatTools(server: McpServer): void;
+//# sourceMappingURL=agent-heartbeat-tools.d.ts.map

package/dist/tools/agent-heartbeat-tools.js

@@ -0,0 +1,71 @@
+/**
+ * Clementine TypeScript — Agent Heartbeat MCP tools.
+ *
+ * `wake_agent` lets an agent (typically Clementine, but anyone permitted
+ * via `canMessage`) wake another agent's heartbeat right now instead of
+ * waiting for their poll cycle. Useful when you've just delegated work
+ * and want them to react in seconds, not minutes.
+ *
+ * Implementation: writes a sentinel file at
+ *   ~/.clementine/heartbeat/wake/<slug>.json
+ * which AgentHeartbeatManager watches via fs.watch (set up in start()).
+ * On detection it consumes the sentinel and calls scheduler.markDue(),
+ * which makes the agent due on the next outerTick (≤60s, usually within
+ * the WAKE_DEBOUNCE_MS window).
+ */
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { ACTIVE_AGENT_SLUG, AGENTS_DIR, BASE_DIR, logger, textResult } from './shared.js';
+const WAKE_DIR = path.join(BASE_DIR, 'heartbeat', 'wake');
+function isKnownAgent(slug) {
+    // A known agent is one with vault/00-System/agents/<slug>/agent.md present.
+    return existsSync(path.join(AGENTS_DIR, slug, 'agent.md'));
+}
+function listKnownAgentSlugs() {
+    if (!existsSync(AGENTS_DIR))
+        return [];
+    try {
+        return readdirSync(AGENTS_DIR, { withFileTypes: true })
+            .filter((d) => d.isDirectory() && !d.name.startsWith('_'))
+            .filter((d) => existsSync(path.join(AGENTS_DIR, d.name, 'agent.md')))
+            .map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+}
+export function registerAgentHeartbeatTools(server) {
+    server.tool('wake_agent', 'Wake an agent\'s heartbeat right now instead of waiting for their next poll cycle. Use after delegating urgent work or when an external signal needs immediate attention. The target agent will tick within ~3 seconds (debounced) and decide what to do.', {
+        slug: z.string().describe('Slug of the agent to wake (e.g., "ross-the-sdr")'),
+        reason: z.string().optional().describe('One-line reason for the wake — appears in the agent\'s next tick context'),
+    }, async ({ slug, reason }) => {
+        const callerSlug = ACTIVE_AGENT_SLUG || 'clementine';
+        if (!slug || typeof slug !== 'string') {
+            return textResult('wake_agent: slug is required.');
+        }
+        if (slug === callerSlug) {
+            return textResult(`wake_agent: cannot wake yourself (${slug}). You're already awake.`);
+        }
+        if (!isKnownAgent(slug)) {
+            const known = listKnownAgentSlugs();
+            return textResult(`wake_agent: unknown agent "${slug}". Known agents: ${known.length > 0 ? known.join(', ') : '(none)'}.`);
+        }
+        try {
+            mkdirSync(WAKE_DIR, { recursive: true });
+            const sentinel = {
+                targetSlug: slug,
+                fromSlug: callerSlug,
+                reason: reason ?? '',
+                requestedAt: new Date().toISOString(),
+            };
+            writeFileSync(path.join(WAKE_DIR, `${slug}.json`), JSON.stringify(sentinel, null, 2));
+            logger.info({ from: callerSlug, to: slug, reason: reason ?? '' }, 'wake_agent: sentinel written');
+            return textResult(`Woke ${slug}. They'll tick within ~3 seconds.${reason ? ` (Reason: ${reason})` : ''}`);
+        }
+        catch (err) {
+            return textResult(`wake_agent: failed to write sentinel — ${String(err).slice(0, 200)}`);
+        }
+    });
+}
+//# sourceMappingURL=agent-heartbeat-tools.js.map

package/dist/tools/mcp-server.js

@@ -26,6 +26,7 @@ import { registerTeamTools } from './team-tools.js';
 import { registerSessionTools } from './session-tools.js';
 import { registerArtifactTools } from './artifact-tools.js';
 import { registerBrainTools } from './brain-tools.js';
+import { registerAgentHeartbeatTools } from './agent-heartbeat-tools.js';
 // ── Server ──────────────────────────────────────────────────────────────
 const serverName = (env['ASSISTANT_NAME'] ?? 'Clementine').toLowerCase() + '-tools';
 const server = new McpServer({ name: serverName, version: '1.0.0' });
@@ -39,6 +40,7 @@ registerTeamTools(server);
 registerSessionTools(server);
 registerArtifactTools(server);
 registerBrainTools(server);
+registerAgentHeartbeatTools(server);
 // ── Main ────────────────────────────────────────────────────────────────
 async function main() {
     // Initialize memory store and run full sync on startup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.0.81",
+  "version": "1.0.82",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",