2 Commits

Author SHA1 Message Date
h z
f627845543 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
hanghang zhang
b878fa2a41 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
5 changed files with 95 additions and 637 deletions

View File

@@ -110,23 +110,6 @@ export class CalendarBridgeClient {
return this.sendBoolean('PATCH', url, update);
}
/**
* Same as {@link updateSlot} but overrides the `X-Agent-ID` header for a
* single call. Used by the multi-agent scheduler handle where the bridge
* client is shared across agents and the constructor agentId is `'unused'`.
*
* Backend identifies the slot purely by `slotId`; the header is informational
* for audit. Passing the calling agent's id keeps audit/log lines correct.
*/
async updateSlotAs(
agentId: string,
slotId: number,
update: SlotAgentUpdate
): Promise<boolean> {
const url = `${this.baseUrl}/calendar/slots/${slotId}/agent-update`;
return this.sendBooleanAs(agentId, 'PATCH', url, update);
}
/**
* Update a virtual (plan-generated) slot's status after agent execution.
*
@@ -281,15 +264,6 @@ export class CalendarBridgeClient {
}
private async sendBoolean(method: 'POST' | 'PATCH', url: string, body: unknown): Promise<boolean> {
return this.sendBooleanAs(this.config.agentId, method, url, body);
}
private async sendBooleanAs(
agentId: string,
method: 'POST' | 'PATCH',
url: string,
body: unknown
): Promise<boolean> {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
@@ -298,7 +272,7 @@ export class CalendarBridgeClient {
method,
headers: {
'Content-Type': 'application/json',
'X-Agent-ID': agentId,
'X-Agent-ID': this.config.agentId,
'X-Claw-Identifier': this.config.clawIdentifier,
},
body: JSON.stringify(body),

View File

@@ -1,240 +0,0 @@
/**
* MultiAgentSchedulerHandle — runtime façade that backs the public
* `harborforge_calendar_*` tools when the plugin runs in multi-agent sync
* mode.
*
* Background
* ----------
* The old single-agent path used `CalendarScheduler` which kept a "current
* slot" cursor and exposed `isRunning() / completeCurrentSlot() / abortCurrentSlot() / …`.
* In multi-agent mode the plugin doesn't own a single cursor — one plugin
* instance services every agent on the claw — so the previous code stubbed the
* `calendarScheduler` variable to `{ stop() }`. That made every tool fail
* with `calendarScheduler.<method> is not a function`.
*
* This handle restores the same surface area (`isRunning / getCurrentSlot /
* completeCurrentSlot / …`) but resolves the "current slot" per caller via
* the agentId/sessionKey supplied by the OpenClaw tool-factory context. The
* scheduler records the slot it just dispatched to each agent in
* {@link recordWoken}; the tool resolves the caller, looks up the last woken
* slot, and PATCHes the backend via the shared bridge.
*
* Tools must pass the calling agentId (from `OpenClawPluginToolContext.agentId`)
* into every method. The handle does not consult `process.env.AGENT_ID` — the
* gateway sets that to the host's primary agent which is meaningless in
* multi-agent mode.
*/
import type { CalendarBridgeClient } from './calendar-bridge.js';
import type { MultiAgentScheduleCache, CachedSlot } from './schedule-cache.js';
import { SlotStatus } from './types.js';
export interface MultiAgentSchedulerHandleParams {
bridge: CalendarBridgeClient;
cache: MultiAgentScheduleCache;
/** setInterval handles cleared on stop() */
syncHandle: ReturnType<typeof setInterval>;
checkHandle: ReturnType<typeof setInterval>;
logger: {
info: (...args: unknown[]) => void;
warn: (...args: unknown[]) => void;
error: (...args: unknown[]) => void;
};
}
/** Last slot we dispatched to an agent. Used as the implicit "current slot". */
export interface WokenSlot {
agentId: string;
slotId: number | null;
virtualId: string | null;
scheduledAt: string | null;
slotType: string | null;
estimatedDuration: number | null;
wokenAt: string;
}
/** Public surface — mirrors the relevant subset of the old single-agent scheduler. */
export class MultiAgentSchedulerHandle {
private readonly bridge: CalendarBridgeClient;
private readonly cache: MultiAgentScheduleCache;
private readonly syncHandle: ReturnType<typeof setInterval>;
private readonly checkHandle: ReturnType<typeof setInterval>;
private readonly logger: MultiAgentSchedulerHandleParams['logger'];
private readonly woken: Map<string, WokenSlot> = new Map();
private stopped = false;
constructor(params: MultiAgentSchedulerHandleParams) {
this.bridge = params.bridge;
this.cache = params.cache;
this.syncHandle = params.syncHandle;
this.checkHandle = params.checkHandle;
this.logger = params.logger;
}
// ---------- lifecycle ----------
/** True while the sync/check intervals are still ticking. */
isRunning(): boolean {
return !this.stopped;
}
/** Always false in multi-agent mode — there is no per-instance work queue. */
isProcessing(): boolean {
return false;
}
stop(): void {
if (this.stopped) return;
this.stopped = true;
clearInterval(this.syncHandle);
clearInterval(this.checkHandle);
this.logger.info('Calendar scheduler stopped (multi-agent mode)');
}
// ---------- wake bookkeeping ----------
/** Record that we just dispatched a slot to `agentId`. */
recordWoken(agentId: string, slot: CachedSlot): void {
this.woken.set(agentId, {
agentId,
slotId: typeof slot.id === 'number' ? slot.id : null,
virtualId: typeof slot.virtual_id === 'string' ? slot.virtual_id : null,
scheduledAt: typeof slot.scheduled_at === 'string' ? slot.scheduled_at : null,
slotType: typeof slot.slot_type === 'string' ? slot.slot_type : null,
estimatedDuration:
typeof slot.estimated_duration === 'number' ? slot.estimated_duration : null,
wokenAt: new Date().toISOString(),
});
}
// ---------- per-agent reads ----------
/**
* The slot most recently dispatched to `agentId`, or null if we never woke
* them (e.g. tool called outside a wakeup). Callers can fall back to
* scanning {@link cachedSlotsFor} for `not_started`/`deferred` slots if they
* want a heuristic "current".
*/
getWokenSlot(agentId: string | null | undefined): WokenSlot | null {
if (!agentId) return null;
return this.woken.get(agentId) ?? null;
}
/** Today's cached slots for an agent (whatever runSync last pulled). */
cachedSlotsFor(agentId: string | null | undefined): CachedSlot[] {
if (!agentId) return [];
return this.cache.getAgentSlots(agentId);
}
/**
* Implicit "current" slot: the last woken slot if we know about it,
* otherwise the highest-priority `not_started`/`deferred`/`ongoing` cached
* slot for the agent (so a tool called between sync windows still finds
* something sensible).
*/
resolveCurrentSlot(agentId: string | null | undefined): WokenSlot | null {
const woken = this.getWokenSlot(agentId);
if (woken) return woken;
if (!agentId) return null;
const slots = this.cache.getAgentSlots(agentId)
.filter((s) => s.status === 'not_started' || s.status === 'deferred' || s.status === 'ongoing')
.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
const top = slots[0];
if (!top) return null;
return {
agentId,
slotId: typeof top.id === 'number' ? top.id : null,
virtualId: typeof top.virtual_id === 'string' ? top.virtual_id : null,
scheduledAt: typeof top.scheduled_at === 'string' ? top.scheduled_at : null,
slotType: typeof top.slot_type === 'string' ? top.slot_type : null,
estimatedDuration:
typeof top.estimated_duration === 'number' ? top.estimated_duration : null,
wokenAt: 'inferred-from-cache',
};
}
// ---------- per-agent writes ----------
async completeSlot(agentId: string, actualDurationMinutes: number): Promise<SlotMutationResult> {
return this.transition(agentId, SlotStatus.FINISHED, { actual_duration: actualDurationMinutes });
}
async abortSlot(agentId: string, reason?: string): Promise<SlotMutationResult> {
if (reason) this.logger.info(`Aborting slot for ${agentId}: ${reason}`);
return this.transition(agentId, SlotStatus.ABORTED);
}
async pauseSlot(agentId: string): Promise<SlotMutationResult> {
return this.transition(agentId, SlotStatus.PAUSED);
}
/** Resume puts the slot back into `ongoing` so it isn't picked up as `not_started`. */
async resumeSlot(agentId: string): Promise<SlotMutationResult> {
return this.transition(agentId, SlotStatus.ONGOING);
}
private async transition(
agentId: string,
status: SlotStatus,
extra: { actual_duration?: number } = {}
): Promise<SlotMutationResult> {
const slot = this.resolveCurrentSlot(agentId);
if (!slot) {
return { ok: false, error: `No tracked slot for agent '${agentId}'` };
}
if (slot.slotId == null && slot.virtualId == null) {
return { ok: false, error: 'Resolved slot has neither id nor virtual_id' };
}
const update = { status, ...extra };
try {
if (slot.slotId != null) {
const ok = await this.bridge.updateSlotAs(agentId, slot.slotId, update);
if (!ok) return { ok: false, error: `Backend rejected slot ${slot.slotId}${status}` };
// Clear the wake cursor only on terminal transitions so re-wakes don't
// re-trigger the same slot mutation.
if (status === SlotStatus.FINISHED || status === SlotStatus.ABORTED) {
this.woken.delete(agentId);
}
return { ok: true, slot, status };
}
// virtual slot path: bridge has updateVirtualSlot
const materialised = await this.bridge.updateVirtualSlot(slot.virtualId!, update);
if (!materialised) {
return { ok: false, error: `Backend rejected virtual slot ${slot.virtualId}` };
}
if (status === SlotStatus.FINISHED || status === SlotStatus.ABORTED) {
this.woken.delete(agentId);
}
return { ok: true, slot, status, materialised };
} catch (err: unknown) {
const msg = (err as { message?: string } | undefined)?.message ?? String(err);
return { ok: false, error: msg };
}
}
// ---------- gateway-restart parity (no-op in multi-agent mode) ----------
/** Multi-agent scheduler does not persist a `ScheduledGatewayRestart` flag. */
isRestartPending(): boolean {
return false;
}
getStateFilePath(): string | null {
return null;
}
getState(): { mode: 'multi-agent'; agents: number; lastWoken: WokenSlot[] } {
return {
mode: 'multi-agent',
agents: this.cache.getStatus().agentCount,
lastWoken: Array.from(this.woken.values()),
};
}
}
export interface SlotMutationResult {
ok: boolean;
error?: string;
status?: SlotStatus;
slot?: WokenSlot;
/** Present only when a virtual slot was materialised. */
materialised?: unknown;
}

View File

@@ -14,7 +14,6 @@
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 { MultiAgentSchedulerHandle } from './calendar/multi-agent-handle.js';
import { getPluginConfig } from './core/config.js';
import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge.js';
import type { OpenClawAgentInfo } from './core/openclaw-agents.js';
@@ -22,28 +21,11 @@ import { registerGatewayStartHook } from './hooks/gateway-start.js';
import { registerGatewayStopHook } from './hooks/gateway-stop.js';
import {
createCalendarBridgeClient,
createCalendarScheduler,
CalendarScheduler,
AgentWakeContext,
} from './calendar/index.js';
// ---------------------------------------------------------------------------
// Module-scope calendar scheduler singleton.
//
// `register()` is called multiple times per gateway boot — once per agent
// (we see 5 `HarborForge plugin registered` lines for 5 agents on dind-t2).
// `gateway_start` only fires once, so before this lift the
// `startCalendarScheduler()` setup ran inside ONE closure while four other
// closures kept their own `calendarScheduler = null`. Whichever of the five
// tool registrations the gateway picked at call time was effectively a coin
// flip, and four times out of five `harborforge_calendar_status` returned
// `Calendar scheduler not running` even though the scheduler was active.
//
// Keeping the singleton at module scope removes the per-`register()` shadow:
// the scheduler is started once, every closure reads the same binding, and
// `startCalendarScheduler()` is idempotent so duplicate `gateway_start`
// firings are harmless.
// ---------------------------------------------------------------------------
let calendarScheduler: MultiAgentSchedulerHandle | CalendarScheduler | null = null;
interface PluginAPI {
logger: {
info: (...args: any[]) => void;
@@ -73,57 +55,6 @@ interface PluginAPI {
getAgentStatus?: () => Promise<{ status: string } | null>;
}
/**
* Coerce a tool execute() return value into the MCP `{ content: [...] }`
* shape that the openclaw Codex tool dispatcher requires.
*
* Background: openclaw's `convertToolContents()` does `result.content.reduce(...)`
* to compute total text length before flattening. Every HF tool here returned a
* bare object (`{ running, processing, currentSlot, ... }`) which has no
* `.content` field, so `undefined.reduce` threw and every call to
* `harborforge_*` from a Codex-harness agent surfaced as the cryptic
* `Cannot read properties of undefined (reading 'reduce')`. The fix is to
* wrap every tool's execute return; doing it at the `registerTool` boundary
* keeps each tool body unchanged.
*/
/**
* Install a fail-open globalThis.__padded stub if PaddedCell hasn't loaded
* yet (load order isn't guaranteed). PaddedCell's installGlobalApi drains
* `_pendingCatalog` and replaces `allowTool` with the real check when it
* starts. This means HF tools registered before PaddedCell are visible
* to the agent until PaddedCell takes over, after which they fall under
* the per-session cache gate (decision #37, openclaw side).
*/
function ensurePaddedStub(): void {
const g = globalThis as unknown as {
__padded?: {
_pendingCatalog?: Array<{ name: string; description: string }>;
registerCatalogEntry?: (n: string, d: string) => void;
allowTool?: (n: string, c: unknown) => boolean;
};
};
if (g.__padded) return;
const buf: Array<{ name: string; description: string }> = [];
g.__padded = {
_pendingCatalog: buf,
registerCatalogEntry(name: string, description: string): void {
buf.push({ name, description });
},
allowTool: () => true,
};
}
function ensureMcpContentShape(result: unknown): { content: Array<{ type: 'text'; text: string }> } {
if (
result && typeof result === 'object' &&
Array.isArray((result as { content?: unknown }).content)
) {
return result as { content: Array<{ type: 'text'; text: string }> };
}
const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
return { content: [{ type: 'text', text }] };
}
function register(api: PluginAPI): void {
const logger = api.logger || {
info: (...args: any[]) => console.log('[HarborForge]', ...args),
@@ -132,43 +63,6 @@ function register(api: PluginAPI): void {
warn: (...args: any[]) => console.warn('[HarborForge]', ...args),
};
// PaddedCell tools-cache integration (decision #37, openclaw side).
// Stub the global API early so the gate is consistent regardless of
// plugin load order; PaddedCell will replace stub with the real impl
// when it loads. fail-open until then.
ensurePaddedStub();
const seenForCatalog = new Set<string>();
// Wrap api.registerTool so every tool:
// (a) registers its name+description into PaddedCell's catalog so
// dynamic-list-tools / dynamic-search-tools surface it (#37)
// (b) returns null when the per-session cache doesn't include the
// name → the tool is hidden from the model that turn
// (c) has its execute() return coerced into the MCP `{ content: [...] }`
// shape openclaw expects (preserved from earlier).
const _origRegisterTool = api.registerTool.bind(api);
api.registerTool = (factory: (ctx: any) => any) => {
_origRegisterTool((ctx: any) => {
const def = factory(ctx);
if (!def || typeof def.execute !== 'function') return def;
const padded = (globalThis as any).__padded as
| { allowTool?: (n: string, c: any) => boolean; registerCatalogEntry?: (n: string, d: string) => void }
| undefined;
if (def.name && padded?.registerCatalogEntry && !seenForCatalog.has(def.name)) {
padded.registerCatalogEntry(def.name, def.description ?? '');
seenForCatalog.add(def.name);
}
if (def.name && padded?.allowTool && !padded.allowTool(def.name, ctx)) {
return null;
}
const origExecute = def.execute;
return {
...def,
execute: async (...args: any[]) => ensureMcpContentShape(await origExecute(...args)),
};
});
};
function resolveConfig() {
return getPluginConfig(api);
}
@@ -176,9 +70,7 @@ function register(api: PluginAPI): void {
/** Resolve agent ID from env, config, or fallback. */
function resolveAgentId(): string {
if (process.env.AGENT_ID) return process.env.AGENT_ID;
// Read from cached `api.config` first — see pushMetaToMonitor for why
// the deprecated `api.runtime?.config?.loadConfig?.()` path is heavy.
const cfg = (api as any).config ?? api.runtime?.config?.loadConfig?.();
const cfg = api.runtime?.config?.loadConfig?.();
return cfg?.agents?.list?.[0]?.id ?? cfg?.agents?.defaults?.id ?? 'unknown';
}
@@ -217,7 +109,7 @@ function register(api: PluginAPI): void {
},
openclaw: {
version: api.runtime?.version || api.version || 'unknown',
pluginVersion: '0.3.4', // Bumped for PLG-CAL-004
pluginVersion: '0.3.1', // Bumped for PLG-CAL-004
},
timestamp: new Date().toISOString(),
};
@@ -226,33 +118,13 @@ function register(api: PluginAPI): void {
// Periodic metadata push interval handle
let metaPushInterval: ReturnType<typeof setInterval> | null = null;
// (calendarScheduler is module-scope — see top of file for the why.
// Tools and lifecycle hooks all reference the same binding so the
// multi-register/single-start mismatch can't shadow them again.)
// Calendar scheduler instance
let calendarScheduler: CalendarScheduler | null = null;
/**
* Push OpenClaw metadata to the Monitor bridge.
* This enriches Monitor heartbeats with OpenClaw version/plugin/agent info.
* Failures are non-fatal — Monitor continues to work without this data.
*
* IMPORTANT — read config from the cached `api.config` surface, NOT from
* the deprecated `api.runtime?.config?.loadConfig?.()` path. The
* deprecated path triggers a full plugin-metadata-snapshot rebuild on
* every call: realpathSync walks every plugin's package.json + manifest
* + source paths (lstats up the directory tree), `hashWatchedFiles`
* fingerprints all watched plugin files, and `discoverInDirectory`
* re-scans every `dist/extensions/<plugin>` dir. On t2 with ~100 plugins
* each rebuild costs ~6-7s of CPU; with this push firing every 30s
* (default reportIntervalSec) the chronic baseline was ~22-25% gateway
* CPU even with zero agent activity (V8 profile 2026-05-27 08:14:00 60s:
* lstat 44.2%, statSync 6.9%, hashWatchedFiles via memo key 1.7%, all
* routed through readPersistedInstalledPluginIndexInstallRecordsSync ->
* discoverInDirectory). Switching to `api.config` reads from the
* already-loaded snapshot cache; the elsewhere-in-this-file pattern was
* already `api.config ?? api.runtime?.config?.loadConfig?.()`.
*
* Same fix is applied to `resolveAgentId` below — that's read once at
* gateway start so the impact is smaller, but it's the same anti-pattern.
*/
async function pushMetaToMonitor() {
const bridgeClient = getBridgeClient();
@@ -260,7 +132,7 @@ function register(api: PluginAPI): void {
let agentNames: string[] = [];
try {
const cfg = (api as any).config ?? api.runtime?.config?.loadConfig?.();
const cfg = api.runtime?.config?.loadConfig?.();
const agentsList = cfg?.agents?.list;
if (Array.isArray(agentsList)) {
agentNames = agentsList
@@ -271,7 +143,7 @@ function register(api: PluginAPI): void {
const meta: OpenClawMeta = {
version: api.runtime?.version || api.version || 'unknown',
plugin_version: '0.3.4',
plugin_version: '0.3.1',
agents: agentNames.map(name => ({ name })),
};
@@ -376,22 +248,10 @@ function register(api: PluginAPI): void {
)}\n\`\`\``;
}
// The wakeup dispatcher's `deliver` callback below only logs the
// reply text — it does NOT inspect any ack token. The earlier
// `WAKEUP_OK` first-line-ack convention was prompt-only theatre;
// nothing in this plugin or in openclaw acted on it. The only
// thing that ends a wake cycle is the slot transitioning out of
// `not_started`, which happens when the agent calls
// `harborforge_calendar_complete` or `harborforge_calendar_abort`.
// Tell the agent that plainly instead of asking for a fake ack.
const wakeupMessage =
`You have due slots. Drive the \`hf-wakeup\` workflow of skill ` +
`\`hf-hangman-lab\` to completion in this session — read slot ` +
`context, call the harborforge_calendar_* tools, route to the ` +
`right sub-workflow, and finish with harborforge_calendar_complete ` +
`or harborforge_calendar_abort. The scheduler keeps re-waking you ` +
`every 30s until the slot transitions out of \`not_started\`, so ` +
`partial work or silence just produces another wake.${slotBlock}`;
`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 result = await dispatchInboundMessageWithDispatcher({
ctx: {
@@ -420,23 +280,42 @@ function register(api: PluginAPI): void {
}
}
// (trackSessionCompletion removed — legacy single-agent poll loop that
// called calendarScheduler.completeCurrentSlot. The multi-agent path
// closes slots via the harborforge_calendar_complete tool, driven by
// the agent itself, not by a timer.)
/**
* Track session completion and update slot status accordingly.
*/
function trackSessionCompletion(sessionId: string, context: AgentWakeContext): void {
// Poll for session completion (simplified approach)
// In production, this would use webhooks or event streaming
const pollInterval = 30000; // 30 seconds
const maxDuration = context.slot.estimated_duration * 60 * 1000; // Convert to ms
const startTime = Date.now();
const poll = async () => {
if (!calendarScheduler) return;
const elapsed = Date.now() - startTime;
// Check if session is complete (would use actual API in production)
// For now, estimate completion based on duration
if (elapsed >= maxDuration) {
// Assume completion
const actualMinutes = Math.round(elapsed / 60000);
await calendarScheduler.completeCurrentSlot(actualMinutes);
return;
}
// Continue polling
setTimeout(poll, pollInterval);
};
// Start polling
setTimeout(poll, pollInterval);
}
/**
* Initialize and start the calendar scheduler.
*
* Idempotent — `gateway_start` may fire once per `register()` invocation
* (the host calls `register` per agent), and we only want one set of
* sync/check intervals across the whole process.
*/
function startCalendarScheduler(): void {
if (calendarScheduler) {
logger.info('Calendar scheduler already started, skipping duplicate gateway_start');
return;
}
const live = resolveConfig();
// Create bridge client (claw-instance level, not per-agent)
@@ -466,94 +345,6 @@ function register(api: PluginAPI): void {
}
}
// Cross-plugin exposure: agent status lookup for other plugins
// (currently Fabric.OpenclawPlugin uses this to skip delivering
// `announce` channel messages to busy agents — see DIALECTIC-V2
// design doc, Phase 1). Backed by calendarBridge.getAgentStatus
// with a small TTL cache to avoid hammering the HF backend.
type HfStatus = 'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline';
const HF_STATUS_CACHE_TTL_MS = 30_000;
const hfStatusCache = new Map<string, { status: HfStatus; at: number }>();
const _G = globalThis as Record<string, unknown>;
_G['__hfAgentStatus'] = {
async get(agentId: string): Promise<HfStatus | undefined> {
if (!agentId) return undefined;
const cached = hfStatusCache.get(agentId);
if (cached && Date.now() - cached.at < HF_STATUS_CACHE_TTL_MS) {
return cached.status;
}
try {
const status = await calendarBridge.getAgentStatus(agentId);
if (status) {
const typed = status as HfStatus;
hfStatusCache.set(agentId, { status: typed, at: Date.now() });
return typed;
}
} catch {
/* fall through to cached-or-undefined */
}
return cached?.status;
},
/**
* Approximate "does agent have an on_call slot covering [from, to]?"
* for cross-plugin pre-check use (currently:
* Dialectic.OpenclawPlugin's signup HF coverage).
*
* v1 honest scope: we only have today's slots in scheduleCache
* (synced from /calendar/sync which is today-only). Returns:
* - true iff window is same-day AND some cached on_call slot
* starts <= from AND ends >= to
* - false iff window is same-day AND no such slot
* - undefined for cross-day windows OR cache empty for this
* agent (caller treats undefined as "I don't know" — see
* Dialectic plugin's hf-precheck.ts which degrades to
* "skipped" gracefully)
*
* Phase TBD: when HF backend ships a `/calendar/slots?agent&from&to`
* endpoint, swap this to call it for arbitrary windows. Until then,
* same-day-only coverage gates ~all debates created by analyze-intel
* (which schedules <2h windows) without needing a backend change.
*/
async hasOnCallCovering(
agentId: string,
fromIso: string,
toIso: string,
): Promise<boolean | undefined> {
if (!agentId || !fromIso || !toIso) return undefined;
const from = new Date(fromIso);
const to = new Date(toIso);
if (isNaN(from.getTime()) || isNaN(to.getTime())) return undefined;
if (!(from < to)) return undefined;
// Cross-day → cache only has today; can't decide.
const fromDate = from.toISOString().slice(0, 10);
const toDate = to.toISOString().slice(0, 10);
if (fromDate !== toDate) return undefined;
// Cache's cachedDate must match our window's date.
const cacheStatus = scheduleCache.getStatus();
if (cacheStatus.cachedDate !== fromDate) return undefined;
const slots = scheduleCache.getAgentSlots(agentId);
if (slots.length === 0) return undefined; // cache empty for this agent — can't decide
for (const s of slots) {
if (s.slot_type !== 'on_call') continue;
// status: ignore aborted/cancelled, accept not_started / ongoing / finished
if (s.status === 'aborted' || s.status === 'cancelled') continue;
const startStr = s.scheduled_at;
if (typeof startStr !== 'string') continue;
// scheduled_at can be HH:MM:SS (cache-relative date) or full ISO
const start =
/^\d{2}:\d{2}(:\d{2})?$/.test(startStr)
? new Date(`${fromDate}T${startStr}Z`)
: new Date(startStr);
if (isNaN(start.getTime())) continue;
const dur = typeof s.estimated_duration === 'number' ? s.estimated_duration : 0;
const end = new Date(start.getTime() + dur * 60_000);
if (start <= from && end >= to) return true;
}
return false;
},
};
// 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
@@ -590,13 +381,6 @@ function register(api: PluginAPI): void {
// Wake the agent with the slot context inlined
const ok = await wakeAgent(agentId, fresh);
if (ok) {
// Top slot is the one inlined in the wakeup message; record it as
// the agent's "current" so harborforge_calendar_complete/abort/…
// can resolve a slot without an explicit param.
const top = fresh[0];
if (top && calendarScheduler instanceof MultiAgentSchedulerHandle) {
calendarScheduler.recordWoken(agentId, top);
}
for (const s of fresh) {
const key = `${agentId}::${s.id ?? s.virtual_id ?? s.scheduled_at}`;
wakedSlotKeys.add(key);
@@ -616,14 +400,14 @@ function register(api: PluginAPI): void {
const syncHandle = setInterval(runSyncReset, SYNC_INTERVAL_MS);
const checkHandle = setInterval(runCheck, CHECK_INTERVAL_MS);
// Install the multi-agent handle so calendar tools resolve per-caller.
calendarScheduler = new MultiAgentSchedulerHandle({
bridge: calendarBridge,
cache: scheduleCache,
syncHandle,
checkHandle,
logger,
});
// 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)');
}
@@ -660,7 +444,7 @@ function register(api: PluginAPI): void {
});
// Tool: plugin status
api.registerTool((ctx) => ({
api.registerTool(() => ({
name: 'harborforge_status',
description: 'Get HarborForge plugin status and current telemetry snapshot',
parameters: {
@@ -679,27 +463,13 @@ function register(api: PluginAPI): void {
: { connected: false, error: 'Monitor bridge unreachable' };
}
// Get calendar scheduler status. In multi-agent mode `currentSlot`
// depends on the caller, so look it up via ctx.agentId.
const callerAgentId = ctx?.agentId ?? resolveAgentId();
const calendarStatus = calendarScheduler
? calendarScheduler instanceof MultiAgentSchedulerHandle
? {
running: calendarScheduler.isRunning(),
processing: calendarScheduler.isProcessing(),
mode: 'multi-agent',
callerAgentId,
currentSlot: calendarScheduler.resolveCurrentSlot(callerAgentId),
isRestartPending: calendarScheduler.isRestartPending(),
}
: {
running: calendarScheduler.isRunning(),
processing: calendarScheduler.isProcessing(),
mode: 'single-agent',
currentSlot: calendarScheduler.getCurrentSlot(),
isRestartPending: calendarScheduler.isRestartPending(),
}
: null;
// Get calendar scheduler status
const calendarStatus = calendarScheduler ? {
running: calendarScheduler.isRunning(),
processing: calendarScheduler.isProcessing(),
currentSlot: calendarScheduler.getCurrentSlot(),
isRestartPending: calendarScheduler.isRestartPending(),
} : null;
return {
enabled: live.enabled !== false,
@@ -758,7 +528,7 @@ function register(api: PluginAPI): void {
}));
// Tool: calendar slot management
api.registerTool((ctx) => ({
api.registerTool(() => ({
name: 'harborforge_calendar_status',
description: 'Get current calendar scheduler status and pending slots',
parameters: {
@@ -769,24 +539,10 @@ function register(api: PluginAPI): void {
if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' };
}
const callerAgentId = ctx?.agentId ?? resolveAgentId();
if (calendarScheduler instanceof MultiAgentSchedulerHandle) {
return {
running: calendarScheduler.isRunning(),
processing: calendarScheduler.isProcessing(),
mode: 'multi-agent',
callerAgentId,
currentSlot: calendarScheduler.resolveCurrentSlot(callerAgentId),
agentSlots: calendarScheduler.cachedSlotsFor(callerAgentId),
state: calendarScheduler.getState(),
isRestartPending: calendarScheduler.isRestartPending(),
stateFilePath: calendarScheduler.getStateFilePath(),
};
}
return {
running: calendarScheduler.isRunning(),
processing: calendarScheduler.isProcessing(),
mode: 'single-agent',
currentSlot: calendarScheduler.getCurrentSlot(),
state: calendarScheduler.getState(),
isRestartPending: calendarScheduler.isRestartPending(),
@@ -796,7 +552,7 @@ function register(api: PluginAPI): void {
}));
// Tool: complete current slot (for agent to report completion)
api.registerTool((ctx) => ({
api.registerTool(() => ({
name: 'harborforge_calendar_complete',
description: 'Complete the current calendar slot with actual duration',
parameters: {
@@ -813,20 +569,14 @@ function register(api: PluginAPI): void {
if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' };
}
if (calendarScheduler instanceof MultiAgentSchedulerHandle) {
const agentId = ctx?.agentId ?? resolveAgentId();
const res = await calendarScheduler.completeSlot(agentId, params.actualDurationMinutes);
return res.ok
? { success: true, message: 'Slot completed', slot: res.slot }
: { error: res.error };
}
await calendarScheduler.completeCurrentSlot(params.actualDurationMinutes);
return { success: true, message: 'Slot completed' };
},
}));
// Tool: abort current slot (for agent to report failure)
api.registerTool((ctx) => ({
api.registerTool(() => ({
name: 'harborforge_calendar_abort',
description: 'Abort the current calendar slot',
parameters: {
@@ -842,20 +592,14 @@ function register(api: PluginAPI): void {
if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' };
}
if (calendarScheduler instanceof MultiAgentSchedulerHandle) {
const agentId = ctx?.agentId ?? resolveAgentId();
const res = await calendarScheduler.abortSlot(agentId, params.reason);
return res.ok
? { success: true, message: 'Slot aborted', slot: res.slot }
: { error: res.error };
}
await calendarScheduler.abortCurrentSlot(params.reason);
return { success: true, message: 'Slot aborted' };
},
}));
// Tool: pause current slot
api.registerTool((ctx) => ({
api.registerTool(() => ({
name: 'harborforge_calendar_pause',
description: 'Pause the current calendar slot',
parameters: {
@@ -866,20 +610,14 @@ function register(api: PluginAPI): void {
if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' };
}
if (calendarScheduler instanceof MultiAgentSchedulerHandle) {
const agentId = ctx?.agentId ?? resolveAgentId();
const res = await calendarScheduler.pauseSlot(agentId);
return res.ok
? { success: true, message: 'Slot paused', slot: res.slot }
: { error: res.error };
}
await calendarScheduler.pauseCurrentSlot();
return { success: true, message: 'Slot paused' };
},
}));
// Tool: resume current slot
api.registerTool((ctx) => ({
api.registerTool(() => ({
name: 'harborforge_calendar_resume',
description: 'Resume the paused calendar slot',
parameters: {
@@ -890,13 +628,7 @@ function register(api: PluginAPI): void {
if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' };
}
if (calendarScheduler instanceof MultiAgentSchedulerHandle) {
const agentId = ctx?.agentId ?? resolveAgentId();
const res = await calendarScheduler.resumeSlot(agentId);
return res.ok
? { success: true, message: 'Slot resumed', slot: res.slot }
: { error: res.error };
}
await calendarScheduler.resumeCurrentSlot();
return { success: true, message: 'Slot resumed' };
},

View File

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

View File

@@ -31,7 +31,6 @@ const OLD_PLUGIN_NAME = 'harborforge-monitor';
const PLUGIN_SRC_DIR = join(__dirname, 'plugin');
const SKILLS_SRC_DIR = join(__dirname, 'skills');
const MONITOR_REPO_URL = 'https://git.hangman-lab.top/zhi/HarborForge.Monitor.git';
const CLI_REPO_URL = 'https://git.hangman-lab.top/zhi/HarborForge.Cli.git';
const args = process.argv.slice(2);
const options = {
@@ -44,7 +43,6 @@ const options = {
installCli: args.includes('--install-cli'),
installMonitor: 'no',
monitorBranch: 'main',
cliBranch: 'main',
};
const profileIdx = args.indexOf('--openclaw-profile-path');
@@ -62,11 +60,6 @@ if (monitorBranchIdx !== -1 && args[monitorBranchIdx + 1]) {
options.monitorBranch = String(args[monitorBranchIdx + 1]);
}
const cliBranchIdx = args.indexOf('--cli-branch');
if (cliBranchIdx !== -1 && args[cliBranchIdx + 1]) {
options.cliBranch = String(args[cliBranchIdx + 1]);
}
function resolveOpenclawPath() {
if (options.openclawProfilePath) return options.openclawProfilePath;
if (process.env.OPENCLAW_PATH) return resolve(process.env.OPENCLAW_PATH);
@@ -323,40 +316,39 @@ async function installCli() {
if (!options.installCli) return;
const totalSteps = 6;
logStep(5, totalSteps, 'Building and installing hf CLI...');
const openclawPath = resolveOpenclawPath();
const binDir = join(openclawPath, 'bin');
mkdirSync(binDir, { recursive: true });
// Clone CLI repo to /tmp, build there, copy artifact out. Mirrors
// installManagedMonitor so the install never depends on a checked-out
// sibling repo at a fixed path.
const tmpDir = join('/tmp', `harborforge-cli-${Date.now()}`);
const hfBinary = join(binDir, 'hf');
// Find CLI source — look for HarborForge.Cli relative to project root
const projectRoot = resolve(__dirname, '..');
const cliDir = join(projectRoot, 'HarborForge.Cli');
if (!existsSync(cliDir)) {
// Try parent directory (monorepo layout)
const monoCliDir = resolve(projectRoot, '..', 'HarborForge.Cli');
if (!existsSync(monoCliDir)) {
logErr(`Cannot find HarborForge.Cli at ${cliDir} or ${monoCliDir}`);
logWarn('Skipping CLI installation');
return;
}
}
const effectiveCliDir = existsSync(cliDir)
? cliDir
: resolve(projectRoot, '..', 'HarborForge.Cli');
log(` Building hf from ${effectiveCliDir}...`, 'blue');
try {
log(` Cloning ${CLI_REPO_URL} (branch ${options.cliBranch}) → ${tmpDir}...`, 'blue');
exec(`git clone --branch ${shellEscape(options.cliBranch)} --depth 1 ${shellEscape(CLI_REPO_URL)} ${shellEscape(tmpDir)}`, { silent: !options.verbose });
// Stamp the binary with the version string the prod CLI surfaces in
// `hf version`. Fall back to a date-only label if rev-parse fails for
// any reason (shallow clone shouldn't, but be defensive).
let versionLabel = `${new Date().toISOString().slice(0, 10)}+install`;
try {
const sha = exec(`git rev-parse --short HEAD`, { cwd: tmpDir, silent: true }).trim();
if (sha) versionLabel = `${new Date().toISOString().slice(0, 10)}+${options.cliBranch}-${sha}`;
} catch { /* keep fallback */ }
log(` Building hf (version=${versionLabel})...`, 'blue');
const ldflags = `-X git.hangman-lab.top/zhi/HarborForge.Cli/internal/commands.Version=${versionLabel}`;
exec(`go build -ldflags ${shellEscape(ldflags)} -o ${shellEscape(hfBinary)} ./cmd/hf`, { cwd: tmpDir, silent: !options.verbose });
const hfBinary = join(binDir, 'hf');
exec(`go build -o ${hfBinary} ./cmd/hf`, { cwd: effectiveCliDir, silent: !options.verbose });
chmodSync(hfBinary, 0o755);
logOk(`hf binary → ${hfBinary} (branch hint: ${options.cliBranch})`);
logOk(`hf binary → ${hfBinary}`);
} catch (err) {
logErr(`Failed to build hf CLI: ${err.message}`);
logWarn('CLI installation failed, plugin still installed');
} finally {
rmSync(tmpDir, { recursive: true, force: true });
}
}