8 Commits

Author SHA1 Message Date
h z
a003416e56 Merge pull request 'fix: wake dedupe + inline slot context + complete contracts.tools' (#6) from fix/wake-dedupe-and-contracts into main 2026-05-20 14:48:06 +00:00
9ba591795b fix: wake dedupe + inline slot context + complete contracts.tools
Three issues making HF→agent wakeup unusable in practice, surfaced by
DinD sim end-to-end test (recruiter agent + slot for 招募 manager task):

1. **Plugin re-woke the same slot every 30s.** The inline runCheck only
   destructured agentId from scheduleCache.getAgentsWithDueSlots() and
   dropped the slots array, then called wakeAgent without recording the
   wake. The simplified inline scheduler also never PATCHes slot status
   server-side from not_started→ongoing, so the next 30s check sees the
   slot still due and wakes again. After 4 wakes the agent's wakeup
   session was full of WAKEUP_OK noise.

   Fix: keep slots in runCheck, add an in-memory wakedSlotKeys set
   keyed by (agentId, slotId|virtual_id|scheduled_at). Dedupe on this
   set; clear it inside the sync interval (fresh wake budget per sync).
   Server-side slot transition still TODO (requires re-introducing the
   CalendarScheduler class path or PATCH /calendar/slots/.../agent-update
   here); the dedupe at least stops the wake spam.

2. **Wakeup message had no slot context.** The wakeup body just said
   'follow hf-wakeup workflow' with no slot id/event_data/task_code.
   The agent then had to call harborforge_calendar_status to learn
   anything — which itself is broken in the simplified scheduler (it
   queries a CalendarScheduler instance that never gets created).

   Fix: pass dueSlots into wakeAgent and inline the highest-priority
   slot's {slot_id, scheduled_at, priority, slot_type, event_data} as
   a JSON block in the wakeup message. The agent reads event_data.
   task_code directly and routes via workflow_lookup without any
   round-trip. Per PLG-CAL-001 docs in hf-hangman-lab SKILL.md, this
   is the documented contract; we are bringing the message in line.

3. **contracts.tools listed 5 of the 9 registered tools.** Manifest had
   harborforge_status/telemetry/monitor_telemetry/calendar_status/
   calendar_complete. Code also registers calendar_abort, calendar_pause,
   calendar_resume, harborforge_restart_status. With the new OpenClaw
   plugin host enforcement (same gotcha that bit Meridian — see
   zhi/Meridian#2), undeclared tools are silently dropped from the
   agent's tool list, so abort/pause/resume cannot be called by the
   agent. plugin doctor was emitting:
   'plugin tool is undeclared (harbor-forge): harborforge_calendar_abort'
   for each missing tool.

   Fix: add the 4 missing tool names to contracts.tools.

Also use api.config as the primary config source in wakeAgent (current
public API), falling back to runtime.config.loadConfig() for older
hosts — same pattern as the Meridian fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-20 12:02:25 +01:00
c9f61419cb Merge docs/readme-refresh into main
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-16 17:55:57 +01:00
cc807484fc docs: refresh README — accuracy pass + HarborForge platform context
Verified against current code; fixed stale/inaccurate sections and
documented previously-undocumented features/flags/endpoints. Added a
"Part of the HarborForge platform" reference and role/port.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-16 17:50:01 +01:00
operator
917cb344cf chore: track ambient openclaw-sdk.d.ts (was caught by *.d.ts ignore)
The .gitignore was set up to skip tsc's compiled .d.ts output but it also
matched the hand-written ambient declarations file added in the previous
commit. Add a negation rule so that one file is tracked.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 08:29:35 +00:00
operator
64a9c431bf chore: convert plugin to ESM and migrate to current openclaw plugin SDK
ESM conversion:
- plugin/package.json: add "type": "module".
- plugin/tsconfig.json: switch module/moduleResolution to "nodenext"; bump
  target to ES2022.
- All relative imports across plugin/ now carry .js extensions as required
  by Node ESM (nodenext module resolution).
- plugin/index.ts: replace `require('./calendar/schedule-cache')` with a
  proper top-level import; switch `from 'os'` to `from 'node:os'`.

Plugin SDK convention update:
- Wrap default export with definePluginEntry({ id, name, description,
  register }) per the current openclaw plugin authoring contract.
- Modernize plugin/openclaw.plugin.json: drop entry/version, add
  activation.onStartup so gateway_start fires for this plugin at boot,
  declare contracts.tools listing the five harborforge_* tools.
- Add a local plugin/openclaw-sdk.d.ts with ambient declarations for the
  focused subpaths (openclaw/plugin-sdk/plugin-entry,
  openclaw/plugin-sdk/core). We deliberately do NOT add openclaw as an
  npm devDependency: the installer's `npm install --omit=dev` step trips
  over openclaw's own (deeply nested) dependency graph when listed via
  file:.../openclaw, and the runtime contract is provided by the gateway
  loader anyway.
- The local PluginAPI interface is preserved (broader than the standard
  OpenClawPluginApi — it surfaces `version`/`runtime`/`spawn`); the
  register function is cast at the definePluginEntry boundary.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 08:28:58 +00:00
h z
957bcbb4a8 Merge pull request 'feat: schedule cache, workflow-aligned prompts, dispatchInbound wakeup' (#5) from zhi-2026-04-18 into main
Reviewed-on: #5
2026-05-01 07:23:25 +00:00
operator
9195dc6bd1 feat: schedule cache, workflow-aligned prompts, dispatchInbound wakeup
1. ScheduleCache: local cache of today's schedule, synced every 5 min
   from HF backend via new getDaySchedule() API

2. Wakeup prompts updated to reference daily-routine skill workflows
   (task-handson, plan-schedule, slot-complete)

3. Agent wakeup via dispatchInboundMessageWithDispatcher (in-process)
   - Same mechanism as Discord plugin
   - Creates unique session per slot: agent:{agentId}:hf-calendar:slot-{slotId}
   - No WebSocket, CLI, or cron dependency
   - Verified working on test environment

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-19 12:24:21 +00:00
15 changed files with 657 additions and 158 deletions

2
.gitignore vendored
View File

@@ -4,3 +4,5 @@ plugin/**/*.js
plugin/**/*.js.map
plugin/**/*.d.ts
plugin/**/*.d.ts.map
# Hand-written ambient declarations are tracked; only compiled .d.ts above is ignored.
!plugin/openclaw-sdk.d.ts

192
README.md
View File

@@ -1,84 +1,107 @@
# HarborForge OpenClaw Plugin
OpenClaw 插件:向 HarborForge Monitor 暴露 OpenClaw 侧元数据,并提供可选的本地桥接能力;安装时也可顺带安装 `hf` CLI
OpenClaw plugin that exposes OpenClaw-side metadata to the HarborForge Monitor, provides an optional local Monitor bridge, drives the HarborForge Calendar scheduler, and can optionally install the `hf` CLI.
## 当前状态
Part of the [HarborForge](../README.md) platform.
- 插件注册名:`harbor-forge`
- 旧 sidecar `server/` 架构已移除
- 监控桥接走本地 `monitor_port`
- 安装脚本支持 `--install-cli`
- `skills/hf/` 仅在 `--install-cli` 时一并安装
- Role: OpenClaw integration layer for HarborForge (registered plugin id: `harbor-forge`).
- Talks to the HarborForge backend (`backendUrl`, default `https://monitor.hangman-lab.top`) for Calendar APIs.
- Talks to a local HarborForge.Monitor bridge over `127.0.0.1:<monitor_port>` (no fixed default; commonly `9100`).
## 项目结构
## Current State
- Plugin registration id: `harbor-forge` (was `harborforge-monitor`)
- Plugin version: `0.2.0` (package manifests); telemetry reports `pluginVersion` `0.3.1`
- Legacy sidecar `server/` architecture removed — telemetry is served directly by the plugin
- Monitor bridge runs over the local `monitor_port`
- Calendar scheduler integration (PLG-CAL-001 / 002 / 004)
- Installer supports `--install-cli` and an optional managed Monitor (`--install-monitor`)
- `skills/hf/` is installed only with `--install-cli`
## Project Structure
```text
HarborForge.OpenclawPlugin/
├── package.json
├── README.md
├── docs/ # design notes (calendar, monitor connector)
├── plugin/
│ ├── openclaw.plugin.json
│ ├── index.ts
│ ├── openclaw.plugin.json # plugin manifest + config schema
│ ├── index.ts # plugin entry, tool registration
│ ├── tsconfig.json
│ ├── core/
│ │ ├── config.ts
│ │ ├── managed-monitor.ts
│ │ ── monitor-bridge.ts
│ │ ├── config.ts # config defaults / resolution
│ │ ├── managed-monitor.ts # optionally spawn HarborForge.Monitor
│ │ ── monitor-bridge.ts # client for the Monitor bridge
│ │ └── openclaw-agents.ts # enumerate OpenClaw agents
│ ├── calendar/ # Calendar scheduler + bridge
│ │ ├── index.ts
│ │ ├── scheduler.ts
│ │ ├── calendar-bridge.ts
│ │ └── types.ts
│ ├── hooks/
│ │ ├── gateway-start.ts
│ │ └── gateway-stop.ts
│ └── package.json
├── skills/
│ └── hf/
│ └── SKILL.md
│ └── SKILL.md # installed only with --install-cli
└── scripts/
└── install.mjs
```
## 安装
## Installation
### 普通安装
### Standard Install
```bash
node scripts/install.mjs
```
这会:
- 构建并安装 OpenClaw 插件
- 复制常规 skills
- **不会**安装 `hf` 二进制
- **不会**复制 `skills/hf/`
This will:
- Build and install the OpenClaw plugin
- Copy regular skills
- **Not** install the `hf` binary
- **Not** copy `skills/hf/`
### 安装插件 + `hf` CLI
### Plugin + `hf` CLI
```bash
node scripts/install.mjs --install-cli
```
这会额外:
- 构建 `HarborForge.Cli`
- 安装 `hf` `~/.openclaw/bin/hf`
- `chmod +x ~/.openclaw/bin/hf`
- 复制 `skills/hf/` 到 OpenClaw profile skills 目录
This additionally:
- Builds `HarborForge.Cli` (`go build ./cmd/hf`)
- Installs `hf` to `<openclaw>/bin/hf` (default `~/.openclaw/bin/hf`) and `chmod +x`
- Copies `skills/hf/` into the OpenClaw skills directory
### 常用选项
### Common Options
```bash
# 仅构建
# Build only (no install / config)
node scripts/install.mjs --build-only
# 指定 OpenClaw profile
# Install only, skip dependency checks
node scripts/install.mjs --skip-check
# Specify OpenClaw profile path (also honors OPENCLAW_PATH env)
node scripts/install.mjs --openclaw-profile-path /custom/path/.openclaw
# 详细日志
# Build and install a managed HarborForge.Monitor binary alongside the plugin
node scripts/install.mjs --install-monitor yes --monitor-branch main
# Verbose logs
node scripts/install.mjs --verbose
# 卸载
# Uninstall (plugin, config entries, hf binary, managed monitor)
node scripts/install.mjs --uninstall
```
## 配置
The installer also updates OpenClaw config (`plugins.load.paths`, `plugins.allow`, `plugins.entries.harbor-forge.enabled`) via `openclaw config`.
编辑 `~/.openclaw/openclaw.json`
## Configuration
Edit `~/.openclaw/openclaw.json`:
```json
{
@@ -94,7 +117,9 @@ node scripts/install.mjs --uninstall
"monitor_port": 9100,
"reportIntervalSec": 30,
"httpFallbackIntervalSec": 60,
"logLevel": "info"
"logLevel": "info",
"calendarEnabled": true,
"calendarHeartbeatIntervalSec": 60
}
}
}
@@ -102,51 +127,72 @@ node scripts/install.mjs --uninstall
}
```
然后重启:
Then restart:
```bash
openclaw gateway restart
```
## 配置项
## Config Options
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `enabled` | boolean | `true` | 是否启用插件 |
| `backendUrl` | string | `https://monitor.hangman-lab.top` | HarborForge Monitor 后端地址 |
| `identifier` | string | 主机名 | 服务器标识符 |
| `apiKey` | string | 无 | HarborForge Monitor 生成的服务器 API Key |
| `monitor_port` | number | 无 | 本地桥接端口;插件通过 `127.0.0.1:<monitor_port>` 与 HarborForge.Monitor 通信 |
| `reportIntervalSec` | number | `30` | 报告间隔(秒) |
| `httpFallbackIntervalSec` | number | `60` | HTTP 回退间隔(秒) |
| `logLevel` | string | `info` | 日志级别:`debug` / `info` / `warn` / `error` |
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable the plugin |
| `backendUrl` | string | `https://monitor.hangman-lab.top` | HarborForge backend base URL (Monitor + Calendar APIs) |
| `identifier` | string | hostname | Server / claw identifier |
| `apiKey` | string | (none) | Server API key from the HarborForge Monitor admin panel |
| `monitor_port` | number | (none) | Local bridge port; plugin talks to HarborForge.Monitor via `127.0.0.1:<monitor_port>` |
| `reportIntervalSec` | number | `30` | Metadata push interval (seconds) |
| `httpFallbackIntervalSec` | number | `60` | HTTP heartbeat interval when WS unavailable |
| `logLevel` | string | `info` | Log level: `debug` / `info` / `warn` / `error` |
| `calendarEnabled` | boolean | `true` | Enable Calendar scheduler integration (PLG-CAL-001) |
| `calendarHeartbeatIntervalSec` | number | `60` | Calendar heartbeat interval (seconds) |
| `calendarApiKey` | string | (none) | API key for Calendar API auth; falls back to `apiKey` / `X-Agent-ID` |
| `managedMonitor` | string | (none) | Absolute path to a HarborForge.Monitor binary; if set, gateway start/stop hooks spawn/stop it |
## 本地桥接说明
## Local Monitor Bridge
当插件配置了 `monitor_port`,并且 HarborForge.Monitor 也使用相同的 `MONITOR_PORT` 时:
When the plugin has `monitor_port` configured and HarborForge.Monitor uses the same `MONITOR_PORT`:
- Monitor `127.0.0.1:<MONITOR_PORT>` 提供本地桥接服务
- 插件可探测 `GET /health`
- 插件工具 `harborforge_monitor_telemetry` 可读取 `GET /telemetry`
- 如果桥接端口未配置或不可达,插件仍可正常运行
- Monitor serves a local bridge on `127.0.0.1:<MONITOR_PORT>`
- The plugin probes `GET /health`
- The plugin tool `harborforge_monitor_telemetry` reads `GET /telemetry`
- The plugin pushes OpenClaw metadata (version, plugin version, agents) via `POST /openclaw` on the `reportIntervalSec` cadence, enriching Monitor heartbeats
- If the bridge port is unconfigured or unreachable, the plugin still works normally
也就是说,这条链路是**可选增强**,不是插件启动或 Monitor 心跳的前置条件。
This link is an **optional enhancement**, not a precondition for the plugin to start or for Monitor heartbeats.
## 插件提供的信息
## Managed Monitor
### OpenClaw 元数据
- OpenClaw version
- plugin version
- 标识符 / 主机名
- 时间戳
If `managedMonitor` points to an installed HarborForge.Monitor binary, the `gateway_start` hook spawns it (passing `--backend-url`, `--identifier`, `--api-key`, `--monitor-port`, `--report-interval`, `--log-level` from the plugin config) and `gateway_stop` terminates it. Use `install.mjs --install-monitor yes` to build and wire this automatically.
### 系统快照
- uptime
- memory total/free/used/usagePercent
- load avg1/avg5/avg15
- platform
## Calendar Scheduler
## 开发
When `calendarEnabled` is true, on gateway start the plugin starts a Calendar scheduler that heartbeats the backend (`/calendar/agent/heartbeat`, `/calendar/agent/status`, `/calendar/agent/notify`) to receive and run scheduled TimeSlots, waking/spawning agents via the OpenClaw `spawn` API (with a notification fallback). Scheduler state is persisted to a state file; gateway restarts can be requested by the backend (PLG-CAL-004).
## Tools Provided
| Tool | Description |
|------|-------------|
| `harborforge_status` | Plugin status, resolved config, Monitor bridge health, calendar status, telemetry snapshot |
| `harborforge_telemetry` | Current system telemetry snapshot from this host |
| `harborforge_monitor_telemetry` | Query the Monitor bridge for host hardware telemetry |
| `harborforge_calendar_status` | Calendar scheduler status and current slot |
| `harborforge_calendar_complete` | Complete the current calendar slot with actual duration |
| `harborforge_calendar_abort` | Abort the current calendar slot |
| `harborforge_calendar_pause` | Pause the current calendar slot |
| `harborforge_calendar_resume` | Resume the paused calendar slot |
| `harborforge_restart_status` | Check whether a gateway restart is pending |
### Telemetry Snapshot Fields
- `identifier`, `hostname`, `platform`, `timestamp`
- `uptime`
- `memory`: `total` / `free` / `used` / `usagePercent`
- `load`: `avg1` / `avg5` / `avg15`
- `openclaw`: `version` / `pluginVersion`
## Development
```bash
cd plugin
@@ -154,14 +200,16 @@ npm install
npm run build
```
## 依赖
The build runs `tsc` and emits `dist/` (`dist/index.js` is the plugin entry).
## Dependencies
- Node.js 18+
- OpenClaw Gateway
- Go 1.20+(仅 `--install-cli` 需要)
- Go 1.20+ (only for `--install-cli` / `--install-monitor`)
## 相关提示
## Tips
- 安装 `hf` 后,建议把 `~/.openclaw/bin` 加到 `PATH`
- Agent 使用 `hf` 时,优先试 `hf --help-brief`
- 完整命令树看 `hf --help`
- After installing `hf`, add `~/.openclaw/bin` to your `PATH`
- When an agent uses `hf`, try `hf --help-brief` first
- For the full command tree, see `hf --help`

118
REFACTOR_PLAN.md Normal file
View File

@@ -0,0 +1,118 @@
# CalendarScheduler Refactor Plan (v2)
> Updated 2026-04-19 based on architecture discussion with hang
## Current Issues
1. `process.env.AGENT_ID` doesn't exist in plugins subprocess — always 'unknown'
2. Heartbeat is per-agent but should be per-claw-instance (global)
3. Scheduler only handles one agent — should manage all agents on this instance
4. wakeAgent used api.spawn (non-existent) → now uses dispatchInboundMessage (verified)
## Target Design
### Plugin State
```typescript
// Local schedule cache: { agentId → [slots] }
const schedules: Map<string, CalendarSlotResponse[]> = new Map();
```
### Sync Flow (every 5 min)
```
1. GET /calendar/sync?claw_identifier=xxx
- First call: server returns full { agentId → [slots] }
- Subsequent: server returns diff since last sync
2. Update local schedules map
3. Scan schedules for due slots:
for each agentId in schedules:
if has slot where scheduled_at <= now && status == not_started:
getAgentStatus(agentId, clawIdentifier) → busy?
if not busy → wakeAgent(agentId)
```
### Heartbeat (every 60s)
Simplified to liveness ping only:
```
POST /monitor/server/heartbeat
claw_identifier: xxx
→ server returns empty/ack
```
No slot data in heartbeat response.
### Wake Flow
```
dispatchInboundMessage:
SessionKey: agent:{agentId}:hf-wakeup
Body: "You have due slots. Follow the hf-wakeup workflow of skill hf-hangman-lab to proceed. Only reply WAKEUP_OK in this session."
Agent reads workflow → calls hf tools → sets own status to busy
```
### Agent ID Resolution
- **Sync**: agentId comes from server response (dict keys)
- **Wake**: agentId from local schedules dict key
- **Tool calls by agent**: agentId from tool ctx (same as padded-cell)
## Backend API Changes Needed
### New: GET /calendar/sync
```
GET /calendar/sync?claw_identifier=xxx
Headers: X-Claw-Identifier
Response (first call):
{
"full": true,
"schedules": {
"developer": [slot1, slot2, ...],
"operator": [slot3, ...]
},
"syncToken": "abc123"
}
Response (subsequent, with ?since=abc123):
{
"full": false,
"diff": [
{ "op": "add", "agent": "developer", "slot": {...} },
{ "op": "update", "agent": "developer", "slotId": 5, "patch": {...} },
{ "op": "remove", "agent": "operator", "slotId": 3 }
],
"syncToken": "def456"
}
```
### Existing: POST /calendar/agent/status
Keep as-is but ensure it accepts agentId + clawIdentifier as params:
```
POST /calendar/agent/status
{ agent_id, claw_identifier, status }
```
## Implementation Order
1. Backend: Add /calendar/sync endpoint
2. Plugin: Replace CalendarBridgeClient single-agent design with multi-agent
3. Plugin: Replace CalendarScheduler with new sync+check loop
4. Plugin: wakeAgent uses dispatchInboundMessage (done)
5. Plugin: Tool handlers get agentId from ctx (like padded-cell)
## Files to Change
### Backend (HarborForge.Backend)
- New route: `/calendar/sync`
- New service: schedule diff tracking per claw_identifier
### Plugin
- `plugin/calendar/calendar-bridge.ts` — remove agentId binding, add sync()
- `plugin/calendar/scheduler.ts` — rewrite to multi-agent sync+check
- `plugin/calendar/schedule-cache.ts` — already exists, adapt to multi-agent
- `plugin/index.ts` — update wakeAgent, getAgentStatus to accept agentId

View File

@@ -29,7 +29,7 @@ import {
CalendarSlotResponse,
SlotAgentUpdate,
SlotStatus,
} from './types';
} from './types.js';
export interface CalendarBridgeConfig {
/** HarborForge backend base URL (e.g. "https://monitor.hangman-lab.top") */
@@ -169,6 +169,74 @@ 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;
}
}
/**
* Sync today's schedules for all agents on this claw instance.
*
* Returns { agentId → slots[] } for all agents with matching claw_identifier.
* This is the primary data source for the multi-agent schedule cache.
*/
async syncSchedules(): Promise<{ schedules: Record<string, any[]>; date: string } | null> {
const url = `${this.baseUrl}/calendar/sync`;
try {
const response = await this.fetchJson<{ schedules: Record<string, any[]>; date: string }>(url, {
method: 'GET',
headers: {
'X-Claw-Identifier': this.config.clawIdentifier,
},
});
return response;
} catch {
return null;
}
}
/**
* Get a specific agent's status.
*
* @param agentId The agent ID to query
*/
async getAgentStatus(agentId: string): Promise<string | null> {
const url = `${this.baseUrl}/calendar/agent/status?agent_id=${encodeURIComponent(agentId)}`;
try {
const response = await this.fetchJson<{ status: string }>(url, {
method: 'GET',
headers: {
'X-Agent-ID': agentId,
'X-Claw-Identifier': this.config.clawIdentifier,
},
});
return response?.status ?? null;
} catch {
return null;
}
}
// -------------------------------------------------------------------------
// Internal helpers
// -------------------------------------------------------------------------
@@ -224,7 +292,7 @@ export class CalendarBridgeClient {
// ---------------------------------------------------------------------------
import { hostname } from 'os';
import { getPluginConfig } from '../core/config';
import { getPluginConfig } from '../core/config.js';
export interface CalendarPluginConfig {
/** Backend URL for calendar API (overrides monitor backendUrl) */

View File

@@ -13,7 +13,7 @@
* • AgentWakeContext — context passed to agent when waking
*
* Usage in plugin/index.ts:
* import { createCalendarBridgeClient, createCalendarScheduler } from './calendar';
* import { createCalendarBridgeClient, createCalendarScheduler } from './calendar.js';
*
* const agentId = process.env.AGENT_ID || 'unknown';
* const calendar = createCalendarBridgeClient(api, 'https://monitor.hangman-lab.top', agentId);
@@ -28,6 +28,7 @@
* scheduler.start();
*/
export * from './types';
export * from './calendar-bridge';
export * from './scheduler';
export * from './types.js';
export * from './calendar-bridge.js';
export * from './scheduler.js';
export * from './schedule-cache.js';

View File

@@ -0,0 +1,101 @@
/**
* Multi-agent local schedule cache.
*
* Maintains today's schedule for all agents on this claw instance.
* Synced periodically from HF backend via /calendar/sync endpoint.
*/
export interface CachedSlot {
id: number | null;
virtual_id: string | null;
slot_type: string;
estimated_duration: number;
scheduled_at: string;
status: string;
priority: number;
event_type: string | null;
event_data: Record<string, unknown> | null;
[key: string]: unknown;
}
export class MultiAgentScheduleCache {
/** { agentId → slots[] } */
private schedules: Map<string, CachedSlot[]> = new Map();
private lastSyncAt: Date | null = null;
private cachedDate: string | null = null;
/**
* Replace cache with data from /calendar/sync response.
*/
sync(date: string, schedules: Record<string, CachedSlot[]>): void {
if (this.cachedDate !== date) {
this.schedules.clear();
}
this.cachedDate = date;
for (const [agentId, slots] of Object.entries(schedules)) {
this.schedules.set(agentId, slots);
}
this.lastSyncAt = new Date();
}
/**
* Get agents that have due (overdue or current) slots.
* Returns [agentId, dueSlots[]] pairs.
*/
getAgentsWithDueSlots(now: Date): Array<{ agentId: string; slots: CachedSlot[] }> {
const results: Array<{ agentId: string; slots: CachedSlot[] }> = [];
for (const [agentId, slots] of this.schedules) {
const due = slots.filter((s) => {
if (s.status !== 'not_started' && s.status !== 'deferred') return false;
const scheduledAt = this.parseScheduledTime(s.scheduled_at);
return scheduledAt !== null && scheduledAt <= now;
});
if (due.length > 0) {
// Sort by priority descending
due.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
results.push({ agentId, slots: due });
}
}
return results;
}
/**
* Get all agent IDs in the cache.
*/
getAgentIds(): string[] {
return Array.from(this.schedules.keys());
}
/**
* Get slots for a specific agent.
*/
getAgentSlots(agentId: string): CachedSlot[] {
return this.schedules.get(agentId) ?? [];
}
/**
* Get cache status for debugging.
*/
getStatus(): { agentCount: number; totalSlots: number; lastSyncAt: string | null; cachedDate: string | null } {
let totalSlots = 0;
for (const slots of this.schedules.values()) totalSlots += slots.length;
return {
agentCount: this.schedules.size,
totalSlots,
lastSyncAt: this.lastSyncAt?.toISOString() ?? null,
cachedDate: this.cachedDate,
};
}
private parseScheduledTime(scheduledAt: string): Date | null {
if (/^\d{2}:\d{2}(:\d{2})?$/.test(scheduledAt)) {
if (!this.cachedDate) return null;
return new Date(`${this.cachedDate}T${scheduledAt}Z`);
}
const d = new Date(scheduledAt);
return isNaN(d.getTime()) ? null : d;
}
}

View File

@@ -18,7 +18,7 @@
import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
import { join, dirname } from 'path';
import { CalendarBridgeClient } from './calendar-bridge';
import { CalendarBridgeClient } from './calendar-bridge.js';
import {
CalendarSlotResponse,
SlotStatus,
@@ -26,7 +26,7 @@ import {
SlotAgentUpdate,
CalendarEventDataJob,
CalendarEventDataSystemEvent,
} from './types';
} from './types.js';
export interface CalendarSchedulerConfig {
/** Calendar bridge client for backend communication */

View File

@@ -1,6 +1,6 @@
import { hostname } from 'os';
import { getPluginConfig } from '../core/config';
import { startManagedMonitor } from '../core/managed-monitor';
import { getPluginConfig } from '../core/config.js';
import { startManagedMonitor } from '../core/managed-monitor.js';
export function registerGatewayStartHook(api: any, deps: {
logger: any;

View File

@@ -1,4 +1,4 @@
import { stopManagedMonitor } from '../core/managed-monitor';
import { stopManagedMonitor } from '../core/managed-monitor.js';
export function registerGatewayStopHook(api: any, deps: {
logger: any;

View File

@@ -11,18 +11,20 @@
* served directly by the plugin when Monitor queries via the
* local monitor_port communication path.
*/
import { hostname, freemem, totalmem, uptime, loadavg, platform } from 'os';
import { getPluginConfig } from './core/config';
import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge';
import type { OpenClawAgentInfo } from './core/openclaw-agents';
import { registerGatewayStartHook } from './hooks/gateway-start';
import { registerGatewayStopHook } from './hooks/gateway-stop';
import { hostname, freemem, totalmem, uptime, loadavg, platform } from 'node:os';
import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
import { MultiAgentScheduleCache } from './calendar/schedule-cache.js';
import { getPluginConfig } from './core/config.js';
import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge.js';
import type { OpenClawAgentInfo } from './core/openclaw-agents.js';
import { registerGatewayStartHook } from './hooks/gateway-start.js';
import { registerGatewayStopHook } from './hooks/gateway-stop.js';
import {
createCalendarBridgeClient,
createCalendarScheduler,
CalendarScheduler,
AgentWakeContext,
} from './calendar';
} from './calendar/index.js';
interface PluginAPI {
logger: {
@@ -53,10 +55,7 @@ interface PluginAPI {
getAgentStatus?: () => Promise<{ status: string } | null>;
}
export default {
id: 'harbor-forge',
name: 'HarborForge',
register(api: PluginAPI) {
function register(api: PluginAPI): void {
const logger = api.logger || {
info: (...args: any[]) => console.log('[HarborForge]', ...args),
error: (...args: any[]) => console.error('[HarborForge]', ...args),
@@ -68,6 +67,13 @@ export default {
return getPluginConfig(api);
}
/** Resolve agent ID from env, config, or fallback. */
function resolveAgentId(): string {
if (process.env.AGENT_ID) return process.env.AGENT_ID;
const cfg = api.runtime?.config?.loadConfig?.();
return cfg?.agents?.list?.[0]?.id ?? cfg?.agents?.defaults?.id ?? 'unknown';
}
/**
* Get the monitor bridge client if monitor_port is configured.
*/
@@ -168,7 +174,7 @@ export default {
// Fallback: query backend for agent status
const live = resolveConfig();
const agentId = process.env.AGENT_ID || 'unknown';
const agentId = resolveAgentId();
try {
const response = await fetch(`${live.backendUrl}/calendar/agent/status?agent_id=${agentId}`, {
headers: {
@@ -188,56 +194,88 @@ export default {
}
/**
* Wake/spawn agent with task context for slot execution.
* This is the callback invoked by CalendarScheduler when a slot is ready.
* Wake agent via dispatchInboundMessage — same mechanism used by Discord plugin.
* Direct in-process call, no WebSocket or CLI needed.
*/
async function wakeAgent(context: AgentWakeContext): Promise<boolean> {
logger.info(`Waking agent for slot: ${context.taskDescription}`);
async function wakeAgent(
agentId: string,
dueSlots?: Array<{
id?: number | null;
virtual_id?: string | null;
event_data?: any;
scheduled_at?: string;
priority?: number;
slot_type?: string;
[k: string]: unknown;
}>
): Promise<boolean> {
logger.info(`Waking agent ${agentId}: has due slots`);
const sessionKey = `agent:${agentId}:hf-wakeup`;
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
});
const sdkPath = 'openclaw/plugin-sdk/reply-runtime';
const { dispatchInboundMessageWithDispatcher } = await import(
/* webpackIgnore: true */ sdkPath
);
if (result?.sessionId) {
logger.info(`Agent spawned for calendar slot: session=${result.sessionId}`);
// Track session completion
trackSessionCompletion(result.sessionId, context);
return true;
}
// api.config first (current public API). Fall back to deprecated
// runtime.config.loadConfig() for older host versions. Both should
// contain agents.list / channels for dispatch routing.
const cfg = (api as any).config ?? api.runtime?.config?.loadConfig?.();
if (!cfg) {
logger.error('Cannot load OpenClaw config for dispatch');
return false;
}
// 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');
// Inline the highest-priority due slot's context so the agent does
// not need a second round-trip to harborforge_calendar_status. The
// agent can read event_data.task_code / task_title etc. directly.
let slotBlock = '';
const top = dueSlots && dueSlots.length ? dueSlots[0] : undefined;
if (top) {
slotBlock = `\n\nMatching slot:\n\`\`\`json\n${JSON.stringify(
{
slot_id: top.id ?? null,
virtual_id: top.virtual_id ?? null,
scheduled_at: top.scheduled_at ?? null,
priority: top.priority ?? null,
slot_type: top.slot_type ?? null,
event_data: top.event_data ?? null,
},
null,
2
)}\n\`\`\``;
}
// Send calendar wakeup notification via backend
const live = resolveConfig();
const agentId = process.env.AGENT_ID || 'unknown';
const wakeupMessage =
`You have due slots. Follow the \`hf-wakeup\` workflow of skill ` +
`\`hf-hangman-lab\` to proceed. Only reply \`WAKEUP_OK\` in this ` +
`session.${slotBlock}`;
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(),
const result = await dispatchInboundMessageWithDispatcher({
ctx: {
Body: wakeupMessage,
SessionKey: sessionKey,
From: 'harborforge-calendar',
Provider: 'harborforge',
},
cfg,
dispatcherOptions: {
deliver: async (payload: any) => {
const text = (payload.text || '').trim();
logger.info(`Agent ${agentId} wakeup reply: ${text.slice(0, 100)}`);
},
},
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.info(`Agent ${agentId} dispatched: ${result?.status || 'ok'}`);
return true;
} catch (err) {
logger.error('Failed to wake agent:', err);
} catch (err: any) {
const msg = err?.message || err?.code || String(err);
const stack = err?.stack?.split('\n').slice(0, 3).join(' | ') || '';
logger.error(`Failed to dispatch agent for slot: ${msg} ${stack}`);
return false;
}
}
@@ -279,27 +317,99 @@ export default {
*/
function startCalendarScheduler(): void {
const live = resolveConfig();
const agentId = process.env.AGENT_ID || 'unknown';
// Create calendar bridge client
// Create bridge client (claw-instance level, not per-agent)
const calendarBridge = createCalendarBridgeClient(
api,
live.backendUrl || 'https://monitor.hangman-lab.top',
agentId
'unused' // agentId no longer needed at bridge level
);
// Create and start scheduler
calendarScheduler = createCalendarScheduler({
bridge: calendarBridge,
getAgentStatus,
wakeAgent,
logger,
heartbeatIntervalMs: 60000, // 1 minute
debug: live.logLevel === 'debug',
});
// Multi-agent sync + check loop
const scheduleCache = new MultiAgentScheduleCache();
calendarScheduler.start();
logger.info('Calendar scheduler started');
const SYNC_INTERVAL_MS = 300_000; // 5 min
const CHECK_INTERVAL_MS = 30_000; // 30 sec
// Sync: pull all agent schedules from backend
async function runSync() {
try {
const result = await calendarBridge.syncSchedules();
if (result) {
scheduleCache.sync(result.date, result.schedules);
const status = scheduleCache.getStatus();
logger.info(`Schedule synced: ${status.agentCount} agents, ${status.totalSlots} slots`);
}
} catch (err) {
logger.warn(`Schedule sync failed: ${String(err)}`);
}
}
// Track wakes already dispatched for a slot in the current sync
// window — the simplified inline scheduler does not PATCH slot
// status server-side, so without dedupe the check loop re-wakes
// the same slot every 30s. Set is cleared by runSync (fresh wake
// budget per sync).
const wakedSlotKeys = new Set<string>();
// Check: find agents with due slots and wake them
async function runCheck() {
const now = new Date();
const agentsWithDue = scheduleCache.getAgentsWithDueSlots(now);
for (const { agentId, slots } of agentsWithDue) {
// Filter out slots we've already woken this sync window
const fresh = slots.filter((s) => {
const key = `${agentId}::${s.id ?? s.virtual_id ?? s.scheduled_at}`;
if (wakedSlotKeys.has(key)) return false;
return true;
});
if (fresh.length === 0) continue;
// Check if agent is busy (best effort; backend may 405 the GET
// — treat unknown as not-busy so wakeup still fires)
let status: string | null = null;
try {
status = await calendarBridge.getAgentStatus(agentId);
} catch {
status = null;
}
if (status === 'busy' || status === 'offline' || status === 'exhausted') {
continue;
}
// Wake the agent with the slot context inlined
const ok = await wakeAgent(agentId, fresh);
if (ok) {
for (const s of fresh) {
const key = `${agentId}::${s.id ?? s.virtual_id ?? s.scheduled_at}`;
wakedSlotKeys.add(key);
}
}
}
}
// Initial sync (also resets the wake-dedupe window)
const runSyncReset = async () => {
wakedSlotKeys.clear();
await runSync();
};
runSyncReset();
// Start intervals
const syncHandle = setInterval(runSyncReset, SYNC_INTERVAL_MS);
const checkHandle = setInterval(runCheck, CHECK_INTERVAL_MS);
// Store handles for cleanup (reuse calendarScheduler variable)
(calendarScheduler as any) = {
stop() {
clearInterval(syncHandle);
clearInterval(checkHandle);
logger.info('Calendar scheduler stopped');
},
};
logger.info('Calendar scheduler started (multi-agent sync mode)');
}
/**
@@ -551,5 +661,16 @@ export default {
}));
logger.info('HarborForge plugin registered (id: harbor-forge)');
},
};
}
// HarborForge's local PluginAPI is broader than the standard OpenClawPluginApi
// (it surfaces optional `version`/`runtime`/`spawn` accessors that older
// OpenClaw builds exposed). The cast at the definePluginEntry boundary
// acknowledges that gap — the runtime api object is whatever the gateway
// passes us, and each access is guarded with optional chaining / fallbacks.
export default definePluginEntry({
id: 'harbor-forge',
name: 'HarborForge',
description: 'HarborForge plugin for OpenClaw - project management, monitoring, and CLI integration',
register: register as (api: any) => void,
});

25
plugin/openclaw-sdk.d.ts vendored Normal file
View File

@@ -0,0 +1,25 @@
// Ambient declarations for the focused subpaths of the openclaw plugin SDK
// that this plugin needs at compile time.
//
// We intentionally do NOT take a `dependencies` (or `devDependencies`) entry
// on the openclaw npm package itself: openclaw is provided by the host
// gateway at runtime, and listing it as a file:/.../openclaw devDep breaks
// the installer's `npm install --omit=dev` step because npm/arborist trips
// over openclaw's own (deeply nested) dependency graph.
//
// These declarations cover only what we use here. They are deliberately
// permissive — the runtime contract is whatever the gateway hands us, and
// we guard each api access with optional chaining or a fallback at call site.
declare module 'openclaw/plugin-sdk/plugin-entry' {
export function definePluginEntry<T extends {
id: string;
name: string;
description?: string;
register: (api: any) => void | Promise<void>;
}>(opts: T): T;
}
declare module 'openclaw/plugin-sdk/core' {
export type OpenClawPluginApi = unknown;
}

View File

@@ -1,9 +1,23 @@
{
"id": "harbor-forge",
"name": "HarborForge",
"version": "0.2.0",
"description": "HarborForge plugin for OpenClaw - project management, monitoring, and CLI integration",
"entry": "./dist/index.js",
"activation": {
"onStartup": true
},
"contracts": {
"tools": [
"harborforge_status",
"harborforge_telemetry",
"harborforge_monitor_telemetry",
"harborforge_calendar_status",
"harborforge_calendar_complete",
"harborforge_calendar_abort",
"harborforge_calendar_pause",
"harborforge_calendar_resume",
"harborforge_restart_status"
]
},
"configSchema": {
"type": "object",
"additionalProperties": false,

View File

@@ -9,14 +9,14 @@
"version": "0.2.0",
"license": "MIT",
"devDependencies": {
"@types/node": "^20.0.0",
"@types/node": "^20.19.41",
"typescript": "^5.0.0"
}
},
"node_modules/@types/node": {
"version": "20.19.37",
"resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.37.tgz",
"integrity": "sha512-8kzdPJ3FsNsVIurqBs7oodNnCEVbni9yUEkaHbgptDACOPW04jimGagZ51E6+lXUwJjgnBw+hyko/lkFWCldqw==",
"version": "20.19.41",
"resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.41.tgz",
"integrity": "sha512-ECymXOukMnOoVkC2bb1Vc/w/836DXncOg5m8Xj1RH7xSHZJWNYY6Zh7EH477vcnD5egKNNfy2RpNOmuChhFPgQ==",
"dev": true,
"license": "MIT",
"dependencies": {

View File

@@ -2,6 +2,7 @@
"name": "harbor-forge-plugin",
"version": "0.2.0",
"description": "OpenClaw plugin for HarborForge monitor bridge and CLI integration",
"type": "module",
"main": "dist/index.js",
"scripts": {
"clean": "rm -rf dist",
@@ -9,7 +10,7 @@
"watch": "tsc --watch"
},
"devDependencies": {
"@types/node": "^20.0.0",
"@types/node": "^20.19.41",
"typescript": "^5.0.0"
},
"license": "MIT"

View File

@@ -1,8 +1,8 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "CommonJS",
"moduleResolution": "node",
"module": "nodenext",
"moduleResolution": "nodenext",
"esModuleInterop": true,
"strict": true,
"skipLibCheck": true,