feat: Discord-based agent wakeup replacing spawn

New wakeup flow:
1. Create private Discord channel for the agent
2. Send wakeup message with slot context + workflow reference
3. If Dirigent detected (globalThis.__dirigent), create work-type channel
4. Fallback to api.spawn if Discord not configured

New config fields: discordBotToken, discordGuildId
New file: plugin/calendar/discord-wakeup.ts

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

REFACTOR_PLAN.md

@@ -0,0 +1,112 @@
+# CalendarScheduler Refactor Plan
+
+## Current Design
+
+```
+Every 60s:
+  heartbeat() → POST /calendar/agent/heartbeat → returns pending slots
+  if idle → select highest priority → executeSlot → wakeAgent(spawn)
+  if busy → defer all pending slots
+```
+
+**Problems:**
+1. Every heartbeat queries backend for pending slots — no local awareness of full schedule
+2. Cannot detect slots assigned by other agents between heartbeats
+3. 60s interval is too frequent for sync but too infrequent for precise wakeup
+4. Wakeup via `api.spawn()` creates a plain session, not a Discord private channel
+
+## Target Design
+
+```
+Every 5-10 min (sync interval):
+  syncSchedule() → GET /calendar/day → update local today cache
+
+Every 30s (check interval):
+  checkDueSlots() → scan local cache for due slots
+  if due slot found:
+    confirmAgentStatus() → GET /calendar/agent/status
+    if not busy → wakeAgent (via Dirigent moderator bot private channel)
+```
+
+## Changes Required
+
+### 1. Add Local Schedule Cache
+
+New class `ScheduleCache`:
+```typescript
+class ScheduleCache {
+  private slots: Map<string, CalendarSlotResponse>;  // slotId → slot
+  private lastSyncAt: Date | null;
+
+  async sync(bridge: CalendarBridgeClient): Promise<void>;  // fetch today's full schedule
+  getDueSlots(now: Date): CalendarSlotResponse[];  // scheduled_at <= now && NOT_STARTED/DEFERRED
+  updateSlot(id: string, update: Partial<CalendarSlotResponse>): void;  // local update
+  getAll(): CalendarSlotResponse[];
+}
+```
+
+### 2. Add CalendarBridgeClient.getDaySchedule()
+
+New endpoint call:
+```typescript
+async getDaySchedule(date: string): Promise<CalendarSlotResponse[]>
+// GET /calendar/day?date=YYYY-MM-DD
+```
+
+This fetches ALL slots for the day, not just pending ones. The existing `heartbeat()` only returns NOT_STARTED/DEFERRED.
+
+### 3. Split Heartbeat into Sync + Check
+
+**Replace** single `runHeartbeat()` with two intervals:
+
+```typescript
+// Sync: every 5 min — pull full schedule from backend
+this.syncInterval = setInterval(() => this.runSync(), 300_000);
+
+// Check: every 30s — scan local cache for due slots
+this.checkInterval = setInterval(() => this.runCheck(), 30_000);
+```
+
+`runSync()`:
+1. `bridge.getDaySchedule(today)` → update cache
+2. Still send heartbeat to keep backend informed of agent liveness
+
+`runCheck()`:
+1. `cache.getDueSlots(now)` → find due slots
+2. Filter out session-deferred slots
+3. If agent idle → select highest priority → execute
+
+### 4. Wakeup via Dirigent (future)
+
+Change `wakeAgent()` to create a private Discord channel via Dirigent moderator bot instead of `api.spawn()`. This requires:
+- Access to Dirigent's moderator bot token or cross-plugin API
+- Creating a private channel with only the target agent
+- Posting the wakeup prompt as a message
+
+**For now:** Keep `api.spawn()` as the wakeup method. The Dirigent integration can be added later as it requires cross-plugin coordination.
+
+## Implementation Order
+
+1. Add `ScheduleCache` class (new file: `plugin/calendar/schedule-cache.ts`)
+2. Add `getDaySchedule()` to `CalendarBridgeClient`
+3. Refactor `CalendarScheduler`:
+   - Replace single interval with sync + check intervals
+   - Use cache instead of heartbeat for slot discovery
+   - Keep heartbeat for agent liveness reporting (reduced frequency)
+4. Update state persistence for new structure
+5. Keep existing wakeAgent/completion/abort/pause/resume tools unchanged
+
+## Files to Modify
+
+| File | Changes |
+|------|---------|
+| `plugin/calendar/schedule-cache.ts` | New file |
+| `plugin/calendar/calendar-bridge.ts` | Add `getDaySchedule()` |
+| `plugin/calendar/scheduler.ts` | Refactor heartbeat → sync + check |
+| `plugin/calendar/index.ts` | Export new types |
+
+## Risk Assessment
+
+- **Low risk:** ScheduleCache is additive, doesn't break existing behavior
+- **Medium risk:** Splitting heartbeat changes core scheduling logic
+- **Mitigation:** Keep `heartbeat()` method intact, use it for liveness reporting alongside new sync

plugin/calendar/calendar-bridge.ts

@@ -169,6 +169,32 @@ export class CalendarBridgeClient {
     return this.sendBoolean('POST', url, body);
   }
 
+  /**
+   * Fetch the full day schedule for this agent.
+   *
+   * Unlike heartbeat() which only returns pending (NOT_STARTED/DEFERRED) slots,
+   * this returns ALL slots for the given date, enabling the plugin to maintain
+   * a complete local view of today's schedule.
+   *
+   * @param date  Date string in YYYY-MM-DD format
+   * @returns Array of all slots for the day, or null if unreachable
+   */
+  async getDaySchedule(date: string): Promise<CalendarSlotResponse[] | null> {
+    const url = `${this.baseUrl}/calendar/day?date=${encodeURIComponent(date)}`;
+    try {
+      const response = await this.fetchJson<{ slots: CalendarSlotResponse[] }>(url, {
+        method: 'GET',
+        headers: {
+          'X-Agent-ID': this.config.agentId,
+          'X-Claw-Identifier': this.config.clawIdentifier,
+        },
+      });
+      return response?.slots ?? null;
+    } catch {
+      return null;
+    }
+  }
+
   // -------------------------------------------------------------------------
   // Internal helpers
   // -------------------------------------------------------------------------

plugin/calendar/discord-wakeup.ts

@@ -0,0 +1,172 @@
+/**
+ * Discord-based agent wakeup: create a private channel and send a wakeup message.
+ *
+ * If Dirigent is detected (via globalThis.__dirigent), creates a work-type channel.
+ * Otherwise, creates a plain private Discord channel.
+ */
+
+const DISCORD_API = 'https://discord.com/api/v10';
+
+interface WakeupConfig {
+  botToken: string;
+  guildId: string;
+  agentDiscordId?: string;
+  agentId: string;
+  message: string;
+  logger: {
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+  };
+}
+
+interface DirigentApi {
+  createWorkChannel?: (params: {
+    guildId: string;
+    name: string;
+    agentDiscordId: string;
+  }) => Promise<string>;
+}
+
+/**
+ * Get bot user ID from token (decode JWT-like Discord token).
+ */
+function getBotUserIdFromToken(token: string): string | null {
+  try {
+    const base64 = token.split('.')[0];
+    const decoded = Buffer.from(base64, 'base64').toString('utf8');
+    return decoded || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a private Discord channel visible only to the target agent and bot.
+ */
+async function createPrivateChannel(
+  token: string,
+  guildId: string,
+  name: string,
+  memberIds: string[],
+  logger: WakeupConfig['logger']
+): Promise<string | null> {
+  const botId = getBotUserIdFromToken(token);
+
+  // Permission overwrites: deny @everyone, allow specific members
+  const permissionOverwrites = [
+    { id: guildId, type: 0, deny: '1024' }, // deny @everyone view
+    ...memberIds.map(id => ({ id, type: 1, allow: '1024' })), // allow members view
+    ...(botId ? [{ id: botId, type: 1, allow: '1024' }] : []),
+  ];
+
+  try {
+    const res = await fetch(`${DISCORD_API}/guilds/${guildId}/channels`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bot ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        name,
+        type: 0, // text channel
+        permission_overwrites: permissionOverwrites,
+      }),
+    });
+
+    if (!res.ok) {
+      logger.warn(`Discord channel creation failed: ${res.status} ${await res.text()}`);
+      return null;
+    }
+
+    const data = await res.json() as { id: string };
+    return data.id;
+  } catch (err) {
+    logger.error(`Discord channel creation error: ${String(err)}`);
+    return null;
+  }
+}
+
+/**
+ * Send a message to a Discord channel.
+ */
+async function sendMessage(
+  token: string,
+  channelId: string,
+  content: string,
+  logger: WakeupConfig['logger']
+): Promise<boolean> {
+  try {
+    const res = await fetch(`${DISCORD_API}/channels/${channelId}/messages`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bot ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ content }),
+    });
+
+    if (!res.ok) {
+      logger.warn(`Discord message send failed: ${res.status}`);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    logger.error(`Discord message send error: ${String(err)}`);
+    return false;
+  }
+}
+
+/**
+ * Wake an agent via Discord: create a private channel and send the wakeup message.
+ */
+export async function wakeAgentViaDiscord(config: WakeupConfig): Promise<boolean> {
+  const { botToken, guildId, agentDiscordId, agentId, message, logger } = config;
+
+  if (!botToken || !guildId) {
+    logger.warn('Discord wakeup: botToken or guildId not configured');
+    return false;
+  }
+
+  // Check if Dirigent is available for work channel creation
+  const dirigent = (globalThis as Record<string, unknown>)['__dirigent'] as DirigentApi | undefined;
+
+  let channelId: string | null = null;
+  const channelName = `hf-wakeup-${agentId}-${Date.now()}`;
+
+  if (dirigent?.createWorkChannel && agentDiscordId) {
+    // Use Dirigent to create a work-type channel (with turn management)
+    try {
+      channelId = await dirigent.createWorkChannel({
+        guildId,
+        name: channelName,
+        agentDiscordId,
+      });
+      logger.info(`Wakeup channel created via Dirigent: ${channelId}`);
+    } catch (err) {
+      logger.warn(`Dirigent work channel creation failed, falling back to plain channel: ${String(err)}`);
+    }
+  }
+
+  if (!channelId) {
+    // Fallback: create a plain private Discord channel
+    const memberIds = agentDiscordId ? [agentDiscordId] : [];
+    channelId = await createPrivateChannel(botToken, guildId, channelName, memberIds, logger);
+    if (channelId) {
+      logger.info(`Wakeup channel created (plain): ${channelId}`);
+    }
+  }
+
+  if (!channelId) {
+    logger.error('Failed to create wakeup channel');
+    return false;
+  }
+
+  // Send the wakeup message
+  const sent = await sendMessage(botToken, channelId, message, logger);
+  if (sent) {
+    logger.info(`Wakeup message sent to ${channelId} for agent ${agentId}`);
+  }
+
+  return sent;
+}

plugin/calendar/index.ts

@@ -31,3 +31,5 @@
 export * from './types';
 export * from './calendar-bridge';
 export * from './scheduler';
+export * from './schedule-cache';
+export * from './discord-wakeup';

plugin/calendar/schedule-cache.ts

@@ -0,0 +1,109 @@
+/**
+ * Local cache of today's calendar schedule.
+ * Synced periodically from HF backend, checked locally for due slots.
+ */
+
+import type { CalendarSlotResponse } from "./types.js";
+
+export class ScheduleCache {
+  private slots: Map<string, CalendarSlotResponse> = new Map();
+  private lastSyncAt: Date | null = null;
+  private cachedDate: string | null = null; // YYYY-MM-DD
+
+  /**
+   * Replace the cache with a fresh schedule from backend.
+   */
+  sync(date: string, slots: CalendarSlotResponse[]): void {
+    // If date changed, clear old data
+    if (this.cachedDate !== date) {
+      this.slots.clear();
+    }
+    this.cachedDate = date;
+
+    // Merge: update existing slots, add new ones
+    const incomingIds = new Set<string>();
+    for (const slot of slots) {
+      const id = this.getSlotId(slot);
+      incomingIds.add(id);
+      this.slots.set(id, slot);
+    }
+
+    // Remove slots that no longer exist on backend (cancelled etc.)
+    for (const id of this.slots.keys()) {
+      if (!incomingIds.has(id)) {
+        this.slots.delete(id);
+      }
+    }
+
+    this.lastSyncAt = new Date();
+  }
+
+  /**
+   * Get slots that are due (scheduled_at <= now) and still pending.
+   */
+  getDueSlots(now: Date): CalendarSlotResponse[] {
+    const results: CalendarSlotResponse[] = [];
+    for (const slot of this.slots.values()) {
+      if (slot.status !== "not_started" && slot.status !== "deferred") continue;
+      if (!slot.scheduled_at) continue;
+
+      const scheduledAt = this.parseScheduledTime(slot.scheduled_at);
+      if (scheduledAt && scheduledAt <= now) {
+        results.push(slot);
+      }
+    }
+    // Sort by priority descending
+    results.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    return results;
+  }
+
+  /**
+   * Update a slot locally (e.g., after status change).
+   */
+  updateSlot(slotId: string, update: Partial<CalendarSlotResponse>): void {
+    const existing = this.slots.get(slotId);
+    if (existing) {
+      this.slots.set(slotId, { ...existing, ...update });
+    }
+  }
+
+  /**
+   * Remove a slot from cache.
+   */
+  removeSlot(slotId: string): void {
+    this.slots.delete(slotId);
+  }
+
+  /**
+   * Get all cached slots.
+   */
+  getAll(): CalendarSlotResponse[] {
+    return Array.from(this.slots.values());
+  }
+
+  /**
+   * Get cache metadata.
+   */
+  getStatus(): { slotCount: number; lastSyncAt: string | null; cachedDate: string | null } {
+    return {
+      slotCount: this.slots.size,
+      lastSyncAt: this.lastSyncAt?.toISOString() ?? null,
+      cachedDate: this.cachedDate,
+    };
+  }
+
+  private getSlotId(slot: CalendarSlotResponse): string {
+    return slot.virtual_id ?? String(slot.id);
+  }
+
+  private parseScheduledTime(scheduledAt: string): Date | null {
+    // scheduled_at can be "HH:MM:SS" (time only) or full ISO
+    if (/^\d{2}:\d{2}(:\d{2})?$/.test(scheduledAt)) {
+      // Time-only: combine with cached date
+      if (!this.cachedDate) return null;
+      return new Date(`${this.cachedDate}T${scheduledAt}Z`);
+    }
+    const d = new Date(scheduledAt);
+    return isNaN(d.getTime()) ? null : d;
+  }
+}

plugin/calendar/scheduler.ts

@@ -19,6 +19,7 @@
 import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { CalendarBridgeClient } from './calendar-bridge';
+import { ScheduleCache } from './schedule-cache';
 import {
   CalendarSlotResponse,
   SlotStatus,
@@ -44,6 +45,8 @@ export interface CalendarSchedulerConfig {
   };
   /** Heartbeat interval in milliseconds (default: 60000) */
   heartbeatIntervalMs?: number;
+  /** Schedule sync interval in milliseconds (default: 300000 = 5 min) */
+  syncIntervalMs?: number;
   /** Enable verbose debug logging */
   debug?: boolean;
   /** Directory for state persistence (default: plugin data dir) */
@@ -95,8 +98,10 @@ interface SchedulerState {
   currentSlot: CalendarSlotResponse | null;
   /** Last heartbeat timestamp */
   lastHeartbeatAt: Date | null;
-  /** Interval handle for cleanup */
+  /** Heartbeat interval handle */
   intervalHandle: ReturnType<typeof setInterval> | null;
+  /** Schedule sync interval handle */
+  syncIntervalHandle: ReturnType<typeof setInterval> | null;
   /** Set of slot IDs that have been deferred in current session */
   deferredSlotIds: Set<string>;
   /** Whether agent is currently processing a slot */
@@ -117,10 +122,13 @@ export class CalendarScheduler {
   private config: Required<CalendarSchedulerConfig>;
   private state: SchedulerState;
   private stateFilePath: string;
+  /** Local cache of today's full schedule, synced periodically from backend */
+  private scheduleCache: ScheduleCache = new ScheduleCache();
 
   constructor(config: CalendarSchedulerConfig) {
     this.config = {
       heartbeatIntervalMs: 60000, // 1 minute default
+      syncIntervalMs: 300_000,    // 5 minutes default
       debug: false,
       stateDir: this.getDefaultStateDir(),
       ...config,
@@ -133,6 +141,7 @@ export class CalendarScheduler {
       currentSlot: null,
       lastHeartbeatAt: null,
       intervalHandle: null,
+      syncIntervalHandle: null,
       deferredSlotIds: new Set(),
       isProcessing: false,
       isRestartPending: false,
@@ -327,14 +336,21 @@ export class CalendarScheduler {
     this.state.isRestartPending = false;
     this.config.logger.info('Calendar scheduler started');
 
-    // Run initial heartbeat immediately
+    // Run initial sync + heartbeat immediately
+    this.runSync();
     this.runHeartbeat();
 
-    // Schedule periodic heartbeats
+    // Schedule periodic heartbeats (slot execution checks)
     this.state.intervalHandle = setInterval(
       () => this.runHeartbeat(),
       this.config.heartbeatIntervalMs
     );
+
+    // Schedule periodic schedule sync (full day schedule refresh)
+    this.state.syncIntervalHandle = setInterval(
+      () => this.runSync(),
+      this.config.syncIntervalMs
+    );
   }
 
   /**
@@ -348,10 +364,41 @@ export class CalendarScheduler {
       clearInterval(this.state.intervalHandle);
       this.state.intervalHandle = null;
     }
+    if (this.state.syncIntervalHandle) {
+      clearInterval(this.state.syncIntervalHandle);
+      this.state.syncIntervalHandle = null;
+    }
 
     this.config.logger.info('Calendar scheduler stopped');
   }
 
+  /**
+   * Sync today's full schedule from backend into local cache.
+   * Runs every syncIntervalMs (default: 5 min).
+   * Catches new slots assigned by other agents or the manager.
+   */
+  async runSync(): Promise<void> {
+    if (!this.state.isRunning || this.state.isRestartPending) return;
+
+    const today = new Date().toISOString().slice(0, 10);
+    try {
+      const slots = await this.config.bridge.getDaySchedule(today);
+      if (slots) {
+        this.scheduleCache.sync(today, slots);
+        this.logDebug(`Schedule synced: ${slots.length} slots for ${today}`);
+      }
+    } catch (err) {
+      this.config.logger.warn(`Schedule sync failed: ${String(err)}`);
+    }
+  }
+
+  /**
+   * Get the local schedule cache (for status reporting / tools).
+   */
+  getScheduleCache(): ScheduleCache {
+    return this.scheduleCache;
+  }
+
   /**
    * Execute a single heartbeat cycle.
    * Fetches pending slots and handles execution logic.
@@ -611,13 +658,11 @@ Task Code: ${code}
 Estimated Duration: ${duration} minutes
 Slot Type: ${slot.slot_type}
 Priority: ${slot.priority}
+Working Sessions: ${jobData.working_sessions?.join(', ') || 'none recorded'}
 
-Please focus on this task for the allocated time. When you finish or need to pause,
-report your progress back to the calendar system.
-
-Working sessions: ${jobData.working_sessions?.join(', ') || 'none recorded'}
-
-Start working on ${code} now.`;
+Follow the daily-routine skill's task-handson workflow to execute this task.
+Use harborforge_calendar_complete when finished, or harborforge_calendar_pause to pause.
+Before going idle, check for overdue slots as described in the slot-complete workflow.`;
   }
 
   /**
@@ -630,19 +675,15 @@ Start working on ${code} now.`;
     switch (sysData.event) {
       case 'ScheduleToday':
         return `System Event: Schedule Today
-
-Please review today's calendar and schedule any pending tasks or planning activities.
 Estimated time: ${slot.estimated_duration} minutes.
 
-Check your calendar and plan the day's work.`;
+Follow the daily-routine skill's plan-schedule workflow to plan today's work.`;
 
       case 'SummaryToday':
         return `System Event: Daily Summary
-
-Please provide a summary of today's activities and progress.
 Estimated time: ${slot.estimated_duration} minutes.
 
-Review what was accomplished and prepare end-of-day notes.`;
+Review today's completed, deferred, and abandoned slots. Write a summary to your daily note (memory/YYYY-MM-DD.md).`;
 
       case 'ScheduledGatewayRestart':
         return `System Event: Scheduled Gateway Restart

plugin/index.ts

@@ -171,53 +171,52 @@ export default {
     }
 
     /**
-     * Wake/spawn agent with task context for slot execution.
+     * Wake agent via Discord channel creation + message.
      * This is the callback invoked by CalendarScheduler when a slot is ready.
+     *
+     * Priority:
+     *   1. Discord wakeup (create private channel + send message)
+     *   2. OpenClaw spawn API (fallback if Discord not configured)
      */
     async function wakeAgent(context: AgentWakeContext): Promise<boolean> {
       logger.info(`Waking agent for slot: ${context.taskDescription}`);
+      const live = resolveConfig();
+      const agentId = process.env.AGENT_ID || 'unknown';
 
       try {
-        // Method 1: Use OpenClaw spawn API if available (preferred)
+        // Method 1: Discord wakeup (preferred)
+        const discordBotToken = (live as any).discordBotToken as string | undefined;
+        const discordGuildId = (live as any).discordGuildId as string | undefined;
+
+        if (discordBotToken && discordGuildId) {
+          const { wakeAgentViaDiscord } = await import('./calendar/discord-wakeup.js');
+          const success = await wakeAgentViaDiscord({
+            botToken: discordBotToken,
+            guildId: discordGuildId,
+            agentId,
+            message: context.prompt,
+            logger,
+          });
+          if (success) return true;
+          logger.warn('Discord wakeup failed, trying spawn fallback');
+        }
+
+        // Method 2: OpenClaw spawn API (fallback)
         if (api.spawn) {
           const result = await api.spawn({
             task: context.prompt,
-            timeoutSeconds: context.slot.estimated_duration * 60, // Convert to seconds
+            timeoutSeconds: context.slot.estimated_duration * 60,
           });
 
           if (result?.sessionId) {
             logger.info(`Agent spawned for calendar slot: session=${result.sessionId}`);
-
-            // Track session completion
             trackSessionCompletion(result.sessionId, context);
             return true;
           }
         }
 
-        // Method 2: Send notification/alert to wake agent (fallback)
-        // This relies on the agent's heartbeat to check for notifications
-        logger.warn('OpenClaw spawn API not available, using notification fallback');
-
-        // Send calendar wakeup notification via backend
-        const live = resolveConfig();
-        const agentId = process.env.AGENT_ID || 'unknown';
-
-        const notifyResponse = await fetch(`${live.backendUrl}/calendar/agent/notify`, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            'X-Agent-ID': agentId,
-            'X-Claw-Identifier': live.identifier || hostname(),
-          },
-          body: JSON.stringify({
-            agent_id: agentId,
-            message: context.prompt,
-            slot_id: context.slot.id || context.slot.virtual_id,
-            task_description: context.taskDescription,
-          }),
-        });
-
-        return notifyResponse.ok;
+        logger.warn('No wakeup method available (configure discordBotToken + discordGuildId)');
+        return false;
 
       } catch (err) {
         logger.error('Failed to wake agent:', err);

plugin/openclaw.plugin.json

@@ -63,6 +63,14 @@
       "managedMonitor": {
         "type": "string",
         "description": "Absolute path to an installed HarborForge.Monitor binary managed by this plugin installer. If set, gateway_start/gateway_stop hooks will start/stop the monitor process automatically."
+      },
+      "discordBotToken": {
+        "type": "string",
+        "description": "Discord bot token for agent wakeup. Used to create private channels and send wakeup messages. Set to the same value as Dirigent moderator bot token."
+      },
+      "discordGuildId": {
+        "type": "string",
+        "description": "Discord guild ID where wakeup channels are created."
       }
     }
   }