feat(plugin): PLG-CAL-001 - define Calendar heartbeat request/response format

- Add plugin/calendar/types.ts: TypeScript interfaces for heartbeat
  request/response (CalendarHeartbeatRequest/Response, CalendarSlotResponse,
  SlotAgentUpdate, all enums: SlotType, SlotStatus, EventType)
- Add plugin/calendar/calendar-bridge.ts: CalendarBridgeClient HTTP client
  with heartbeat(), updateSlot(), updateVirtualSlot(), reportAgentStatus()
- Add plugin/calendar/index.ts: module entry point exporting all public types
- Add docs/PLG-CAL-001-calendar-heartbeat-format.md: full specification
  documenting claw_identifier and agent_id determination, request/response
  shapes, error handling, and endpoint summary
- Update plugin/openclaw.plugin.json: add calendarEnabled,
  calendarHeartbeatIntervalSec, calendarApiKey config options; clarify
  identifier description as claw_identifier

Refs: HarborForge.NEXT_WAVE_DEV_DIRECTION.md §6, BE-AGT-001

plugin/openclaw.plugin.json

@@ -8,43 +8,57 @@
     "type": "object",
     "additionalProperties": false,
     "properties": {
-      "enabled": { 
-        "type": "boolean", 
+      "enabled": {
+        "type": "boolean",
         "default": true,
         "description": "Enable the HarborForge plugin"
       },
-      "backendUrl": { 
-        "type": "string", 
+      "backendUrl": {
+        "type": "string",
         "default": "https://monitor.hangman-lab.top",
-        "description": "HarborForge Monitor backend URL"
+        "description": "HarborForge backend base URL (shared by Monitor and Calendar API)"
       },
-      "identifier": { 
+      "identifier": {
         "type": "string",
-        "description": "Server identifier (auto-detected from hostname if not set)"
+        "description": "Server/claw identifier. Used as claw_identifier in Calendar heartbeat and as MonitoredServer.identifier. Auto-detected from hostname if not set."
       },
-      "apiKey": { 
+      "apiKey": {
         "type": "string",
-        "description": "API Key from HarborForge Monitor admin panel (optional but required for authentication)"
+        "description": "API Key from HarborForge Monitor admin panel (optional but required for Monitor authentication)"
       },
       "monitor_port": {
         "type": "number",
         "description": "Local port for communication between HarborForge Monitor and this plugin"
       },
-      "reportIntervalSec": { 
-        "type": "number", 
+      "reportIntervalSec": {
+        "type": "number",
         "default": 30,
         "description": "How often to report metrics (seconds)"
       },
-      "httpFallbackIntervalSec": { 
-        "type": "number", 
+      "httpFallbackIntervalSec": {
+        "type": "number",
         "default": 60,
         "description": "HTTP heartbeat interval when WS unavailable"
       },
-      "logLevel": { 
-        "type": "string", 
-        "enum": ["debug", "info", "warn", "error"], 
+      "logLevel": {
+        "type": "string",
+        "enum": ["debug", "info", "warn", "error"],
         "default": "info",
         "description": "Logging level"
+      },
+      "calendarEnabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable Calendar heartbeat integration (PLG-CAL-001). When enabled, plugin sends periodic heartbeat to /calendar/agent/heartbeat to receive pending TimeSlots."
+      },
+      "calendarHeartbeatIntervalSec": {
+        "type": "number",
+        "default": 60,
+        "description": "How often to send Calendar heartbeat to backend (seconds). Defaults to 60s (1 minute)."
+      },
+      "calendarApiKey": {
+        "type": "string",
+        "description": "API key for Calendar API authentication. If not set, uses apiKey or plugin auto-authentication via X-Agent-ID header."
       }
     }
   }