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
This commit is contained in:
261
docs/PLG-CAL-001-calendar-heartbeat-format.md
Normal file
261
docs/PLG-CAL-001-calendar-heartbeat-format.md
Normal file
@@ -0,0 +1,261 @@
|
|||||||
|
# PLG-CAL-001 — Calendar Heartbeat Format Specification
|
||||||
|
|
||||||
|
> **Task:** HarborForge OpenclawPlugin / Monitor 联动
|
||||||
|
> **Subtask:** PLG-CAL-001 — 插件侧定义 Calendar 心跳请求格式
|
||||||
|
> **Status:** ✅ Implemented (types + client + spec)
|
||||||
|
> **Date:** 2026-04-01
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This document specifies the request/response format for the Calendar heartbeat
|
||||||
|
communication between the OpenClaw HarborForge plugin and the HarborForge backend.
|
||||||
|
|
||||||
|
Heartbeat direction: **Plugin → Backend**
|
||||||
|
|
||||||
|
The plugin sends a heartbeat every minute (aligned with the existing Monitor
|
||||||
|
heartbeat interval). The backend returns today's pending TimeSlots for the agent.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. How `claw_identifier` is Determined
|
||||||
|
|
||||||
|
`claw_identifier` identifies the server/claw instance. It is the same value used
|
||||||
|
in the Monitor heartbeat system (`MonitoredServer.identifier`).
|
||||||
|
|
||||||
|
**Priority order:**
|
||||||
|
|
||||||
|
1. **`config.identifier`** — if set in the plugin config (`harbor-forge.identifier`)
|
||||||
|
2. **`os.hostname()`** — auto-detected from the machine hostname (fallback)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// In plugin/calendar/calendar-bridge.ts
|
||||||
|
const clawIdentifier = baseConfig.identifier || hostname();
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. How `agent_id` is Determined
|
||||||
|
|
||||||
|
`agent_id` is the OpenClaw agent identifier (`$AGENT_ID`).
|
||||||
|
|
||||||
|
- Set by OpenClaw at agent startup as an environment variable
|
||||||
|
- The plugin reads it via `process.env.AGENT_ID`
|
||||||
|
- Globally unique within a single OpenClaw gateway deployment
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// In plugin/index.ts (caller)
|
||||||
|
const agentId = process.env.AGENT_ID || 'unknown';
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Heartbeat Request
|
||||||
|
|
||||||
|
**Endpoint:** `GET /calendar/agent/heartbeat`
|
||||||
|
|
||||||
|
### Headers
|
||||||
|
|
||||||
|
| Header | Value | Notes |
|
||||||
|
|--------|-------|-------|
|
||||||
|
| `Content-Type` | `application/json` | Always set |
|
||||||
|
| `X-Agent-ID` | `$AGENT_ID` | OpenClaw agent identifier |
|
||||||
|
| `X-Claw-Identifier` | `claw_identifier` | Server identifier |
|
||||||
|
|
||||||
|
### Request Body (JSON)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"claw_identifier": "srv1390517",
|
||||||
|
"agent_id": "developer"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Field Definitions
|
||||||
|
|
||||||
|
| Field | Type | Source | Notes |
|
||||||
|
|-------|------|--------|-------|
|
||||||
|
| `claw_identifier` | string | Plugin config or `hostname()` | Identifies the OpenClaw server instance |
|
||||||
|
| `agent_id` | string | `process.env.AGENT_ID` | Identifies the agent session |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Heartbeat Response
|
||||||
|
|
||||||
|
### Success (HTTP 200)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"slots": [
|
||||||
|
{
|
||||||
|
"id": 42,
|
||||||
|
"virtual_id": null,
|
||||||
|
"user_id": 1,
|
||||||
|
"date": "2026-04-01",
|
||||||
|
"slot_type": "work",
|
||||||
|
"estimated_duration": 30,
|
||||||
|
"scheduled_at": "09:00:00",
|
||||||
|
"started_at": null,
|
||||||
|
"attended": false,
|
||||||
|
"actual_duration": null,
|
||||||
|
"event_type": "job",
|
||||||
|
"event_data": {
|
||||||
|
"type": "Task",
|
||||||
|
"code": "TASK-123"
|
||||||
|
},
|
||||||
|
"priority": 50,
|
||||||
|
"status": "not_started",
|
||||||
|
"plan_id": null
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"agent_status": "idle",
|
||||||
|
"message": "2 slots pending"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Field Definitions
|
||||||
|
|
||||||
|
| Field | Type | Notes |
|
||||||
|
|-------|------|-------|
|
||||||
|
| `slots` | `CalendarSlotResponse[]` | Pending slots, sorted by `priority` DESC |
|
||||||
|
| `agent_status` | `AgentStatusValue` | Current backend-observed agent status |
|
||||||
|
| `message` | string (optional) | Human-readable summary |
|
||||||
|
|
||||||
|
### `CalendarSlotResponse` Fields
|
||||||
|
|
||||||
|
| Field | Type | Notes |
|
||||||
|
|-------|------|-------|
|
||||||
|
| `id` | `number \| null` | Real slot DB id. `null` for virtual slots. |
|
||||||
|
| `virtual_id` | `string \| null` | `plan-{plan_id}-{date}`. `null` for real slots. |
|
||||||
|
| `user_id` | number | Owner HarborForge user id |
|
||||||
|
| `date` | string | ISO date `YYYY-MM-DD` |
|
||||||
|
| `slot_type` | `SlotType` | `work \| on_call \| entertainment \| system` |
|
||||||
|
| `estimated_duration` | number | Minutes (1-50) |
|
||||||
|
| `scheduled_at` | string | ISO time `HH:MM:SS` |
|
||||||
|
| `started_at` | `string \| null` | Actual start time when slot begins |
|
||||||
|
| `attended` | boolean | `true` once agent begins the slot |
|
||||||
|
| `actual_duration` | `number \| null` | Real minutes when slot finishes |
|
||||||
|
| `event_type` | `EventType \| null` | `job \| entertainment \| system_event` |
|
||||||
|
| `event_data` | object \| null | See §4a below |
|
||||||
|
| `priority` | number | 0-99, higher = more urgent |
|
||||||
|
| `status` | `SlotStatus` | `not_started \| deferred \| ...` |
|
||||||
|
| `plan_id` | `number \| null` | Source plan if materialized from SchedulePlan |
|
||||||
|
|
||||||
|
### §4a — `event_data` Shapes
|
||||||
|
|
||||||
|
**When `event_type == "job"`:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "Task",
|
||||||
|
"code": "TASK-42",
|
||||||
|
"working_sessions": ["session-id-1"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**When `event_type == "system_event"`:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"event": "ScheduleToday"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Valid events: `ScheduleToday | SummaryToday | ScheduledGatewayRestart`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Slot Update Requests (Plugin → Backend after execution)
|
||||||
|
|
||||||
|
After attending / finishing / deferring a slot, the plugin calls:
|
||||||
|
|
||||||
|
**Real slot:** `PATCH /calendar/slots/{slot_id}/agent-update`
|
||||||
|
**Virtual slot:** `PATCH /calendar/slots/virtual/{virtual_id}/agent-update`
|
||||||
|
|
||||||
|
### Headers
|
||||||
|
|
||||||
|
Same as heartbeat (see §3).
|
||||||
|
|
||||||
|
### Request Body
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ongoing",
|
||||||
|
"started_at": "09:02:31",
|
||||||
|
"actual_duration": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| Field | Type | Required | Notes |
|
||||||
|
|-------|------|----------|-------|
|
||||||
|
| `status` | `SlotStatus` | **Required** | New status after agent action |
|
||||||
|
| `started_at` | string | On attending | ISO time `HH:MM:SS` |
|
||||||
|
| `actual_duration` | number | On finishing | Real minutes |
|
||||||
|
|
||||||
|
### Status Transition Values
|
||||||
|
|
||||||
|
| Action | `status` value |
|
||||||
|
|--------|---------------|
|
||||||
|
| Agent begins slot | `ongoing` |
|
||||||
|
| Agent finishes slot | `finished` |
|
||||||
|
| Agent defers slot | `deferred` |
|
||||||
|
| Agent aborts slot | `aborted` |
|
||||||
|
| Agent pauses slot | `paused` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Backend Endpoint Summary
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | `/calendar/agent/heartbeat` | X-Agent-ID + X-Claw-Identifier | Fetch pending slots for today |
|
||||||
|
| PATCH | `/calendar/slots/{id}/agent-update` | X-Agent-ID + X-Claw-Identifier | Update real slot status |
|
||||||
|
| PATCH | `/calendar/slots/virtual/{vid}/agent-update` | X-Agent-ID + X-Claw-Identifier | Update virtual slot status |
|
||||||
|
| POST | `/calendar/agent/status` | X-Agent-ID + X-Claw-Identifier | Report agent status change |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Error Handling
|
||||||
|
|
||||||
|
- **Backend unreachable:** Plugin logs warning, returns `null` from heartbeat.
|
||||||
|
Agent continues to operate without Calendar integration.
|
||||||
|
- **Invalid credentials (401/403):** Logged as error. No retry on same interval.
|
||||||
|
- **Rate limiting (429):** Plugin should mark agent as `Exhausted` and not retry
|
||||||
|
until the `Retry-After` header indicates.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. TypeScript Reference
|
||||||
|
|
||||||
|
Full type definitions are in `plugin/calendar/types.ts`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Request
|
||||||
|
interface CalendarHeartbeatRequest {
|
||||||
|
claw_identifier: string;
|
||||||
|
agent_id: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Response
|
||||||
|
interface CalendarHeartbeatResponse {
|
||||||
|
slots: CalendarSlotResponse[];
|
||||||
|
agent_status: AgentStatusValue;
|
||||||
|
message?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Slot update
|
||||||
|
interface SlotAgentUpdate {
|
||||||
|
status: SlotStatus;
|
||||||
|
started_at?: string; // ISO time HH:MM:SS
|
||||||
|
actual_duration?: number;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Implementation Files
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `plugin/calendar/types.ts` | TypeScript interfaces for all request/response shapes |
|
||||||
|
| `plugin/calendar/calendar-bridge.ts` | `CalendarBridgeClient` HTTP client |
|
||||||
|
| `plugin/calendar/index.ts` | Module entry point |
|
||||||
|
| `docs/PLG-CAL-001-calendar-heartbeat-format.md` | This specification |
|
||||||
17
package-lock.json
generated
Normal file
17
package-lock.json
generated
Normal file
@@ -0,0 +1,17 @@
|
|||||||
|
{
|
||||||
|
"name": "harbor-forge-openclaw-plugin",
|
||||||
|
"version": "0.2.0",
|
||||||
|
"lockfileVersion": 3,
|
||||||
|
"requires": true,
|
||||||
|
"packages": {
|
||||||
|
"": {
|
||||||
|
"name": "harbor-forge-openclaw-plugin",
|
||||||
|
"version": "0.2.0",
|
||||||
|
"hasInstallScript": true,
|
||||||
|
"license": "MIT",
|
||||||
|
"engines": {
|
||||||
|
"node": ">=18.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
124
plugin/calendar/calendar-bridge.d.ts
vendored
Normal file
124
plugin/calendar/calendar-bridge.d.ts
vendored
Normal file
@@ -0,0 +1,124 @@
|
|||||||
|
/**
|
||||||
|
* HarborForge Calendar Bridge Client
|
||||||
|
*
|
||||||
|
* PLG-CAL-001: Handles HTTP communication between the OpenClaw plugin
|
||||||
|
* and the HarborForge backend for Calendar heartbeat and slot updates.
|
||||||
|
*
|
||||||
|
* Request authentication:
|
||||||
|
* • X-Agent-ID header — set to process.env.AGENT_ID
|
||||||
|
* • X-Claw-Identifier header — set to the server's claw_identifier
|
||||||
|
* (from plugin config or hostname fallback)
|
||||||
|
*
|
||||||
|
* Base URL:
|
||||||
|
* Derived from plugin config: backendUrl + "/calendar"
|
||||||
|
* Default backendUrl: "https://monitor.hangman-lab.top"
|
||||||
|
*
|
||||||
|
* Endpoints used:
|
||||||
|
* GET /calendar/agent/heartbeat — fetch pending slots
|
||||||
|
* PATCH /calendar/slots/{id}/agent-update — update real slot status
|
||||||
|
* PATCH /calendar/slots/virtual/{vid}/agent-update — update virtual slot status
|
||||||
|
*
|
||||||
|
* References:
|
||||||
|
* • NEXT_WAVE_DEV_DIRECTION.md §6.1 (Heartbeat flow)
|
||||||
|
* • HarborForge.Backend/app/services/agent_heartbeat.py (BE-AGT-001)
|
||||||
|
*/
|
||||||
|
import { CalendarHeartbeatResponse, CalendarSlotResponse, SlotAgentUpdate } from './types';
|
||||||
|
export interface CalendarBridgeConfig {
|
||||||
|
/** HarborForge backend base URL (e.g. "https://monitor.hangman-lab.top") */
|
||||||
|
backendUrl: string;
|
||||||
|
/** Server/claw identifier (from plugin config or hostname fallback) */
|
||||||
|
clawIdentifier: string;
|
||||||
|
/** OpenClaw agent ID ($AGENT_ID), set at agent startup */
|
||||||
|
agentId: string;
|
||||||
|
/** HTTP request timeout in milliseconds (default: 5000) */
|
||||||
|
timeoutMs?: number;
|
||||||
|
}
|
||||||
|
export declare class CalendarBridgeClient {
|
||||||
|
private baseUrl;
|
||||||
|
private config;
|
||||||
|
private timeoutMs;
|
||||||
|
constructor(config: CalendarBridgeConfig);
|
||||||
|
/**
|
||||||
|
* Fetch today's pending calendar slots for this agent.
|
||||||
|
*
|
||||||
|
* Heartbeat flow (§6.1):
|
||||||
|
* 1. Plugin sends heartbeat every minute
|
||||||
|
* 2. Backend returns slots where status is NotStarted or Deferred
|
||||||
|
* AND scheduled_at <= now
|
||||||
|
* 3. Plugin selects highest-priority slot (if any)
|
||||||
|
* 4. For remaining slots, plugin sets status = Deferred + priority += 1
|
||||||
|
*
|
||||||
|
* @returns CalendarHeartbeatResponse or null if the backend is unreachable
|
||||||
|
*/
|
||||||
|
heartbeat(): Promise<CalendarHeartbeatResponse | null>;
|
||||||
|
/**
|
||||||
|
* Update a real (materialized) slot's status after agent execution.
|
||||||
|
*
|
||||||
|
* Used by the plugin to report:
|
||||||
|
* - Slot attended (attended=true, started_at=now, status=Ongoing)
|
||||||
|
* - Slot finished (actual_duration set, status=Finished)
|
||||||
|
* - Slot deferred (status=Deferred, priority += 1)
|
||||||
|
* - Slot aborted (status=Aborted)
|
||||||
|
*
|
||||||
|
* @param slotId Real slot DB id
|
||||||
|
* @param update Status update payload
|
||||||
|
* @returns true on success, false on failure
|
||||||
|
*/
|
||||||
|
updateSlot(slotId: number, update: SlotAgentUpdate): Promise<boolean>;
|
||||||
|
/**
|
||||||
|
* Update a virtual (plan-generated) slot's status after agent execution.
|
||||||
|
*
|
||||||
|
* When updating a virtual slot, the backend first materializes it
|
||||||
|
* (creates a real TimeSlot row), then applies the update.
|
||||||
|
* The returned slot will have a real id on subsequent calls.
|
||||||
|
*
|
||||||
|
* @param virtualId Virtual slot id in format "plan-{plan_id}-{date}"
|
||||||
|
* @param update Status update payload
|
||||||
|
* @returns Updated CalendarSlotResponse on success, null on failure
|
||||||
|
*/
|
||||||
|
updateVirtualSlot(virtualId: string, update: SlotAgentUpdate): Promise<CalendarSlotResponse | null>;
|
||||||
|
/**
|
||||||
|
* Report the agent's current runtime status to HarborForge.
|
||||||
|
*
|
||||||
|
* Used to push agent status transitions:
|
||||||
|
* idle → busy / on_call (when starting a slot)
|
||||||
|
* busy / on_call → idle (when finishing a slot)
|
||||||
|
* → exhausted (on rate-limit / billing error, with recovery_at)
|
||||||
|
* → offline (after 2 min with no heartbeat)
|
||||||
|
*
|
||||||
|
* @param status New agent status
|
||||||
|
* @param recoveryAt ISO timestamp for expected Exhausted recovery (optional)
|
||||||
|
* @param exhaustReason "rate_limit" | "billing" (required if status=exhausted)
|
||||||
|
*/
|
||||||
|
reportAgentStatus(params: {
|
||||||
|
status: 'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline';
|
||||||
|
recoveryAt?: string;
|
||||||
|
exhaustReason?: 'rate_limit' | 'billing';
|
||||||
|
}): Promise<boolean>;
|
||||||
|
private fetchJson;
|
||||||
|
private postBoolean;
|
||||||
|
}
|
||||||
|
export interface CalendarPluginConfig {
|
||||||
|
/** Backend URL for calendar API (overrides monitor backendUrl) */
|
||||||
|
calendarBackendUrl?: string;
|
||||||
|
/** Server identifier (overrides auto-detected hostname) */
|
||||||
|
identifier?: string;
|
||||||
|
/** Agent ID from OpenClaw ($AGENT_ID) */
|
||||||
|
agentId: string;
|
||||||
|
/** HTTP timeout for calendar API calls (default: 5000) */
|
||||||
|
timeoutMs?: number;
|
||||||
|
}
|
||||||
|
/**
|
||||||
|
* Build a CalendarBridgeClient from the OpenClaw plugin API context.
|
||||||
|
*
|
||||||
|
* @param api OpenClaw plugin API (register() receives this)
|
||||||
|
* @param fallbackUrl Fallback backend URL if not configured
|
||||||
|
* @param agentId $AGENT_ID from OpenClaw environment
|
||||||
|
*/
|
||||||
|
export declare function createCalendarBridgeClient(api: {
|
||||||
|
config?: Record<string, unknown>;
|
||||||
|
logger?: {
|
||||||
|
debug?: (...args: unknown[]) => void;
|
||||||
|
};
|
||||||
|
}, fallbackUrl: string, agentId: string): CalendarBridgeClient;
|
||||||
|
//# sourceMappingURL=calendar-bridge.d.ts.map
|
||||||
1
plugin/calendar/calendar-bridge.d.ts.map
Normal file
1
plugin/calendar/calendar-bridge.d.ts.map
Normal file
@@ -0,0 +1 @@
|
|||||||
|
{"version":3,"file":"calendar-bridge.d.ts","sourceRoot":"","sources":["calendar-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAEL,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EAEhB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,EAAE,oBAAoB;IASxC;;;;;;;;;;;OAWG;IACG,SAAS,IAAI,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAwB5D;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAK3E;;;;;;;;;;OAUG;IACG,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAkBvC;;;;;;;;;;;;OAYG;IACG,iBAAiB,CAAC,MAAM,EAAE;QAC9B,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;QAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;KAC1C,GAAG,OAAO,CAAC,OAAO,CAAC;YAcN,SAAS;YAsBT,WAAW;CAsB1B;AASD,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,EAC5F,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,oBAAoB,CActB"}
|
||||||
214
plugin/calendar/calendar-bridge.js
Normal file
214
plugin/calendar/calendar-bridge.js
Normal file
@@ -0,0 +1,214 @@
|
|||||||
|
"use strict";
|
||||||
|
/**
|
||||||
|
* HarborForge Calendar Bridge Client
|
||||||
|
*
|
||||||
|
* PLG-CAL-001: Handles HTTP communication between the OpenClaw plugin
|
||||||
|
* and the HarborForge backend for Calendar heartbeat and slot updates.
|
||||||
|
*
|
||||||
|
* Request authentication:
|
||||||
|
* • X-Agent-ID header — set to process.env.AGENT_ID
|
||||||
|
* • X-Claw-Identifier header — set to the server's claw_identifier
|
||||||
|
* (from plugin config or hostname fallback)
|
||||||
|
*
|
||||||
|
* Base URL:
|
||||||
|
* Derived from plugin config: backendUrl + "/calendar"
|
||||||
|
* Default backendUrl: "https://monitor.hangman-lab.top"
|
||||||
|
*
|
||||||
|
* Endpoints used:
|
||||||
|
* GET /calendar/agent/heartbeat — fetch pending slots
|
||||||
|
* PATCH /calendar/slots/{id}/agent-update — update real slot status
|
||||||
|
* PATCH /calendar/slots/virtual/{vid}/agent-update — update virtual slot status
|
||||||
|
*
|
||||||
|
* References:
|
||||||
|
* • NEXT_WAVE_DEV_DIRECTION.md §6.1 (Heartbeat flow)
|
||||||
|
* • HarborForge.Backend/app/services/agent_heartbeat.py (BE-AGT-001)
|
||||||
|
*/
|
||||||
|
Object.defineProperty(exports, "__esModule", { value: true });
|
||||||
|
exports.CalendarBridgeClient = void 0;
|
||||||
|
exports.createCalendarBridgeClient = createCalendarBridgeClient;
|
||||||
|
class CalendarBridgeClient {
|
||||||
|
baseUrl;
|
||||||
|
config;
|
||||||
|
timeoutMs;
|
||||||
|
constructor(config) {
|
||||||
|
this.baseUrl = config.backendUrl.replace(/\/$/, ''); // strip trailing slash
|
||||||
|
this.config = {
|
||||||
|
timeoutMs: 5000,
|
||||||
|
...config,
|
||||||
|
};
|
||||||
|
this.timeoutMs = this.config.timeoutMs;
|
||||||
|
}
|
||||||
|
/**
|
||||||
|
* Fetch today's pending calendar slots for this agent.
|
||||||
|
*
|
||||||
|
* Heartbeat flow (§6.1):
|
||||||
|
* 1. Plugin sends heartbeat every minute
|
||||||
|
* 2. Backend returns slots where status is NotStarted or Deferred
|
||||||
|
* AND scheduled_at <= now
|
||||||
|
* 3. Plugin selects highest-priority slot (if any)
|
||||||
|
* 4. For remaining slots, plugin sets status = Deferred + priority += 1
|
||||||
|
*
|
||||||
|
* @returns CalendarHeartbeatResponse or null if the backend is unreachable
|
||||||
|
*/
|
||||||
|
async heartbeat() {
|
||||||
|
const url = `${this.baseUrl}/calendar/agent/heartbeat`;
|
||||||
|
const body = {
|
||||||
|
claw_identifier: this.config.clawIdentifier,
|
||||||
|
agent_id: this.config.agentId,
|
||||||
|
};
|
||||||
|
try {
|
||||||
|
const response = await this.fetchJson(url, {
|
||||||
|
method: 'GET',
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
'X-Agent-ID': this.config.agentId,
|
||||||
|
'X-Claw-Identifier': this.config.clawIdentifier,
|
||||||
|
},
|
||||||
|
body: JSON.stringify(body),
|
||||||
|
});
|
||||||
|
return response;
|
||||||
|
}
|
||||||
|
catch (err) {
|
||||||
|
// Non-fatal: backend unreachable — return null, plugin continues
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
/**
|
||||||
|
* Update a real (materialized) slot's status after agent execution.
|
||||||
|
*
|
||||||
|
* Used by the plugin to report:
|
||||||
|
* - Slot attended (attended=true, started_at=now, status=Ongoing)
|
||||||
|
* - Slot finished (actual_duration set, status=Finished)
|
||||||
|
* - Slot deferred (status=Deferred, priority += 1)
|
||||||
|
* - Slot aborted (status=Aborted)
|
||||||
|
*
|
||||||
|
* @param slotId Real slot DB id
|
||||||
|
* @param update Status update payload
|
||||||
|
* @returns true on success, false on failure
|
||||||
|
*/
|
||||||
|
async updateSlot(slotId, update) {
|
||||||
|
const url = `${this.baseUrl}/calendar/slots/${slotId}/agent-update`;
|
||||||
|
return this.postBoolean(url, update);
|
||||||
|
}
|
||||||
|
/**
|
||||||
|
* Update a virtual (plan-generated) slot's status after agent execution.
|
||||||
|
*
|
||||||
|
* When updating a virtual slot, the backend first materializes it
|
||||||
|
* (creates a real TimeSlot row), then applies the update.
|
||||||
|
* The returned slot will have a real id on subsequent calls.
|
||||||
|
*
|
||||||
|
* @param virtualId Virtual slot id in format "plan-{plan_id}-{date}"
|
||||||
|
* @param update Status update payload
|
||||||
|
* @returns Updated CalendarSlotResponse on success, null on failure
|
||||||
|
*/
|
||||||
|
async updateVirtualSlot(virtualId, update) {
|
||||||
|
const url = `${this.baseUrl}/calendar/slots/virtual/${encodeURIComponent(virtualId)}/agent-update`;
|
||||||
|
try {
|
||||||
|
const response = await this.fetchJson(url, {
|
||||||
|
method: 'PATCH',
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
'X-Agent-ID': this.config.agentId,
|
||||||
|
'X-Claw-Identifier': this.config.clawIdentifier,
|
||||||
|
},
|
||||||
|
body: JSON.stringify(update),
|
||||||
|
});
|
||||||
|
return response?.slot ?? null;
|
||||||
|
}
|
||||||
|
catch {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
/**
|
||||||
|
* Report the agent's current runtime status to HarborForge.
|
||||||
|
*
|
||||||
|
* Used to push agent status transitions:
|
||||||
|
* idle → busy / on_call (when starting a slot)
|
||||||
|
* busy / on_call → idle (when finishing a slot)
|
||||||
|
* → exhausted (on rate-limit / billing error, with recovery_at)
|
||||||
|
* → offline (after 2 min with no heartbeat)
|
||||||
|
*
|
||||||
|
* @param status New agent status
|
||||||
|
* @param recoveryAt ISO timestamp for expected Exhausted recovery (optional)
|
||||||
|
* @param exhaustReason "rate_limit" | "billing" (required if status=exhausted)
|
||||||
|
*/
|
||||||
|
async reportAgentStatus(params) {
|
||||||
|
const url = `${this.baseUrl}/calendar/agent/status`;
|
||||||
|
const body = {
|
||||||
|
agent_id: this.config.agentId,
|
||||||
|
claw_identifier: this.config.clawIdentifier,
|
||||||
|
...params,
|
||||||
|
};
|
||||||
|
return this.postBoolean(url, body);
|
||||||
|
}
|
||||||
|
// -------------------------------------------------------------------------
|
||||||
|
// Internal helpers
|
||||||
|
// -------------------------------------------------------------------------
|
||||||
|
async fetchJson(url, init) {
|
||||||
|
const controller = new AbortController();
|
||||||
|
const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
|
||||||
|
try {
|
||||||
|
const response = await fetch(url, {
|
||||||
|
...init,
|
||||||
|
signal: controller.signal,
|
||||||
|
});
|
||||||
|
clearTimeout(timeout);
|
||||||
|
if (!response.ok)
|
||||||
|
return null;
|
||||||
|
return (await response.json());
|
||||||
|
}
|
||||||
|
catch {
|
||||||
|
clearTimeout(timeout);
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
async postBoolean(url, body) {
|
||||||
|
const controller = new AbortController();
|
||||||
|
const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
|
||||||
|
try {
|
||||||
|
const response = await fetch(url, {
|
||||||
|
method: 'POST',
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
'X-Agent-ID': this.config.agentId,
|
||||||
|
'X-Claw-Identifier': this.config.clawIdentifier,
|
||||||
|
},
|
||||||
|
body: JSON.stringify(body),
|
||||||
|
signal: controller.signal,
|
||||||
|
});
|
||||||
|
clearTimeout(timeout);
|
||||||
|
return response.ok;
|
||||||
|
}
|
||||||
|
catch {
|
||||||
|
clearTimeout(timeout);
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
exports.CalendarBridgeClient = CalendarBridgeClient;
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
// Utility: build CalendarBridgeConfig from plugin API context
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
const os_1 = require("os");
|
||||||
|
const live_config_1 = require("../core/live-config");
|
||||||
|
/**
|
||||||
|
* Build a CalendarBridgeClient from the OpenClaw plugin API context.
|
||||||
|
*
|
||||||
|
* @param api OpenClaw plugin API (register() receives this)
|
||||||
|
* @param fallbackUrl Fallback backend URL if not configured
|
||||||
|
* @param agentId $AGENT_ID from OpenClaw environment
|
||||||
|
*/
|
||||||
|
function createCalendarBridgeClient(api, fallbackUrl, agentId) {
|
||||||
|
const baseConfig = (0, live_config_1.getLivePluginConfig)(api, {
|
||||||
|
backendUrl: fallbackUrl,
|
||||||
|
identifier: (0, os_1.hostname)(),
|
||||||
|
});
|
||||||
|
const clawIdentifier = baseConfig.identifier || (0, os_1.hostname)();
|
||||||
|
return new CalendarBridgeClient({
|
||||||
|
backendUrl: baseConfig.backendUrl || fallbackUrl,
|
||||||
|
clawIdentifier,
|
||||||
|
agentId,
|
||||||
|
timeoutMs: 5000,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
//# sourceMappingURL=calendar-bridge.js.map
|
||||||
1
plugin/calendar/calendar-bridge.js.map
Normal file
1
plugin/calendar/calendar-bridge.js.map
Normal file
@@ -0,0 +1 @@
|
|||||||
|
{"version":3,"file":"calendar-bridge.js","sourceRoot":"","sources":["calendar-bridge.ts"],"names":[],"mappings":"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"}
|
||||||
265
plugin/calendar/calendar-bridge.ts
Normal file
265
plugin/calendar/calendar-bridge.ts
Normal file
@@ -0,0 +1,265 @@
|
|||||||
|
/**
|
||||||
|
* HarborForge Calendar Bridge Client
|
||||||
|
*
|
||||||
|
* PLG-CAL-001: Handles HTTP communication between the OpenClaw plugin
|
||||||
|
* and the HarborForge backend for Calendar heartbeat and slot updates.
|
||||||
|
*
|
||||||
|
* Request authentication:
|
||||||
|
* • X-Agent-ID header — set to process.env.AGENT_ID
|
||||||
|
* • X-Claw-Identifier header — set to the server's claw_identifier
|
||||||
|
* (from plugin config or hostname fallback)
|
||||||
|
*
|
||||||
|
* Base URL:
|
||||||
|
* Derived from plugin config: backendUrl + "/calendar"
|
||||||
|
* Default backendUrl: "https://monitor.hangman-lab.top"
|
||||||
|
*
|
||||||
|
* Endpoints used:
|
||||||
|
* GET /calendar/agent/heartbeat — fetch pending slots
|
||||||
|
* PATCH /calendar/slots/{id}/agent-update — update real slot status
|
||||||
|
* PATCH /calendar/slots/virtual/{vid}/agent-update — update virtual slot status
|
||||||
|
*
|
||||||
|
* References:
|
||||||
|
* • NEXT_WAVE_DEV_DIRECTION.md §6.1 (Heartbeat flow)
|
||||||
|
* • HarborForge.Backend/app/services/agent_heartbeat.py (BE-AGT-001)
|
||||||
|
*/
|
||||||
|
|
||||||
|
import {
|
||||||
|
CalendarHeartbeatRequest,
|
||||||
|
CalendarHeartbeatResponse,
|
||||||
|
CalendarSlotResponse,
|
||||||
|
SlotAgentUpdate,
|
||||||
|
SlotStatus,
|
||||||
|
} from './types';
|
||||||
|
|
||||||
|
export interface CalendarBridgeConfig {
|
||||||
|
/** HarborForge backend base URL (e.g. "https://monitor.hangman-lab.top") */
|
||||||
|
backendUrl: string;
|
||||||
|
/** Server/claw identifier (from plugin config or hostname fallback) */
|
||||||
|
clawIdentifier: string;
|
||||||
|
/** OpenClaw agent ID ($AGENT_ID), set at agent startup */
|
||||||
|
agentId: string;
|
||||||
|
/** HTTP request timeout in milliseconds (default: 5000) */
|
||||||
|
timeoutMs?: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
export class CalendarBridgeClient {
|
||||||
|
private baseUrl: string;
|
||||||
|
private config: Required<CalendarBridgeConfig>;
|
||||||
|
private timeoutMs: number;
|
||||||
|
|
||||||
|
constructor(config: CalendarBridgeConfig) {
|
||||||
|
this.baseUrl = config.backendUrl.replace(/\/$/, ''); // strip trailing slash
|
||||||
|
this.config = {
|
||||||
|
timeoutMs: 5000,
|
||||||
|
...config,
|
||||||
|
};
|
||||||
|
this.timeoutMs = this.config.timeoutMs;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Fetch today's pending calendar slots for this agent.
|
||||||
|
*
|
||||||
|
* Heartbeat flow (§6.1):
|
||||||
|
* 1. Plugin sends heartbeat every minute
|
||||||
|
* 2. Backend returns slots where status is NotStarted or Deferred
|
||||||
|
* AND scheduled_at <= now
|
||||||
|
* 3. Plugin selects highest-priority slot (if any)
|
||||||
|
* 4. For remaining slots, plugin sets status = Deferred + priority += 1
|
||||||
|
*
|
||||||
|
* @returns CalendarHeartbeatResponse or null if the backend is unreachable
|
||||||
|
*/
|
||||||
|
async heartbeat(): Promise<CalendarHeartbeatResponse | null> {
|
||||||
|
const url = `${this.baseUrl}/calendar/agent/heartbeat`;
|
||||||
|
const body: CalendarHeartbeatRequest = {
|
||||||
|
claw_identifier: this.config.clawIdentifier,
|
||||||
|
agent_id: this.config.agentId,
|
||||||
|
};
|
||||||
|
|
||||||
|
try {
|
||||||
|
const response = await this.fetchJson<CalendarHeartbeatResponse>(url, {
|
||||||
|
method: 'GET',
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
'X-Agent-ID': this.config.agentId,
|
||||||
|
'X-Claw-Identifier': this.config.clawIdentifier,
|
||||||
|
},
|
||||||
|
body: JSON.stringify(body),
|
||||||
|
});
|
||||||
|
return response;
|
||||||
|
} catch (err) {
|
||||||
|
// Non-fatal: backend unreachable — return null, plugin continues
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Update a real (materialized) slot's status after agent execution.
|
||||||
|
*
|
||||||
|
* Used by the plugin to report:
|
||||||
|
* - Slot attended (attended=true, started_at=now, status=Ongoing)
|
||||||
|
* - Slot finished (actual_duration set, status=Finished)
|
||||||
|
* - Slot deferred (status=Deferred, priority += 1)
|
||||||
|
* - Slot aborted (status=Aborted)
|
||||||
|
*
|
||||||
|
* @param slotId Real slot DB id
|
||||||
|
* @param update Status update payload
|
||||||
|
* @returns true on success, false on failure
|
||||||
|
*/
|
||||||
|
async updateSlot(slotId: number, update: SlotAgentUpdate): Promise<boolean> {
|
||||||
|
const url = `${this.baseUrl}/calendar/slots/${slotId}/agent-update`;
|
||||||
|
return this.postBoolean(url, update);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Update a virtual (plan-generated) slot's status after agent execution.
|
||||||
|
*
|
||||||
|
* When updating a virtual slot, the backend first materializes it
|
||||||
|
* (creates a real TimeSlot row), then applies the update.
|
||||||
|
* The returned slot will have a real id on subsequent calls.
|
||||||
|
*
|
||||||
|
* @param virtualId Virtual slot id in format "plan-{plan_id}-{date}"
|
||||||
|
* @param update Status update payload
|
||||||
|
* @returns Updated CalendarSlotResponse on success, null on failure
|
||||||
|
*/
|
||||||
|
async updateVirtualSlot(
|
||||||
|
virtualId: string,
|
||||||
|
update: SlotAgentUpdate
|
||||||
|
): Promise<CalendarSlotResponse | null> {
|
||||||
|
const url = `${this.baseUrl}/calendar/slots/virtual/${encodeURIComponent(virtualId)}/agent-update`;
|
||||||
|
try {
|
||||||
|
const response = await this.fetchJson<{ slot: CalendarSlotResponse }>(url, {
|
||||||
|
method: 'PATCH',
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
'X-Agent-ID': this.config.agentId,
|
||||||
|
'X-Claw-Identifier': this.config.clawIdentifier,
|
||||||
|
},
|
||||||
|
body: JSON.stringify(update),
|
||||||
|
});
|
||||||
|
return response?.slot ?? null;
|
||||||
|
} catch {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Report the agent's current runtime status to HarborForge.
|
||||||
|
*
|
||||||
|
* Used to push agent status transitions:
|
||||||
|
* idle → busy / on_call (when starting a slot)
|
||||||
|
* busy / on_call → idle (when finishing a slot)
|
||||||
|
* → exhausted (on rate-limit / billing error, with recovery_at)
|
||||||
|
* → offline (after 2 min with no heartbeat)
|
||||||
|
*
|
||||||
|
* @param status New agent status
|
||||||
|
* @param recoveryAt ISO timestamp for expected Exhausted recovery (optional)
|
||||||
|
* @param exhaustReason "rate_limit" | "billing" (required if status=exhausted)
|
||||||
|
*/
|
||||||
|
async reportAgentStatus(params: {
|
||||||
|
status: 'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline';
|
||||||
|
recoveryAt?: string;
|
||||||
|
exhaustReason?: 'rate_limit' | 'billing';
|
||||||
|
}): Promise<boolean> {
|
||||||
|
const url = `${this.baseUrl}/calendar/agent/status`;
|
||||||
|
const body = {
|
||||||
|
agent_id: this.config.agentId,
|
||||||
|
claw_identifier: this.config.clawIdentifier,
|
||||||
|
...params,
|
||||||
|
};
|
||||||
|
return this.postBoolean(url, body);
|
||||||
|
}
|
||||||
|
|
||||||
|
// -------------------------------------------------------------------------
|
||||||
|
// Internal helpers
|
||||||
|
// -------------------------------------------------------------------------
|
||||||
|
|
||||||
|
private async fetchJson<T>(
|
||||||
|
url: string,
|
||||||
|
init: RequestInit
|
||||||
|
): Promise<T | null> {
|
||||||
|
const controller = new AbortController();
|
||||||
|
const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
|
||||||
|
|
||||||
|
try {
|
||||||
|
const response = await fetch(url, {
|
||||||
|
...init,
|
||||||
|
signal: controller.signal,
|
||||||
|
});
|
||||||
|
clearTimeout(timeout);
|
||||||
|
|
||||||
|
if (!response.ok) return null;
|
||||||
|
return (await response.json()) as T;
|
||||||
|
} catch {
|
||||||
|
clearTimeout(timeout);
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private async postBoolean(url: string, body: unknown): Promise<boolean> {
|
||||||
|
const controller = new AbortController();
|
||||||
|
const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
|
||||||
|
|
||||||
|
try {
|
||||||
|
const response = await fetch(url, {
|
||||||
|
method: 'POST',
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
'X-Agent-ID': this.config.agentId,
|
||||||
|
'X-Claw-Identifier': this.config.clawIdentifier,
|
||||||
|
},
|
||||||
|
body: JSON.stringify(body),
|
||||||
|
signal: controller.signal,
|
||||||
|
});
|
||||||
|
clearTimeout(timeout);
|
||||||
|
return response.ok;
|
||||||
|
} catch {
|
||||||
|
clearTimeout(timeout);
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
// Utility: build CalendarBridgeConfig from plugin API context
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
import { hostname } from 'os';
|
||||||
|
import { getLivePluginConfig, type HarborForgeMonitorConfig } from '../core/live-config';
|
||||||
|
|
||||||
|
export interface CalendarPluginConfig {
|
||||||
|
/** Backend URL for calendar API (overrides monitor backendUrl) */
|
||||||
|
calendarBackendUrl?: string;
|
||||||
|
/** Server identifier (overrides auto-detected hostname) */
|
||||||
|
identifier?: string;
|
||||||
|
/** Agent ID from OpenClaw ($AGENT_ID) */
|
||||||
|
agentId: string;
|
||||||
|
/** HTTP timeout for calendar API calls (default: 5000) */
|
||||||
|
timeoutMs?: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Build a CalendarBridgeClient from the OpenClaw plugin API context.
|
||||||
|
*
|
||||||
|
* @param api OpenClaw plugin API (register() receives this)
|
||||||
|
* @param fallbackUrl Fallback backend URL if not configured
|
||||||
|
* @param agentId $AGENT_ID from OpenClaw environment
|
||||||
|
*/
|
||||||
|
export function createCalendarBridgeClient(
|
||||||
|
api: { config?: Record<string, unknown>; logger?: { debug?: (...args: unknown[]) => void } },
|
||||||
|
fallbackUrl: string,
|
||||||
|
agentId: string
|
||||||
|
): CalendarBridgeClient {
|
||||||
|
const baseConfig = getLivePluginConfig(api, {
|
||||||
|
backendUrl: fallbackUrl,
|
||||||
|
identifier: hostname(),
|
||||||
|
} as HarborForgeMonitorConfig) as HarborForgeMonitorConfig;
|
||||||
|
|
||||||
|
const clawIdentifier = baseConfig.identifier || hostname();
|
||||||
|
|
||||||
|
return new CalendarBridgeClient({
|
||||||
|
backendUrl: baseConfig.backendUrl || fallbackUrl,
|
||||||
|
clawIdentifier,
|
||||||
|
agentId,
|
||||||
|
timeoutMs: 5000,
|
||||||
|
});
|
||||||
|
}
|
||||||
23
plugin/calendar/index.d.ts
vendored
Normal file
23
plugin/calendar/index.d.ts
vendored
Normal file
@@ -0,0 +1,23 @@
|
|||||||
|
/**
|
||||||
|
* HarborForge Calendar — Plugin Module
|
||||||
|
*
|
||||||
|
* PLG-CAL-001: Calendar heartbeat request/response format definition.
|
||||||
|
*
|
||||||
|
* Exports:
|
||||||
|
* • Types for heartbeat request/response and slot update
|
||||||
|
* • CalendarBridgeClient — HTTP client for backend communication
|
||||||
|
* • createCalendarBridgeClient — factory from plugin API context
|
||||||
|
*
|
||||||
|
* Usage in plugin/index.ts:
|
||||||
|
* import { createCalendarBridgeClient } from './calendar';
|
||||||
|
*
|
||||||
|
* const agentId = process.env.AGENT_ID || 'unknown';
|
||||||
|
* const calendar = createCalendarBridgeClient(api, 'https://monitor.hangman-lab.top', agentId);
|
||||||
|
*
|
||||||
|
* // Inside gateway_start or heartbeat tick:
|
||||||
|
* const result = await calendar.heartbeat();
|
||||||
|
* if (result?.slots.length) { /* handle pending slots /\ }
|
||||||
|
*/
|
||||||
|
export * from './types';
|
||||||
|
export * from './calendar-bridge';
|
||||||
|
//# sourceMappingURL=index.d.ts.map
|
||||||
1
plugin/calendar/index.d.ts.map
Normal file
1
plugin/calendar/index.d.ts.map
Normal file
@@ -0,0 +1 @@
|
|||||||
|
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC"}
|
||||||
39
plugin/calendar/index.js
Normal file
39
plugin/calendar/index.js
Normal file
@@ -0,0 +1,39 @@
|
|||||||
|
"use strict";
|
||||||
|
/**
|
||||||
|
* HarborForge Calendar — Plugin Module
|
||||||
|
*
|
||||||
|
* PLG-CAL-001: Calendar heartbeat request/response format definition.
|
||||||
|
*
|
||||||
|
* Exports:
|
||||||
|
* • Types for heartbeat request/response and slot update
|
||||||
|
* • CalendarBridgeClient — HTTP client for backend communication
|
||||||
|
* • createCalendarBridgeClient — factory from plugin API context
|
||||||
|
*
|
||||||
|
* Usage in plugin/index.ts:
|
||||||
|
* import { createCalendarBridgeClient } from './calendar';
|
||||||
|
*
|
||||||
|
* const agentId = process.env.AGENT_ID || 'unknown';
|
||||||
|
* const calendar = createCalendarBridgeClient(api, 'https://monitor.hangman-lab.top', agentId);
|
||||||
|
*
|
||||||
|
* // Inside gateway_start or heartbeat tick:
|
||||||
|
* const result = await calendar.heartbeat();
|
||||||
|
* if (result?.slots.length) { /* handle pending slots /\ }
|
||||||
|
*/
|
||||||
|
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
||||||
|
if (k2 === undefined) k2 = k;
|
||||||
|
var desc = Object.getOwnPropertyDescriptor(m, k);
|
||||||
|
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
||||||
|
desc = { enumerable: true, get: function() { return m[k]; } };
|
||||||
|
}
|
||||||
|
Object.defineProperty(o, k2, desc);
|
||||||
|
}) : (function(o, m, k, k2) {
|
||||||
|
if (k2 === undefined) k2 = k;
|
||||||
|
o[k2] = m[k];
|
||||||
|
}));
|
||||||
|
var __exportStar = (this && this.__exportStar) || function(m, exports) {
|
||||||
|
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
|
||||||
|
};
|
||||||
|
Object.defineProperty(exports, "__esModule", { value: true });
|
||||||
|
__exportStar(require("./types"), exports);
|
||||||
|
__exportStar(require("./calendar-bridge"), exports);
|
||||||
|
//# sourceMappingURL=index.js.map
|
||||||
1
plugin/calendar/index.js.map
Normal file
1
plugin/calendar/index.js.map
Normal file
@@ -0,0 +1 @@
|
|||||||
|
{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;;;;;;;;;;;;;;AAEH,0CAAwB;AACxB,oDAAkC"}
|
||||||
23
plugin/calendar/index.ts
Normal file
23
plugin/calendar/index.ts
Normal file
@@ -0,0 +1,23 @@
|
|||||||
|
/**
|
||||||
|
* HarborForge Calendar — Plugin Module
|
||||||
|
*
|
||||||
|
* PLG-CAL-001: Calendar heartbeat request/response format definition.
|
||||||
|
*
|
||||||
|
* Exports:
|
||||||
|
* • Types for heartbeat request/response and slot update
|
||||||
|
* • CalendarBridgeClient — HTTP client for backend communication
|
||||||
|
* • createCalendarBridgeClient — factory from plugin API context
|
||||||
|
*
|
||||||
|
* Usage in plugin/index.ts:
|
||||||
|
* import { createCalendarBridgeClient } from './calendar';
|
||||||
|
*
|
||||||
|
* const agentId = process.env.AGENT_ID || 'unknown';
|
||||||
|
* const calendar = createCalendarBridgeClient(api, 'https://monitor.hangman-lab.top', agentId);
|
||||||
|
*
|
||||||
|
* // Inside gateway_start or heartbeat tick:
|
||||||
|
* const result = await calendar.heartbeat();
|
||||||
|
* if (result?.slots.length) { /* handle pending slots /\ }
|
||||||
|
*/
|
||||||
|
|
||||||
|
export * from './types';
|
||||||
|
export * from './calendar-bridge';
|
||||||
171
plugin/calendar/types.d.ts
vendored
Normal file
171
plugin/calendar/types.d.ts
vendored
Normal file
@@ -0,0 +1,171 @@
|
|||||||
|
/**
|
||||||
|
* HarborForge Calendar — Plugin-side type definitions
|
||||||
|
*
|
||||||
|
* PLG-CAL-001: Define the Calendar heartbeat request/response format
|
||||||
|
* between the OpenClaw plugin and HarborForge backend.
|
||||||
|
*
|
||||||
|
* Request flow (plugin → backend):
|
||||||
|
* POST /calendar/agent/heartbeat
|
||||||
|
* Headers:
|
||||||
|
* X-Agent-ID: <agent_id> — OpenClaw $AGENT_ID of the calling agent
|
||||||
|
* X-Claw-Identifier: <identifier> — HarborForge server identifier
|
||||||
|
* Body (JSON):
|
||||||
|
* { "claw_identifier": "...", "agent_id": "..." }
|
||||||
|
*
|
||||||
|
* Response flow (backend → plugin):
|
||||||
|
* Returns list of TimeSlots pending execution for today.
|
||||||
|
* The plugin uses slot.id / slot.virtual_id to update slot status
|
||||||
|
* via subsequent API calls.
|
||||||
|
*
|
||||||
|
* References:
|
||||||
|
* • NEXT_WAVE_DEV_DIRECTION.md §6 (Agent wakeup mechanism)
|
||||||
|
* • HarborForge.Backend/app/models/calendar.py — TimeSlot DB model
|
||||||
|
* • HarborForge.Backend/app/schemas/calendar.py — TimeSlot schemas
|
||||||
|
* • HarborForge.Backend/app/services/agent_heartbeat.py — BE-AGT-001
|
||||||
|
*/
|
||||||
|
/** Slot type — mirrors backend SlotType enum */
|
||||||
|
export declare enum SlotType {
|
||||||
|
WORK = "work",
|
||||||
|
ON_CALL = "on_call",
|
||||||
|
ENTERTAINMENT = "entertainment",
|
||||||
|
SYSTEM = "system"
|
||||||
|
}
|
||||||
|
/** Slot lifecycle status — mirrors backend SlotStatus enum */
|
||||||
|
export declare enum SlotStatus {
|
||||||
|
NOT_STARTED = "not_started",
|
||||||
|
ONGOING = "ongoing",
|
||||||
|
DEFERRED = "deferred",
|
||||||
|
SKIPPED = "skipped",
|
||||||
|
PAUSED = "paused",
|
||||||
|
FINISHED = "finished",
|
||||||
|
ABORTED = "aborted"
|
||||||
|
}
|
||||||
|
/** High-level event category — mirrors backend EventType enum */
|
||||||
|
export declare enum EventType {
|
||||||
|
JOB = "job",
|
||||||
|
ENTERTAINMENT = "entertainment",
|
||||||
|
SYSTEM_EVENT = "system_event"
|
||||||
|
}
|
||||||
|
/**
|
||||||
|
* Calendar heartbeat request body sent by the plugin to HarborForge backend.
|
||||||
|
*
|
||||||
|
* How claw_identifier is determined:
|
||||||
|
* 1. Read from plugin config: `config.backendUrl` is the base URL.
|
||||||
|
* 2. If not set, fall back to `os.hostname()` (plugin machine hostname).
|
||||||
|
*
|
||||||
|
* How agent_id is determined:
|
||||||
|
* - Read from OpenClaw environment variable: `process.env.AGENT_ID`
|
||||||
|
* - This is set by OpenClaw at agent startup and uniquely identifies
|
||||||
|
* the running agent instance within a single OpenClaw gateway.
|
||||||
|
*/
|
||||||
|
export interface CalendarHeartbeatRequest {
|
||||||
|
/** HarborForge server/claw identifier (matches MonitoredServer.identifier) */
|
||||||
|
claw_identifier: string;
|
||||||
|
/** OpenClaw agent ID ($AGENT_ID) for this agent session */
|
||||||
|
agent_id: string;
|
||||||
|
}
|
||||||
|
/**
|
||||||
|
* A single calendar slot returned in the heartbeat response.
|
||||||
|
*
|
||||||
|
* For **real** (materialized) slots: `id` is set, `virtual_id` is null.
|
||||||
|
* For **virtual** (plan-generated) slots: `id` is null, `virtual_id`
|
||||||
|
* is the `plan-{plan_id}-{date}` identifier.
|
||||||
|
*
|
||||||
|
* Key fields the plugin uses:
|
||||||
|
* - `id` / `virtual_id` — to update slot status after execution
|
||||||
|
* - `event_type` — to determine what action to take
|
||||||
|
* - `event_data` — job details / system event type
|
||||||
|
* - `slot_type` — work vs on_call (affects agent status transition)
|
||||||
|
* - `scheduled_at` — planned start time (HH:MM:SS)
|
||||||
|
* - `estimated_duration` — expected minutes (for time-tracking)
|
||||||
|
* - `priority` — for multi-slot competition logic
|
||||||
|
* - `status` — current status (NotStarted / Deferred)
|
||||||
|
*/
|
||||||
|
export interface CalendarSlotResponse {
|
||||||
|
/** Real slot DB id. Null for virtual slots. */
|
||||||
|
id: number | null;
|
||||||
|
/** Virtual slot id (plan-{plan_id}-{date}). Null for real slots. */
|
||||||
|
virtual_id: string | null;
|
||||||
|
/** Owner user id */
|
||||||
|
user_id: number;
|
||||||
|
/** Calendar date */
|
||||||
|
date: string;
|
||||||
|
/** Slot type */
|
||||||
|
slot_type: SlotType;
|
||||||
|
/** Estimated duration in minutes (1-50) */
|
||||||
|
estimated_duration: number;
|
||||||
|
/** Planned start time (ISO time string: "HH:MM:SS") */
|
||||||
|
scheduled_at: string;
|
||||||
|
/** Actual start time, set when slot begins (null until started) */
|
||||||
|
started_at: string | null;
|
||||||
|
/** Whether the slot has been attended */
|
||||||
|
attended: boolean;
|
||||||
|
/** Actual duration in minutes (set when slot finishes) */
|
||||||
|
actual_duration: number | null;
|
||||||
|
/** Event category */
|
||||||
|
event_type: EventType | null;
|
||||||
|
/** Event details JSON — structure depends on event_type (see below) */
|
||||||
|
event_data: CalendarEventData | null;
|
||||||
|
/** Priority 0-99, higher = more urgent */
|
||||||
|
priority: number;
|
||||||
|
/** Current lifecycle status */
|
||||||
|
status: SlotStatus;
|
||||||
|
/** Source plan id if materialized from a SchedulePlan; null otherwise */
|
||||||
|
plan_id: number | null;
|
||||||
|
}
|
||||||
|
/**
|
||||||
|
* Event data stored inside CalendarSlotResponse.event_data.
|
||||||
|
* The shape depends on event_type.
|
||||||
|
*
|
||||||
|
* When event_type == "job":
|
||||||
|
* { "type": "Task|Support|Meeting|Essential", "code": "TASK-42", "working_sessions": ["..."] }
|
||||||
|
*
|
||||||
|
* When event_type == "system_event":
|
||||||
|
* { "event": "ScheduleToday|SummaryToday|ScheduledGatewayRestart" }
|
||||||
|
*
|
||||||
|
* When event_type == "entertainment":
|
||||||
|
* { /* TBD /\ }
|
||||||
|
*/
|
||||||
|
export interface CalendarEventDataJob {
|
||||||
|
type: 'Task' | 'Support' | 'Meeting' | 'Essential';
|
||||||
|
code: string;
|
||||||
|
working_sessions?: string[];
|
||||||
|
}
|
||||||
|
export interface CalendarEventDataSystemEvent {
|
||||||
|
event: 'ScheduleToday' | 'SummaryToday' | 'ScheduledGatewayRestart';
|
||||||
|
}
|
||||||
|
export type CalendarEventData = CalendarEventDataJob | CalendarEventDataSystemEvent | Record<string, any>;
|
||||||
|
/**
|
||||||
|
* Full heartbeat response returned by GET /calendar/agent/heartbeat
|
||||||
|
*
|
||||||
|
* Fields:
|
||||||
|
* slots — list of pending TimeSlots for today (sorted by priority desc)
|
||||||
|
* agent_status — current agent status from the backend's perspective
|
||||||
|
* (idle | on_call | busy | exhausted | offline)
|
||||||
|
*/
|
||||||
|
export interface CalendarHeartbeatResponse {
|
||||||
|
/** Pending slots for today — sorted by priority descending */
|
||||||
|
slots: CalendarSlotResponse[];
|
||||||
|
/** Current agent status in HarborForge */
|
||||||
|
agent_status: AgentStatusValue;
|
||||||
|
/** Human-readable message (optional) */
|
||||||
|
message?: string;
|
||||||
|
}
|
||||||
|
/** Agent status values — mirrors backend AgentStatus enum */
|
||||||
|
export type AgentStatusValue = 'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline';
|
||||||
|
/**
|
||||||
|
* Request body for updating a real slot's status after agent execution.
|
||||||
|
* Called by the plugin after attending / finishing / deferring a slot.
|
||||||
|
*
|
||||||
|
* Endpoint: PATCH /calendar/slots/{slot_id}/agent-update
|
||||||
|
* (Plugin-facing variant that bypasses some user-level guards)
|
||||||
|
*/
|
||||||
|
export interface SlotAgentUpdate {
|
||||||
|
/** New status to set */
|
||||||
|
status: SlotStatus;
|
||||||
|
/** Actual start time (ISO time string HH:MM:SS), required when attending */
|
||||||
|
started_at?: string;
|
||||||
|
/** Actual duration in minutes, set when finishing */
|
||||||
|
actual_duration?: number;
|
||||||
|
}
|
||||||
|
//# sourceMappingURL=types.d.ts.map
|
||||||
1
plugin/calendar/types.d.ts.map
Normal file
1
plugin/calendar/types.d.ts.map
Normal file
@@ -0,0 +1 @@
|
|||||||
|
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,gDAAgD;AAChD,oBAAY,QAAQ;IAClB,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,aAAa,kBAAkB;IAC/B,MAAM,WAAW;CAClB;AAED,8DAA8D;AAC9D,oBAAY,UAAU;IACpB,WAAW,gBAAgB;IAC3B,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,OAAO,YAAY;CACpB;AAED,iEAAiE;AACjE,oBAAY,SAAS;IACnB,GAAG,QAAQ;IACX,aAAa,kBAAkB;IAC/B,YAAY,iBAAiB;CAC9B;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,oEAAoE;IACpE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB;IAChB,SAAS,EAAE,QAAQ,CAAC;IACpB,2CAA2C;IAC3C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,qBAAqB;IACrB,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,uEAAuE;IACvE,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACrC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,yEAAyE;IACzE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,eAAe,GAAG,cAAc,GAAG,yBAAyB,CAAC;CACrE;AAGD,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,GAAG,4BAA4B,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE1G;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,8DAA8D;IAC9D,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,0CAA0C;IAC1C,YAAY,EAAE,gBAAgB,CAAC;IAC/B,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAMrF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B"}
|
||||||
58
plugin/calendar/types.js
Normal file
58
plugin/calendar/types.js
Normal file
@@ -0,0 +1,58 @@
|
|||||||
|
"use strict";
|
||||||
|
/**
|
||||||
|
* HarborForge Calendar — Plugin-side type definitions
|
||||||
|
*
|
||||||
|
* PLG-CAL-001: Define the Calendar heartbeat request/response format
|
||||||
|
* between the OpenClaw plugin and HarborForge backend.
|
||||||
|
*
|
||||||
|
* Request flow (plugin → backend):
|
||||||
|
* POST /calendar/agent/heartbeat
|
||||||
|
* Headers:
|
||||||
|
* X-Agent-ID: <agent_id> — OpenClaw $AGENT_ID of the calling agent
|
||||||
|
* X-Claw-Identifier: <identifier> — HarborForge server identifier
|
||||||
|
* Body (JSON):
|
||||||
|
* { "claw_identifier": "...", "agent_id": "..." }
|
||||||
|
*
|
||||||
|
* Response flow (backend → plugin):
|
||||||
|
* Returns list of TimeSlots pending execution for today.
|
||||||
|
* The plugin uses slot.id / slot.virtual_id to update slot status
|
||||||
|
* via subsequent API calls.
|
||||||
|
*
|
||||||
|
* References:
|
||||||
|
* • NEXT_WAVE_DEV_DIRECTION.md §6 (Agent wakeup mechanism)
|
||||||
|
* • HarborForge.Backend/app/models/calendar.py — TimeSlot DB model
|
||||||
|
* • HarborForge.Backend/app/schemas/calendar.py — TimeSlot schemas
|
||||||
|
* • HarborForge.Backend/app/services/agent_heartbeat.py — BE-AGT-001
|
||||||
|
*/
|
||||||
|
Object.defineProperty(exports, "__esModule", { value: true });
|
||||||
|
exports.EventType = exports.SlotStatus = exports.SlotType = void 0;
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
// Enums (mirror backend enums)
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
/** Slot type — mirrors backend SlotType enum */
|
||||||
|
var SlotType;
|
||||||
|
(function (SlotType) {
|
||||||
|
SlotType["WORK"] = "work";
|
||||||
|
SlotType["ON_CALL"] = "on_call";
|
||||||
|
SlotType["ENTERTAINMENT"] = "entertainment";
|
||||||
|
SlotType["SYSTEM"] = "system";
|
||||||
|
})(SlotType || (exports.SlotType = SlotType = {}));
|
||||||
|
/** Slot lifecycle status — mirrors backend SlotStatus enum */
|
||||||
|
var SlotStatus;
|
||||||
|
(function (SlotStatus) {
|
||||||
|
SlotStatus["NOT_STARTED"] = "not_started";
|
||||||
|
SlotStatus["ONGOING"] = "ongoing";
|
||||||
|
SlotStatus["DEFERRED"] = "deferred";
|
||||||
|
SlotStatus["SKIPPED"] = "skipped";
|
||||||
|
SlotStatus["PAUSED"] = "paused";
|
||||||
|
SlotStatus["FINISHED"] = "finished";
|
||||||
|
SlotStatus["ABORTED"] = "aborted";
|
||||||
|
})(SlotStatus || (exports.SlotStatus = SlotStatus = {}));
|
||||||
|
/** High-level event category — mirrors backend EventType enum */
|
||||||
|
var EventType;
|
||||||
|
(function (EventType) {
|
||||||
|
EventType["JOB"] = "job";
|
||||||
|
EventType["ENTERTAINMENT"] = "entertainment";
|
||||||
|
EventType["SYSTEM_EVENT"] = "system_event";
|
||||||
|
})(EventType || (exports.EventType = EventType = {}));
|
||||||
|
//# sourceMappingURL=types.js.map
|
||||||
1
plugin/calendar/types.js.map
Normal file
1
plugin/calendar/types.js.map
Normal file
@@ -0,0 +1 @@
|
|||||||
|
{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAEH,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E,gDAAgD;AAChD,IAAY,QAKX;AALD,WAAY,QAAQ;IAClB,yBAAa,CAAA;IACb,+BAAmB,CAAA;IACnB,2CAA+B,CAAA;IAC/B,6BAAiB,CAAA;AACnB,CAAC,EALW,QAAQ,wBAAR,QAAQ,QAKnB;AAED,8DAA8D;AAC9D,IAAY,UAQX;AARD,WAAY,UAAU;IACpB,yCAA2B,CAAA;IAC3B,iCAAmB,CAAA;IACnB,mCAAqB,CAAA;IACrB,iCAAmB,CAAA;IACnB,+BAAiB,CAAA;IACjB,mCAAqB,CAAA;IACrB,iCAAmB,CAAA;AACrB,CAAC,EARW,UAAU,0BAAV,UAAU,QAQrB;AAED,iEAAiE;AACjE,IAAY,SAIX;AAJD,WAAY,SAAS;IACnB,wBAAW,CAAA;IACX,4CAA+B,CAAA;IAC/B,0CAA6B,CAAA;AAC/B,CAAC,EAJW,SAAS,yBAAT,SAAS,QAIpB"}
|
||||||
198
plugin/calendar/types.ts
Normal file
198
plugin/calendar/types.ts
Normal file
@@ -0,0 +1,198 @@
|
|||||||
|
/**
|
||||||
|
* HarborForge Calendar — Plugin-side type definitions
|
||||||
|
*
|
||||||
|
* PLG-CAL-001: Define the Calendar heartbeat request/response format
|
||||||
|
* between the OpenClaw plugin and HarborForge backend.
|
||||||
|
*
|
||||||
|
* Request flow (plugin → backend):
|
||||||
|
* POST /calendar/agent/heartbeat
|
||||||
|
* Headers:
|
||||||
|
* X-Agent-ID: <agent_id> — OpenClaw $AGENT_ID of the calling agent
|
||||||
|
* X-Claw-Identifier: <identifier> — HarborForge server identifier
|
||||||
|
* Body (JSON):
|
||||||
|
* { "claw_identifier": "...", "agent_id": "..." }
|
||||||
|
*
|
||||||
|
* Response flow (backend → plugin):
|
||||||
|
* Returns list of TimeSlots pending execution for today.
|
||||||
|
* The plugin uses slot.id / slot.virtual_id to update slot status
|
||||||
|
* via subsequent API calls.
|
||||||
|
*
|
||||||
|
* References:
|
||||||
|
* • NEXT_WAVE_DEV_DIRECTION.md §6 (Agent wakeup mechanism)
|
||||||
|
* • HarborForge.Backend/app/models/calendar.py — TimeSlot DB model
|
||||||
|
* • HarborForge.Backend/app/schemas/calendar.py — TimeSlot schemas
|
||||||
|
* • HarborForge.Backend/app/services/agent_heartbeat.py — BE-AGT-001
|
||||||
|
*/
|
||||||
|
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
// Enums (mirror backend enums)
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
/** Slot type — mirrors backend SlotType enum */
|
||||||
|
export enum SlotType {
|
||||||
|
WORK = 'work',
|
||||||
|
ON_CALL = 'on_call',
|
||||||
|
ENTERTAINMENT = 'entertainment',
|
||||||
|
SYSTEM = 'system',
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Slot lifecycle status — mirrors backend SlotStatus enum */
|
||||||
|
export enum SlotStatus {
|
||||||
|
NOT_STARTED = 'not_started',
|
||||||
|
ONGOING = 'ongoing',
|
||||||
|
DEFERRED = 'deferred',
|
||||||
|
SKIPPED = 'skipped',
|
||||||
|
PAUSED = 'paused',
|
||||||
|
FINISHED = 'finished',
|
||||||
|
ABORTED = 'aborted',
|
||||||
|
}
|
||||||
|
|
||||||
|
/** High-level event category — mirrors backend EventType enum */
|
||||||
|
export enum EventType {
|
||||||
|
JOB = 'job',
|
||||||
|
ENTERTAINMENT = 'entertainment',
|
||||||
|
SYSTEM_EVENT = 'system_event',
|
||||||
|
}
|
||||||
|
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
// Request types
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Calendar heartbeat request body sent by the plugin to HarborForge backend.
|
||||||
|
*
|
||||||
|
* How claw_identifier is determined:
|
||||||
|
* 1. Read from plugin config: `config.backendUrl` is the base URL.
|
||||||
|
* 2. If not set, fall back to `os.hostname()` (plugin machine hostname).
|
||||||
|
*
|
||||||
|
* How agent_id is determined:
|
||||||
|
* - Read from OpenClaw environment variable: `process.env.AGENT_ID`
|
||||||
|
* - This is set by OpenClaw at agent startup and uniquely identifies
|
||||||
|
* the running agent instance within a single OpenClaw gateway.
|
||||||
|
*/
|
||||||
|
export interface CalendarHeartbeatRequest {
|
||||||
|
/** HarborForge server/claw identifier (matches MonitoredServer.identifier) */
|
||||||
|
claw_identifier: string;
|
||||||
|
/** OpenClaw agent ID ($AGENT_ID) for this agent session */
|
||||||
|
agent_id: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
// Response types
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A single calendar slot returned in the heartbeat response.
|
||||||
|
*
|
||||||
|
* For **real** (materialized) slots: `id` is set, `virtual_id` is null.
|
||||||
|
* For **virtual** (plan-generated) slots: `id` is null, `virtual_id`
|
||||||
|
* is the `plan-{plan_id}-{date}` identifier.
|
||||||
|
*
|
||||||
|
* Key fields the plugin uses:
|
||||||
|
* - `id` / `virtual_id` — to update slot status after execution
|
||||||
|
* - `event_type` — to determine what action to take
|
||||||
|
* - `event_data` — job details / system event type
|
||||||
|
* - `slot_type` — work vs on_call (affects agent status transition)
|
||||||
|
* - `scheduled_at` — planned start time (HH:MM:SS)
|
||||||
|
* - `estimated_duration` — expected minutes (for time-tracking)
|
||||||
|
* - `priority` — for multi-slot competition logic
|
||||||
|
* - `status` — current status (NotStarted / Deferred)
|
||||||
|
*/
|
||||||
|
export interface CalendarSlotResponse {
|
||||||
|
/** Real slot DB id. Null for virtual slots. */
|
||||||
|
id: number | null;
|
||||||
|
/** Virtual slot id (plan-{plan_id}-{date}). Null for real slots. */
|
||||||
|
virtual_id: string | null;
|
||||||
|
/** Owner user id */
|
||||||
|
user_id: number;
|
||||||
|
/** Calendar date */
|
||||||
|
date: string; // ISO date string: "YYYY-MM-DD"
|
||||||
|
/** Slot type */
|
||||||
|
slot_type: SlotType;
|
||||||
|
/** Estimated duration in minutes (1-50) */
|
||||||
|
estimated_duration: number;
|
||||||
|
/** Planned start time (ISO time string: "HH:MM:SS") */
|
||||||
|
scheduled_at: string;
|
||||||
|
/** Actual start time, set when slot begins (null until started) */
|
||||||
|
started_at: string | null;
|
||||||
|
/** Whether the slot has been attended */
|
||||||
|
attended: boolean;
|
||||||
|
/** Actual duration in minutes (set when slot finishes) */
|
||||||
|
actual_duration: number | null;
|
||||||
|
/** Event category */
|
||||||
|
event_type: EventType | null;
|
||||||
|
/** Event details JSON — structure depends on event_type (see below) */
|
||||||
|
event_data: CalendarEventData | null;
|
||||||
|
/** Priority 0-99, higher = more urgent */
|
||||||
|
priority: number;
|
||||||
|
/** Current lifecycle status */
|
||||||
|
status: SlotStatus;
|
||||||
|
/** Source plan id if materialized from a SchedulePlan; null otherwise */
|
||||||
|
plan_id: number | null;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Event data stored inside CalendarSlotResponse.event_data.
|
||||||
|
* The shape depends on event_type.
|
||||||
|
*
|
||||||
|
* When event_type == "job":
|
||||||
|
* { "type": "Task|Support|Meeting|Essential", "code": "TASK-42", "working_sessions": ["..."] }
|
||||||
|
*
|
||||||
|
* When event_type == "system_event":
|
||||||
|
* { "event": "ScheduleToday|SummaryToday|ScheduledGatewayRestart" }
|
||||||
|
*
|
||||||
|
* When event_type == "entertainment":
|
||||||
|
* { /* TBD /\ }
|
||||||
|
*/
|
||||||
|
export interface CalendarEventDataJob {
|
||||||
|
type: 'Task' | 'Support' | 'Meeting' | 'Essential';
|
||||||
|
code: string;
|
||||||
|
working_sessions?: string[];
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface CalendarEventDataSystemEvent {
|
||||||
|
event: 'ScheduleToday' | 'SummaryToday' | 'ScheduledGatewayRestart';
|
||||||
|
}
|
||||||
|
|
||||||
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||||
|
export type CalendarEventData = CalendarEventDataJob | CalendarEventDataSystemEvent | Record<string, any>;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Full heartbeat response returned by GET /calendar/agent/heartbeat
|
||||||
|
*
|
||||||
|
* Fields:
|
||||||
|
* slots — list of pending TimeSlots for today (sorted by priority desc)
|
||||||
|
* agent_status — current agent status from the backend's perspective
|
||||||
|
* (idle | on_call | busy | exhausted | offline)
|
||||||
|
*/
|
||||||
|
export interface CalendarHeartbeatResponse {
|
||||||
|
/** Pending slots for today — sorted by priority descending */
|
||||||
|
slots: CalendarSlotResponse[];
|
||||||
|
/** Current agent status in HarborForge */
|
||||||
|
agent_status: AgentStatusValue;
|
||||||
|
/** Human-readable message (optional) */
|
||||||
|
message?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Agent status values — mirrors backend AgentStatus enum */
|
||||||
|
export type AgentStatusValue = 'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline';
|
||||||
|
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
// Slot update types (for post-execution status updates)
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Request body for updating a real slot's status after agent execution.
|
||||||
|
* Called by the plugin after attending / finishing / deferring a slot.
|
||||||
|
*
|
||||||
|
* Endpoint: PATCH /calendar/slots/{slot_id}/agent-update
|
||||||
|
* (Plugin-facing variant that bypasses some user-level guards)
|
||||||
|
*/
|
||||||
|
export interface SlotAgentUpdate {
|
||||||
|
/** New status to set */
|
||||||
|
status: SlotStatus;
|
||||||
|
/** Actual start time (ISO time string HH:MM:SS), required when attending */
|
||||||
|
started_at?: string;
|
||||||
|
/** Actual duration in minutes, set when finishing */
|
||||||
|
actual_duration?: number;
|
||||||
|
}
|
||||||
@@ -16,15 +16,15 @@
|
|||||||
"backendUrl": {
|
"backendUrl": {
|
||||||
"type": "string",
|
"type": "string",
|
||||||
"default": "https://monitor.hangman-lab.top",
|
"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",
|
"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",
|
"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": {
|
"monitor_port": {
|
||||||
"type": "number",
|
"type": "number",
|
||||||
@@ -45,6 +45,20 @@
|
|||||||
"enum": ["debug", "info", "warn", "error"],
|
"enum": ["debug", "info", "warn", "error"],
|
||||||
"default": "info",
|
"default": "info",
|
||||||
"description": "Logging level"
|
"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."
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user