zhi/HarborForge.OpenclawPlugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

PLG-CAL-002: Implement calendar scheduler for agent slot wakeup

Browse Source 
- Add CalendarScheduler class to manage periodic heartbeat and slot execution
- Implement agent wakeup logic when Idle and slots are pending
- Handle slot status transitions (attended, ongoing, deferred)
- Support both real and virtual slot materialization
- Add task context building for different event types (job, system, entertainment)
- Integrate scheduler into main plugin index.ts
- Add new plugin tools: harborforge_calendar_status, complete, abort
This commit is contained in:
zhi
2026-04-01 08:45:05 +00:00
parent 55d7d11a52
commit 97021f97c0
11 changed files with 1698 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

274
plugin/index.ts
View File

@@ -4,6 +4,9 @@
* Provides monitor-related tools and exposes OpenClaw metadata
* for the HarborForge Monitor bridge (via monitor_port).
*
* Also integrates with HarborForge Calendar system to wake agents
* for scheduled tasks (PLG-CAL-002).
*
* Sidecar architecture has been removed. Telemetry data is now
* served directly by the plugin when Monitor queries via the
* local monitor_port communication path.
@@ -11,6 +14,12 @@
import { hostname, freemem, totalmem, uptime, loadavg, platform } from 'os';
import { getLivePluginConfig, type HarborForgeMonitorConfig } from './core/live-config';
import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge';
import {
createCalendarBridgeClient,
createCalendarScheduler,
CalendarScheduler,
AgentWakeContext,
} from './calendar';
interface PluginAPI {
logger: {
@@ -24,6 +33,15 @@ interface PluginAPI {
pluginConfig?: Record<string, unknown>;
on: (event: string, handler: () => void) => void;
registerTool: (factory: (ctx: any) => any) => void;
/** Spawn a sub-agent with task context (OpenClaw 2.1+) */
spawn?: (options: {
agentId?: string;
task: string;
model?: string;
timeoutSeconds?: number;
}) => Promise<{ sessionId: string; status: string }>;
/** Get current agent status */
getAgentStatus?: () => Promise<{ status: string } | null>;
}
export default {
@@ -87,7 +105,7 @@ export default {
},
openclaw: {
version: api.version || 'unknown',
pluginVersion: '0.2.0',
pluginVersion: '0.3.0',
},
timestamp: new Date().toISOString(),
};
@@ -96,6 +114,9 @@ export default {
// Periodic metadata push interval handle
let metaPushInterval: ReturnType<typeof setInterval> | null = null;
// Calendar scheduler instance
let calendarScheduler: CalendarScheduler | null = null;
/**
* Push OpenClaw metadata to the Monitor bridge.
* This enriches Monitor heartbeats with OpenClaw version/plugin/agent info.
@@ -107,7 +128,7 @@ export default {
const meta: OpenClawMeta = {
version: api.version || 'unknown',
plugin_version: '0.2.0',
plugin_version: '0.3.0',
agents: [], // TODO: populate from api agent list when available
};
@@ -119,6 +140,170 @@ export default {
}
}
/**
* Get current agent status from OpenClaw.
* Falls back to querying backend if OpenClaw API unavailable.
*/
async function getAgentStatus(): Promise<'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline' | null> {
// Try OpenClaw API first (if available)
if (api.getAgentStatus) {
try {
const status = await api.getAgentStatus();
if (status?.status) {
return status.status as 'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline';
}
} catch (err) {
logger.debug('Failed to get agent status from OpenClaw API:', err);
}
}
// Fallback: query backend for agent status
const live = resolveConfig();
const agentId = process.env.AGENT_ID || 'unknown';
try {
const response = await fetch(`${live.backendUrl}/calendar/agent/status?agent_id=${agentId}`, {
headers: {
'X-Agent-ID': agentId,
'X-Claw-Identifier': live.identifier || hostname(),
},
});
if (response.ok) {
const data = await response.json();
return data.status;
}
} catch (err) {
logger.debug('Failed to get agent status from backend:', err);
}
return null;
}
/**
* Wake/spawn agent with task context for slot execution.
* This is the callback invoked by CalendarScheduler when a slot is ready.
*/
async function wakeAgent(context: AgentWakeContext): Promise<boolean> {
logger.info(`Waking agent for slot: ${context.taskDescription}`);
try {
// Method 1: Use OpenClaw spawn API if available (preferred)
if (api.spawn) {
const result = await api.spawn({
task: context.prompt,
timeoutSeconds: context.slot.estimated_duration * 60, // Convert to seconds
});
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;
} catch (err) {
logger.error('Failed to wake agent:', err);
return false;
}
}
/**
* Track session completion and update slot status accordingly.
*/
function trackSessionCompletion(sessionId: string, context: AgentWakeContext): void {
// Poll for session completion (simplified approach)
// In production, this would use webhooks or event streaming
const pollInterval = 30000; // 30 seconds
const maxDuration = context.slot.estimated_duration * 60 * 1000; // Convert to ms
const startTime = Date.now();
const poll = async () => {
if (!calendarScheduler) return;
const elapsed = Date.now() - startTime;
// Check if session is complete (would use actual API in production)
// For now, estimate completion based on duration
if (elapsed >= maxDuration) {
// Assume completion
const actualMinutes = Math.round(elapsed / 60000);
await calendarScheduler.completeCurrentSlot(actualMinutes);
return;
}
// Continue polling
setTimeout(poll, pollInterval);
};
// Start polling
setTimeout(poll, pollInterval);
}
/**
* Initialize and start the calendar scheduler.
*/
function startCalendarScheduler(): void {
const live = resolveConfig();
const agentId = process.env.AGENT_ID || 'unknown';
// Create calendar bridge client
const calendarBridge = createCalendarBridgeClient(
api,
live.backendUrl || 'https://monitor.hangman-lab.top',
agentId
);
// Create and start scheduler
calendarScheduler = createCalendarScheduler({
bridge: calendarBridge,
getAgentStatus,
wakeAgent,
logger,
heartbeatIntervalMs: 60000, // 1 minute
debug: live.logLevel === 'debug',
});
calendarScheduler.start();
logger.info('Calendar scheduler started');
}
/**
* Stop the calendar scheduler.
*/
function stopCalendarScheduler(): void {
if (calendarScheduler) {
calendarScheduler.stop();
calendarScheduler = null;
logger.info('Calendar scheduler stopped');
}
}
api.on('gateway_start', () => {
logger.info('HarborForge plugin active');
@@ -135,14 +320,22 @@ export default {
() => pushMetaToMonitor(),
intervalSec * 1000,
);
// Start calendar scheduler (delayed to let everything initialize)
if (live.enabled !== false) {
setTimeout(() => startCalendarScheduler(), 5000);
}
});
api.on('gateway_stop', () => {
logger.info('HarborForge plugin stopping');
if (metaPushInterval) {
clearInterval(metaPushInterval);
metaPushInterval = null;
}
stopCalendarScheduler();
});
// Tool: plugin status
@@ -165,6 +358,13 @@ export default {
: { connected: false, error: 'Monitor bridge unreachable' };
}
// Get calendar scheduler status
const calendarStatus = calendarScheduler ? {
running: calendarScheduler.isRunning(),
processing: calendarScheduler.isProcessing(),
currentSlot: calendarScheduler.getCurrentSlot(),
} : null;
return {
enabled: live.enabled !== false,
config: {
@@ -175,6 +375,7 @@ export default {
hasApiKey: Boolean(live.apiKey),
},
monitorBridge,
calendar: calendarStatus,
telemetry: collectTelemetry(),
};
},
@@ -220,6 +421,75 @@ export default {
},
}));
// Tool: calendar slot management
api.registerTool(() => ({
name: 'harborforge_calendar_status',
description: 'Get current calendar scheduler status and pending slots',
parameters: {
type: 'object',
properties: {},
},
async execute() {
if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' };
}
return {
running: calendarScheduler.isRunning(),
processing: calendarScheduler.isProcessing(),
currentSlot: calendarScheduler.getCurrentSlot(),
state: calendarScheduler.getState(),
};
},
}));
// Tool: complete current slot (for agent to report completion)
api.registerTool(() => ({
name: 'harborforge_calendar_complete',
description: 'Complete the current calendar slot with actual duration',
parameters: {
type: 'object',
properties: {
actualDurationMinutes: {
type: 'number',
description: 'Actual time spent on the task in minutes',
},
},
required: ['actualDurationMinutes'],
},
async execute(params: { actualDurationMinutes: number }) {
if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' };
}
await calendarScheduler.completeCurrentSlot(params.actualDurationMinutes);
return { success: true, message: 'Slot completed' };
},
}));
// Tool: abort current slot (for agent to report failure)
api.registerTool(() => ({
name: 'harborforge_calendar_abort',
description: 'Abort the current calendar slot',
parameters: {
type: 'object',
properties: {
reason: {
type: 'string',
description: 'Reason for aborting',
},
},
},
async execute(params: { reason?: string }) {
if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' };
}
await calendarScheduler.abortCurrentSlot(params.reason);
return { success: true, message: 'Slot aborted' };
},
}));
logger.info('HarborForge plugin registered (id: harbor-forge)');
},
};