Merge pull request 'fix: real per-agent slot handle for multi-agent calendar tools' (#7) from fix/multi-agent-scheduler-handle into main

In multi-agent sync mode every harborforge_calendar_* tool was returning
`calendarScheduler.<method> is not a function`. The cause: index.ts replaced
`calendarScheduler` (typed `CalendarScheduler | null`) with a `{ stop() }`
stub right after wiring the runSync/runCheck intervals, so `isRunning()`,
`getCurrentSlot()`, `completeCurrentSlot()`, `abortCurrentSlot()`,
`pauseCurrentSlot()`, `resumeCurrentSlot()`, `getState()`,
`isRestartPending()` and `getStateFilePath()` all blew up at call time.

Replaces the stub with a `MultiAgentSchedulerHandle` that:
  - tracks the last slot dispatched per agent (recorded by `wakeAgent`)
  - exposes status/complete/abort/pause/resume taking the calling agentId
  - resolves the implicit "current slot" via woken-cursor first then a
    cache scan over not_started/deferred/ongoing slots
  - PATCHes via `bridge.updateSlotAs(agentId, …)` so audit headers reflect
    the real caller (bridge constructor agentId is 'unused' in multi-agent)
  - mirrors the legacy `isRunning/isProcessing/getState/...` surface so
    the single-agent fallback (`CalendarScheduler`) keeps working unchanged

Each calendar tool factory now takes `OpenClawPluginToolContext`, reads
`ctx.agentId`, and dispatches through the handle. Single-agent path
(when `calendarScheduler` is a real `CalendarScheduler`) is preserved
behind `instanceof` checks.

Drops the dead `trackSessionCompletion` poll loop (only definition, no
caller) which referenced the removed `completeCurrentSlot`. Bumps
plugin version 0.2.0 → 0.3.2.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

plugin/index.ts

@@ -25,25 +25,6 @@ import {
   CalendarScheduler,
 } from './calendar/index.js';
 
-// ---------------------------------------------------------------------------
-// Module-scope calendar scheduler singleton.
-//
-// `register()` is called multiple times per gateway boot — once per agent
-// (we see 5 `HarborForge plugin registered` lines for 5 agents on dind-t2).
-// `gateway_start` only fires once, so before this lift the
-// `startCalendarScheduler()` setup ran inside ONE closure while four other
-// closures kept their own `calendarScheduler = null`. Whichever of the five
-// tool registrations the gateway picked at call time was effectively a coin
-// flip, and four times out of five `harborforge_calendar_status` returned
-// `Calendar scheduler not running` even though the scheduler was active.
-//
-// Keeping the singleton at module scope removes the per-`register()` shadow:
-// the scheduler is started once, every closure reads the same binding, and
-// `startCalendarScheduler()` is idempotent so duplicate `gateway_start`
-// firings are harmless.
-// ---------------------------------------------------------------------------
-let calendarScheduler: MultiAgentSchedulerHandle | CalendarScheduler | null = null;
-
 interface PluginAPI {
   logger: {
     info: (...args: any[]) => void;
@@ -127,7 +108,7 @@ function register(api: PluginAPI): void {
         },
         openclaw: {
           version: api.runtime?.version || api.version || 'unknown',
-          pluginVersion: '0.3.4', // Bumped for PLG-CAL-004
+          pluginVersion: '0.3.2', // Bumped for PLG-CAL-004
         },
         timestamp: new Date().toISOString(),
       };
@@ -136,9 +117,13 @@ function register(api: PluginAPI): void {
     // Periodic metadata push interval handle
     let metaPushInterval: ReturnType<typeof setInterval> | null = null;
 
-    // (calendarScheduler is module-scope — see top of file for the why.
+    // Calendar scheduler instance.
-    //  Tools and lifecycle hooks all reference the same binding so the
+    //
-    //  multi-register/single-start mismatch can't shadow them again.)
+    // In multi-agent sync mode (the only path today) this is a
+    // {@link MultiAgentSchedulerHandle}. The legacy `CalendarScheduler` type
+    // is retained in the union for compatibility with the typed-only single-
+    // agent path that may be reintroduced later.
+    let calendarScheduler: MultiAgentSchedulerHandle | CalendarScheduler | null = null;
 
     /**
      * Push OpenClaw metadata to the Monitor bridge.
@@ -162,7 +147,7 @@ function register(api: PluginAPI): void {
 
       const meta: OpenClawMeta = {
         version: api.runtime?.version || api.version || 'unknown',
-        plugin_version: '0.3.4',
+        plugin_version: '0.3.2',
         agents: agentNames.map(name => ({ name })),
       };
 
@@ -267,21 +252,10 @@ function register(api: PluginAPI): void {
           )}\n\`\`\``;
         }
 
-        // First-line ack `WAKEUP_OK` is the plugin's ack-receipt token; the
-        // agent MUST then continue in the same session and drive the
-        // `hf-wakeup` workflow to completion (calendar_status → task fetch →
-        // sub-workflow → calendar_complete/abort). Without that continuation
-        // the scheduler keeps re-waking every 30s because the slot stays
-        // `not_started` forever.
         const wakeupMessage =
-          `You have due slots. **First line of your reply MUST be exactly ` +
+          `You have due slots. Follow the \`hf-wakeup\` workflow of skill ` +
-          `\`WAKEUP_OK\`** so the plugin records the ack. Then, **in this ` +
+          `\`hf-hangman-lab\` to proceed. Only reply \`WAKEUP_OK\` in this ` +
-          `same session**, drive the \`hf-wakeup\` workflow of skill ` +
+          `session.${slotBlock}`;
-          `\`hf-hangman-lab\` to completion — read slot context, call the ` +
-          `harborforge_calendar_* tools, route to the right sub-workflow, ` +
-          `and finish with harborforge_calendar_complete or abort. Do NOT ` +
-          `stop after the ack — the scheduler will re-wake you every 30s ` +
-          `until the slot transitions out of \`not_started\`.${slotBlock}`;
 
         const result = await dispatchInboundMessageWithDispatcher({
           ctx: {
@@ -317,16 +291,8 @@ function register(api: PluginAPI): void {
 
     /**
      * Initialize and start the calendar scheduler.
-     *
-     * Idempotent — `gateway_start` may fire once per `register()` invocation
-     * (the host calls `register` per agent), and we only want one set of
-     * sync/check intervals across the whole process.
      */
     function startCalendarScheduler(): void {
-      if (calendarScheduler) {
-        logger.info('Calendar scheduler already started, skipping duplicate gateway_start');
-        return;
-      }
       const live = resolveConfig();
 
       // Create bridge client (claw-instance level, not per-agent)

plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harbor-forge-plugin",
-  "version": "0.3.4",
+  "version": "0.3.2",
   "description": "OpenClaw plugin for HarborForge monitor bridge and CLI integration",
   "type": "module",
   "main": "dist/index.js",