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

Compare commits

base: zhi:main
Branches Tags
zhi:main zhi:refactor/install-cli-clone-from-repo zhi:fix/meta-push-use-cached-api-config zhi:fix/drop-wakeup-ok-token zhi:fix/wakeup-message-no-ack-only zhi:fix/scheduler-module-singleton zhi:fix/multi-agent-scheduler-handle zhi:_main zhi:fix/wake-dedupe-and-contracts zhi:docs/readme-refresh
..
compare: zhi:f6278455435040ccf4f280299908974a80096519
Branches Tags
zhi:main zhi:refactor/install-cli-clone-from-repo zhi:fix/meta-push-use-cached-api-config zhi:fix/drop-wakeup-ok-token zhi:fix/wakeup-message-no-ack-only zhi:fix/scheduler-module-singleton zhi:fix/multi-agent-scheduler-handle zhi:_main zhi:fix/wake-dedupe-and-contracts zhi:docs/readme-refresh

2 Commits
main ... f627845543

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
9 changed files with 96 additions and 1319 deletions
Expand all files Collapse all files

28
plugin/calendar/calendar-bridge.ts
View File

@@ -110,23 +110,6 @@ export class CalendarBridgeClient {
return this.sendBoolean('PATCH', url, update); 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. * 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> { 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 controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), this.timeoutMs); const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
@@ -298,7 +272,7 @@ export class CalendarBridgeClient {
method, method,
headers: { headers: {
'Content-Type': 'application/json', 'Content-Type': 'application/json',
'X-Agent-ID': agentId, 'X-Agent-ID': this.config.agentId,
'X-Claw-Identifier': this.config.clawIdentifier, 'X-Claw-Identifier': this.config.clawIdentifier,
}, },
body: JSON.stringify(body), body: JSON.stringify(body),

240
plugin/calendar/multi-agent-handle.ts
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;
}

481
plugin/index.ts
View File

@@ -14,46 +14,18 @@
import { hostname, freemem, totalmem, uptime, loadavg, platform } from 'node:os'; import { hostname, freemem, totalmem, uptime, loadavg, platform } from 'node:os';
import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry'; import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
import { MultiAgentScheduleCache } from './calendar/schedule-cache.js'; import { MultiAgentScheduleCache } from './calendar/schedule-cache.js';
import { MultiAgentSchedulerHandle } from './calendar/multi-agent-handle.js';
import { getPluginConfig } from './core/config.js'; import { getPluginConfig } from './core/config.js';
import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge.js'; import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge.js';
import type { OpenClawAgentInfo } from './core/openclaw-agents.js'; import type { OpenClawAgentInfo } from './core/openclaw-agents.js';
import { registerGatewayStartHook } from './hooks/gateway-start.js'; import { registerGatewayStartHook } from './hooks/gateway-start.js';
import { registerGatewayStopHook } from './hooks/gateway-stop.js'; import { registerGatewayStopHook } from './hooks/gateway-stop.js';
import { Block as KBBlock } from './tools/kbblock.js';
import { KBClient } from './tools/kbclient.js';
import {
type KBDeps,
createListKBsTool,
createListTopicsTool,
createListFactsTool,
createCacheTool,
createEvictTool,
} from './tools/dynamic-kb.js';
import { import {
createCalendarBridgeClient, createCalendarBridgeClient,
createCalendarScheduler,
CalendarScheduler, CalendarScheduler,
AgentWakeContext,
} from './calendar/index.js'; } 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 { interface PluginAPI {
logger: { logger: {
info: (...args: any[]) => void; info: (...args: any[]) => void;
@@ -83,57 +55,6 @@ interface PluginAPI {
getAgentStatus?: () => Promise<{ status: string } | null>; 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 { function register(api: PluginAPI): void {
const logger = api.logger || { const logger = api.logger || {
info: (...args: any[]) => console.log('[HarborForge]', ...args), info: (...args: any[]) => console.log('[HarborForge]', ...args),
@@ -142,43 +63,6 @@ function register(api: PluginAPI): void {
warn: (...args: any[]) => console.warn('[HarborForge]', ...args), 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() { function resolveConfig() {
return getPluginConfig(api); return getPluginConfig(api);
} }
@@ -186,9 +70,7 @@ function register(api: PluginAPI): void {
/** Resolve agent ID from env, config, or fallback. */ /** Resolve agent ID from env, config, or fallback. */
function resolveAgentId(): string { function resolveAgentId(): string {
if (process.env.AGENT_ID) return process.env.AGENT_ID; if (process.env.AGENT_ID) return process.env.AGENT_ID;
// Read from cached `api.config` first — see pushMetaToMonitor for why const cfg = api.runtime?.config?.loadConfig?.();
// the deprecated `api.runtime?.config?.loadConfig?.()` path is heavy.
const cfg = (api as any).config ?? api.runtime?.config?.loadConfig?.();
return cfg?.agents?.list?.[0]?.id ?? cfg?.agents?.defaults?.id ?? 'unknown'; return cfg?.agents?.list?.[0]?.id ?? cfg?.agents?.defaults?.id ?? 'unknown';
} }
@@ -227,7 +109,7 @@ function register(api: PluginAPI): void {
}, },
openclaw: { openclaw: {
version: api.runtime?.version || api.version || 'unknown', 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(), timestamp: new Date().toISOString(),
}; };
@@ -236,33 +118,13 @@ function register(api: PluginAPI): void {
// Periodic metadata push interval handle // Periodic metadata push interval handle
let metaPushInterval: ReturnType<typeof setInterval> | null = null; let metaPushInterval: ReturnType<typeof setInterval> | null = null;
// (calendarScheduler is module-scope — see top of file for the why. // Calendar scheduler instance
// Tools and lifecycle hooks all reference the same binding so the let calendarScheduler: CalendarScheduler | null = null;
// multi-register/single-start mismatch can't shadow them again.)
/** /**
* Push OpenClaw metadata to the Monitor bridge. * Push OpenClaw metadata to the Monitor bridge.
* This enriches Monitor heartbeats with OpenClaw version/plugin/agent info. * This enriches Monitor heartbeats with OpenClaw version/plugin/agent info.
* Failures are non-fatal — Monitor continues to work without this data. * 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() { async function pushMetaToMonitor() {
const bridgeClient = getBridgeClient(); const bridgeClient = getBridgeClient();
@@ -270,7 +132,7 @@ function register(api: PluginAPI): void {
let agentNames: string[] = []; let agentNames: string[] = [];
try { try {
const cfg = (api as any).config ?? api.runtime?.config?.loadConfig?.(); const cfg = api.runtime?.config?.loadConfig?.();
const agentsList = cfg?.agents?.list; const agentsList = cfg?.agents?.list;
if (Array.isArray(agentsList)) { if (Array.isArray(agentsList)) {
agentNames = agentsList agentNames = agentsList
@@ -281,7 +143,7 @@ function register(api: PluginAPI): void {
const meta: OpenClawMeta = { const meta: OpenClawMeta = {
version: api.runtime?.version || api.version || 'unknown', version: api.runtime?.version || api.version || 'unknown',
plugin_version: '0.3.4', plugin_version: '0.3.1',
agents: agentNames.map(name => ({ name })), agents: agentNames.map(name => ({ name })),
}; };
@@ -386,22 +248,10 @@ function register(api: PluginAPI): void {
)}\n\`\`\``; )}\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 = const wakeupMessage =
`You have due slots. Drive the \`hf-wakeup\` workflow of skill ` + `You have due slots. Follow the \`hf-wakeup\` workflow of skill ` +
`\`hf-hangman-lab\` to completion in this session — read slot ` + `\`hf-hangman-lab\` to proceed. Only reply \`WAKEUP_OK\` in this ` +
`context, call the harborforge_calendar_* tools, route to the ` + `session.${slotBlock}`;
`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}`;
const result = await dispatchInboundMessageWithDispatcher({ const result = await dispatchInboundMessageWithDispatcher({
ctx: { ctx: {
@@ -430,23 +280,42 @@ function register(api: PluginAPI): void {
} }
} }
// (trackSessionCompletion removed — legacy single-agent poll loop that /**
// called calendarScheduler.completeCurrentSlot. The multi-agent path * Track session completion and update slot status accordingly.
// closes slots via the harborforge_calendar_complete tool, driven by */
// the agent itself, not by a timer.) 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. * 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 { function startCalendarScheduler(): void {
if (calendarScheduler) {
logger.info('Calendar scheduler already started, skipping duplicate gateway_start');
return;
}
const live = resolveConfig(); const live = resolveConfig();
// Create bridge client (claw-instance level, not per-agent) // Create bridge client (claw-instance level, not per-agent)
@@ -476,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 // Track wakes already dispatched for a slot in the current sync
// window — the simplified inline scheduler does not PATCH slot // window — the simplified inline scheduler does not PATCH slot
// status server-side, so without dedupe the check loop re-wakes // status server-side, so without dedupe the check loop re-wakes
@@ -600,13 +381,6 @@ function register(api: PluginAPI): void {
// Wake the agent with the slot context inlined // Wake the agent with the slot context inlined
const ok = await wakeAgent(agentId, fresh); const ok = await wakeAgent(agentId, fresh);
if (ok) { 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) { for (const s of fresh) {
const key = `${agentId}::${s.id ?? s.virtual_id ?? s.scheduled_at}`; const key = `${agentId}::${s.id ?? s.virtual_id ?? s.scheduled_at}`;
wakedSlotKeys.add(key); wakedSlotKeys.add(key);
@@ -626,14 +400,14 @@ function register(api: PluginAPI): void {
const syncHandle = setInterval(runSyncReset, SYNC_INTERVAL_MS); const syncHandle = setInterval(runSyncReset, SYNC_INTERVAL_MS);
const checkHandle = setInterval(runCheck, CHECK_INTERVAL_MS); const checkHandle = setInterval(runCheck, CHECK_INTERVAL_MS);
// Install the multi-agent handle so calendar tools resolve per-caller. // Store handles for cleanup (reuse calendarScheduler variable)
calendarScheduler = new MultiAgentSchedulerHandle({ (calendarScheduler as any) = {
bridge: calendarBridge, stop() {
cache: scheduleCache, clearInterval(syncHandle);
syncHandle, clearInterval(checkHandle);
checkHandle, logger.info('Calendar scheduler stopped');
logger, },
}); };
logger.info('Calendar scheduler started (multi-agent sync mode)'); logger.info('Calendar scheduler started (multi-agent sync mode)');
} }
@@ -670,7 +444,7 @@ function register(api: PluginAPI): void {
}); });
// Tool: plugin status // Tool: plugin status
api.registerTool((ctx) => ({ api.registerTool(() => ({
name: 'harborforge_status', name: 'harborforge_status',
description: 'Get HarborForge plugin status and current telemetry snapshot', description: 'Get HarborForge plugin status and current telemetry snapshot',
parameters: { parameters: {
@@ -689,27 +463,13 @@ function register(api: PluginAPI): void {
: { connected: false, error: 'Monitor bridge unreachable' }; : { connected: false, error: 'Monitor bridge unreachable' };
} }
// Get calendar scheduler status. In multi-agent mode `currentSlot` // Get calendar scheduler status
// depends on the caller, so look it up via ctx.agentId. const calendarStatus = calendarScheduler ? {
const callerAgentId = ctx?.agentId ?? resolveAgentId(); running: calendarScheduler.isRunning(),
const calendarStatus = calendarScheduler processing: calendarScheduler.isProcessing(),
? calendarScheduler instanceof MultiAgentSchedulerHandle currentSlot: calendarScheduler.getCurrentSlot(),
? { isRestartPending: calendarScheduler.isRestartPending(),
running: calendarScheduler.isRunning(), } : null;
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;
return { return {
enabled: live.enabled !== false, enabled: live.enabled !== false,
@@ -768,7 +528,7 @@ function register(api: PluginAPI): void {
})); }));
// Tool: calendar slot management // Tool: calendar slot management
api.registerTool((ctx) => ({ api.registerTool(() => ({
name: 'harborforge_calendar_status', name: 'harborforge_calendar_status',
description: 'Get current calendar scheduler status and pending slots', description: 'Get current calendar scheduler status and pending slots',
parameters: { parameters: {
@@ -779,24 +539,10 @@ function register(api: PluginAPI): void {
if (!calendarScheduler) { if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' }; 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 { return {
running: calendarScheduler.isRunning(), running: calendarScheduler.isRunning(),
processing: calendarScheduler.isProcessing(), processing: calendarScheduler.isProcessing(),
mode: 'single-agent',
currentSlot: calendarScheduler.getCurrentSlot(), currentSlot: calendarScheduler.getCurrentSlot(),
state: calendarScheduler.getState(), state: calendarScheduler.getState(),
isRestartPending: calendarScheduler.isRestartPending(), isRestartPending: calendarScheduler.isRestartPending(),
@@ -806,7 +552,7 @@ function register(api: PluginAPI): void {
})); }));
// Tool: complete current slot (for agent to report completion) // Tool: complete current slot (for agent to report completion)
api.registerTool((ctx) => ({ api.registerTool(() => ({
name: 'harborforge_calendar_complete', name: 'harborforge_calendar_complete',
description: 'Complete the current calendar slot with actual duration', description: 'Complete the current calendar slot with actual duration',
parameters: { parameters: {
@@ -823,20 +569,14 @@ function register(api: PluginAPI): void {
if (!calendarScheduler) { if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' }; 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); await calendarScheduler.completeCurrentSlot(params.actualDurationMinutes);
return { success: true, message: 'Slot completed' }; return { success: true, message: 'Slot completed' };
}, },
})); }));
// Tool: abort current slot (for agent to report failure) // Tool: abort current slot (for agent to report failure)
api.registerTool((ctx) => ({ api.registerTool(() => ({
name: 'harborforge_calendar_abort', name: 'harborforge_calendar_abort',
description: 'Abort the current calendar slot', description: 'Abort the current calendar slot',
parameters: { parameters: {
@@ -852,20 +592,14 @@ function register(api: PluginAPI): void {
if (!calendarScheduler) { if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' }; 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); await calendarScheduler.abortCurrentSlot(params.reason);
return { success: true, message: 'Slot aborted' }; return { success: true, message: 'Slot aborted' };
}, },
})); }));
// Tool: pause current slot // Tool: pause current slot
api.registerTool((ctx) => ({ api.registerTool(() => ({
name: 'harborforge_calendar_pause', name: 'harborforge_calendar_pause',
description: 'Pause the current calendar slot', description: 'Pause the current calendar slot',
parameters: { parameters: {
@@ -876,20 +610,14 @@ function register(api: PluginAPI): void {
if (!calendarScheduler) { if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' }; 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(); await calendarScheduler.pauseCurrentSlot();
return { success: true, message: 'Slot paused' }; return { success: true, message: 'Slot paused' };
}, },
})); }));
// Tool: resume current slot // Tool: resume current slot
api.registerTool((ctx) => ({ api.registerTool(() => ({
name: 'harborforge_calendar_resume', name: 'harborforge_calendar_resume',
description: 'Resume the paused calendar slot', description: 'Resume the paused calendar slot',
parameters: { parameters: {
@@ -900,13 +628,7 @@ function register(api: PluginAPI): void {
if (!calendarScheduler) { if (!calendarScheduler) {
return { error: 'Calendar scheduler not running' }; 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(); await calendarScheduler.resumeCurrentSlot();
return { success: true, message: 'Slot resumed' }; return { success: true, message: 'Slot resumed' };
}, },
@@ -938,73 +660,6 @@ function register(api: PluginAPI): void {
}, },
})); }));
// ---- dynamic-kb-* family (DESIGN-DYNAMIC-BLOCK.md §3.3 / §4.4)
// Cross-runtime mirror of HarborForge.PlexumPlugin/internal/tools/kb.go +
// /internal/kbblock + /internal/kbclient. v1 auth = plugin-level apiKey
// via Bearer (per-agent hf-token resolution is a TODO matching the
// Plexum side).
const kbCfg = resolveConfig();
const kbBackendUrl =
typeof kbCfg?.backendUrl === 'string' && kbCfg.backendUrl
? (kbCfg.backendUrl as string)
: 'https://monitor.hangman-lab.top';
const kbApiKey = typeof kbCfg?.apiKey === 'string' ? (kbCfg.apiKey as string) : '';
const kbDeps: KBDeps = {
client: kbApiKey ? new KBClient(kbBackendUrl, kbApiKey) : null,
tokenFor: null,
makeClient: null,
turnFor: () => 0,
};
// Wrap each KB tool factory: pass ctx into execute so cache/evict can
// resolve the per-session kb-block.json path.
const kbFactories = [
createListKBsTool,
createListTopicsTool,
createListFactsTool,
createCacheTool,
createEvictTool,
];
for (const make of kbFactories) {
api.registerTool((ctx: any) => {
const tool = make(kbDeps);
const inner = tool.execute;
tool.execute = async (callId: string, params: any) =>
inner(callId, params, { agentId: ctx?.agentId, sessionId: ctx?.sessionId });
return tool;
});
}
// <kb-block> subblock injection via before_prompt_build hook
// (DESIGN-DYNAMIC-BLOCK.md §2 + §7: openclaw side uses
// appendSystemContext since the hook can't replace baked-in
// <available_skills> precisely). Empty block → no append.
const apiOn = (api as any).on;
if (typeof apiOn === 'function') {
apiOn.call(
api,
'before_prompt_build',
async (_event: any, ctx: any) => {
const agentId = ctx?.agentId;
const sessionId = ctx?.sessionId;
if (!agentId || !sessionId) return undefined;
let body = '';
try {
const block = KBBlock.open(agentId, sessionId);
body = block.render();
} catch (err) {
logger.warn(`kb-block render failed: ${err}`);
return undefined;
}
if (!body) return undefined;
return {
appendSystemContext: `<dynamic-block>\n<kb-block>\n${body}</kb-block>\n</dynamic-block>\n`,
};
},
);
logger.info('HarborForge kb-block subblock hook registered');
}
logger.info('HarborForge plugin registered (id: harbor-forge)'); logger.info('HarborForge plugin registered (id: harbor-forge)');
} }

7
plugin/openclaw.plugin.json
View File

@@ -15,12 +15,7 @@
"harborforge_calendar_abort", "harborforge_calendar_abort",
"harborforge_calendar_pause", "harborforge_calendar_pause",
"harborforge_calendar_resume", "harborforge_calendar_resume",
"harborforge_restart_status", "harborforge_restart_status"
"dynamic-kb-list-kbs",
"dynamic-kb-list-topics",
"dynamic-kb-list-facts",
"dynamic-kb-cache",
"dynamic-kb-evict"
] ]
}, },
"configSchema": { "configSchema": {

2
plugin/package.json
View File

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

278
plugin/tools/dynamic-kb.ts
View File

@@ -1,278 +0,0 @@
// dynamic-kb.ts — 5 host tools (dynamic-kb-list-kbs / list-topics /
// list-facts / cache / evict) implementing the agent-side knowledge-
// base browse + cache flow per DESIGN-DYNAMIC-BLOCK.md §4.4.
//
// Cross-runtime aligned with Plexum's dynmem/kb_tools.go — same tool
// names, same input shapes, same return shapes (so ClawSkills
// workflow text reads identically on either runtime).
//
// Returns ToolResult.content[].text for both ok and error cases. The
// `isError: true` flag surfaces errors to the model rather than RPC-
// failing the tool call.
import { Block as KBBlock } from './kbblock.js';
import { KBClient } from './kbclient.js';
interface ToolCtx {
agentId?: string;
sessionId?: string;
}
interface ToolResult {
content: Array<{ type: 'text'; text: string }>;
isError?: boolean;
}
function ok(text: string): ToolResult {
return { content: [{ type: 'text', text }] };
}
function err(text: string): ToolResult {
return { isError: true, content: [{ type: 'text', text }] };
}
/** Dependencies the 5 KB tools share. Built once in index.ts. */
export interface KBDeps {
/** HF backend KB HTTP client. */
client: KBClient | null;
/** Resolve hf-token for the agent at call time (via secret-mgr). null → no auth */
tokenFor: ((agentId: string) => Promise<string | null>) | null;
/** Build new client given a token (so each call gets fresh per-agent client). */
makeClient: ((token: string) => KBClient) | null;
/** Best-effort current turn number; 0 is acceptable. */
turnFor: (agentId: string) => number;
}
/**
* Resolve a per-agent KBClient. Returns null with reason if no client
* (no agent context / no token / no backend URL).
*/
async function clientFor(deps: KBDeps, ctx: ToolCtx): Promise<{ c: KBClient | null; reason: string }> {
if (!ctx.agentId) return { c: null, reason: 'no agent context' };
if (deps.makeClient && deps.tokenFor) {
const tok = await deps.tokenFor(ctx.agentId);
if (!tok) return { c: null, reason: 'agent has no hf-token in secret-mgr' };
return { c: deps.makeClient(tok), reason: '' };
}
if (deps.client) return { c: deps.client, reason: '' };
return { c: null, reason: 'HF KB backend unavailable' };
}
// ----- 5 tool factories -----
export function createListKBsTool(deps: KBDeps) {
return {
name: 'dynamic-kb-list-kbs',
description: 'List HarborForge Knowledge Bases the agent can access. Optional project-code filter.',
parameters: {
type: 'object',
properties: { 'project-code': { type: 'string' } },
},
async execute(_id: string, params: any, ctxArg?: ToolCtx): Promise<ToolResult> {
const ctx = ctxArg ?? {};
const r = await clientFor(deps, ctx);
if (!r.c) return err('dynamic-kb-list-kbs: ' + r.reason);
const proj = params?.['project-code'];
try {
const kbs = await r.c.listKBs(typeof proj === 'string' ? proj : undefined);
const lines: string[] = [];
if (proj) lines.push(`project: ${proj}`);
lines.push(`kbs: ${kbs.length}`, '');
for (const k of kbs) {
lines.push(`[${k.knowledge_base_code}] ${k.title}`);
lines.push(` ${k.description || ''}`, '');
}
lines.push(`Call dynamic-kb-list-topics({kb-code: "<code>"}) to drill into a KB.`);
return ok(lines.join('\n'));
} catch (e: any) {
return err('dynamic-kb-list-kbs: ' + (e?.message || String(e)));
}
},
};
}
export function createListTopicsTool(deps: KBDeps) {
return {
name: 'dynamic-kb-list-topics',
description: 'List topics in one HF KB by code.',
parameters: {
type: 'object',
properties: { 'kb-code': { type: 'string' } },
required: ['kb-code'],
},
async execute(_id: string, params: any, ctxArg?: ToolCtx): Promise<ToolResult> {
const ctx = ctxArg ?? {};
const r = await clientFor(deps, ctx);
if (!r.c) return err('dynamic-kb-list-topics: ' + r.reason);
const kbCode = String(params?.['kb-code'] ?? '');
if (!kbCode) return err('dynamic-kb-list-topics: kb-code required');
try {
const ts = await r.c.listTopics(kbCode);
const lines = [
`kb: ${kbCode}`,
`topics: ${ts.length}`,
'',
...ts.flatMap((t) => [`[${t.id}] ${t.topic}`, ` ${t.description || ''}`, '']),
`Call dynamic-kb-list-facts({kb-code: "${kbCode}", topic-ids: [<id>, ...]}) to drill into facts.`,
];
return ok(lines.join('\n'));
} catch (e: any) {
return err('dynamic-kb-list-topics: ' + (e?.message || String(e)));
}
},
};
}
export function createListFactsTool(deps: KBDeps) {
return {
name: 'dynamic-kb-list-facts',
description: 'List fact previews (id/topic/title/snippet) in given topics. Feed into dynamic-kb-cache.',
parameters: {
type: 'object',
properties: {
'kb-code': { type: 'string' },
'topic-ids': { type: 'array', items: { type: 'integer' } },
},
required: ['kb-code', 'topic-ids'],
},
async execute(_id: string, params: any, ctxArg?: ToolCtx): Promise<ToolResult> {
const ctx = ctxArg ?? {};
const r = await clientFor(deps, ctx);
if (!r.c) return err('dynamic-kb-list-facts: ' + r.reason);
const kbCode = String(params?.['kb-code'] ?? '');
const topicIds = Array.isArray(params?.['topic-ids']) ? params['topic-ids'].map((x: any) => Number(x)) : [];
if (!kbCode || topicIds.length === 0) {
return err('dynamic-kb-list-facts: kb-code + topic-ids required');
}
try {
const facts = await r.c.listFacts(kbCode, topicIds);
const lines = [
`kb: ${kbCode}`,
`topics: [${topicIds.join(', ')}]`,
`facts: ${facts.length}`,
'',
...facts.flatMap((f) => [
`[${f.id}] (topic ${f.topic_id}/${f.topic_slug}) ${f.title}`,
` ${f.snippet}`,
'',
]),
`Call dynamic-kb-cache({kb-code: "${kbCode}", fact-ids: [<id>, ...]}) to commit selected facts to your kb-block.`,
];
return ok(lines.join('\n'));
} catch (e: any) {
return err('dynamic-kb-list-facts: ' + (e?.message || String(e)));
}
},
};
}
export function createCacheTool(deps: KBDeps) {
return {
name: 'dynamic-kb-cache',
description: 'Cache KB facts into your per-session kb-block (visible next turn).',
parameters: {
type: 'object',
properties: {
'kb-code': { type: 'string' },
'fact-ids': { type: 'array', items: { type: 'integer' } },
'previous-dynamic-id': { type: 'string' },
},
required: ['kb-code', 'fact-ids'],
},
async execute(_id: string, params: any, ctxArg?: ToolCtx): Promise<ToolResult> {
const ctx = ctxArg ?? {};
if (!ctx.agentId || !ctx.sessionId) {
return err('dynamic-kb-cache: no per-session context');
}
const r = await clientFor(deps, ctx);
if (!r.c) return err('dynamic-kb-cache: ' + r.reason);
const kbCode = String(params?.['kb-code'] ?? '');
const factIds = Array.isArray(params?.['fact-ids']) ? params['fact-ids'].map((x: any) => Number(x)) : [];
if (!kbCode || factIds.length === 0) {
return err('dynamic-kb-cache: kb-code + fact-ids required');
}
let block: KBBlock;
try {
block = KBBlock.open(ctx.agentId, ctx.sessionId);
} catch (e: any) {
return err('dynamic-kb-cache: open block: ' + (e?.message || String(e)));
}
const toFetch: number[] = [];
const alreadyCached: number[] = [];
for (const id of factIds) {
if (block.has(id)) alreadyCached.push(id);
else toFetch.push(id);
}
let fetched: Array<{ id: number; kb_code: string; topic_slug: string; content: string }> = [];
if (toFetch.length > 0) {
try {
fetched = await r.c.getFacts(kbCode, toFetch);
} catch (e: any) {
return err('dynamic-kb-cache: ' + (e?.message || String(e)));
}
}
const turn = deps.turnFor(ctx.agentId);
const fetchedByID = new Map(fetched.map((f) => [f.id, f]));
const added: number[] = [];
for (const id of toFetch) {
const f = fetchedByID.get(id);
if (!f) continue;
if (block.add(f.id, kbCode, f.topic_slug, f.content, turn)) added.push(f.id);
}
try {
block.save();
} catch (e: any) {
return err('dynamic-kb-cache: save: ' + (e?.message || String(e)));
}
const missing = toFetch.filter((id) => !added.includes(id));
return ok(
JSON.stringify({
added: added.sort((a, b) => a - b),
already_cached: alreadyCached.sort((a, b) => a - b),
missing: missing.length ? missing.sort((a, b) => a - b) : undefined,
note: 'Newly cached facts are available starting your next turn.',
}),
);
},
};
}
export function createEvictTool(_deps: KBDeps) {
return {
name: 'dynamic-kb-evict',
description: "Remove cached facts from your kb-block. Takes effect next turn.",
parameters: {
type: 'object',
properties: { 'fact-ids': { type: 'array', items: { type: 'integer' } } },
required: ['fact-ids'],
},
async execute(_id: string, params: any, ctxArg?: ToolCtx): Promise<ToolResult> {
const ctx = ctxArg ?? {};
if (!ctx.agentId || !ctx.sessionId) {
return err('dynamic-kb-evict: no per-session context');
}
const factIds = Array.isArray(params?.['fact-ids']) ? params['fact-ids'].map((x: any) => Number(x)) : [];
if (factIds.length === 0) return err('dynamic-kb-evict: fact-ids required');
let block: KBBlock;
try {
block = KBBlock.open(ctx.agentId, ctx.sessionId);
} catch (e: any) {
return err('dynamic-kb-evict: open block: ' + (e?.message || String(e)));
}
const evicted = block.remove(factIds);
try {
block.save();
} catch (e: any) {
return err('dynamic-kb-evict: save: ' + (e?.message || String(e)));
}
const notCached = factIds.filter((id: number) => !evicted.includes(id));
return ok(
JSON.stringify({
evicted: evicted.sort((a, b) => a - b),
not_cached: notCached.length ? notCached.sort((a: number, b: number) => a - b) : undefined,
note: 'Evictions take effect starting your next turn.',
}),
);
},
};
}

155
plugin/tools/kbblock.ts
View File

@@ -1,155 +0,0 @@
// kbblock.ts — TypeScript mirror of HarborForge.PlexumPlugin's
// internal/kbblock package. Per-session storage of HarborForge KB
// facts the agent has cached, rendered as <kb-fact id=N kb=<code>
// source=topic:<slug>>content</kb-fact> per DESIGN-DYNAMIC-BLOCK.md
// §3.3 / §4.4.
//
// Storage location:
//
// <OPENCLAW_PATH>/agents/<agentId>/sessions/<sessionId>/plugins/
// harbor-forge/kb-block.json
//
// Fade NOT applied in v1 (§9 #3 placeholder; defer until prod data).
// Cross-runtime aligned with Plexum kbblock.
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
export interface Entry {
id: number; // HF backend DB primary key
kb_code: string; // e.g. "KB-PAYROT"
source_topic: string; // human slug from HF, e.g. "debugging"
content: string;
insert_seq: number;
added_at_turn: number;
last_refresh_at_turn: number;
}
interface BlockShape {
version: number;
next_seq: number;
entries: Entry[];
}
const FILE_NAME = 'kb-block.json';
const VERSION = 1;
function openclawRoot(): string {
const env = process.env.OPENCLAW_PATH;
if (env) return env;
const home = process.env.HOME || os.homedir();
return path.join(home, '.openclaw');
}
/** sessions/<sid>/plugins/harbor-forge path under openclaw profile. */
export function sessionDir(agentId: string, sessionId: string): string {
return path.join(openclawRoot(), 'agents', agentId, 'sessions', sessionId, 'plugins', 'harbor-forge');
}
export function blockPath(agentId: string, sessionId: string): string {
return path.join(sessionDir(agentId, sessionId), FILE_NAME);
}
/** Block is the in-memory representation. Cheap to Open + Save per call. */
export class Block {
private readonly path: string;
next_seq: number = 1;
entries: Entry[] = [];
private constructor(blockPath: string) { this.path = blockPath; }
/** Open from disk (missing file → empty block). Throws on parse error. */
static open(agentId: string, sessionId: string): Block {
if (!agentId || !sessionId) {
throw new Error('kbblock.open: agentId + sessionId required');
}
const b = new Block(blockPath(agentId, sessionId));
try {
const raw = fs.readFileSync(b.path, 'utf8');
if (raw.trim().length === 0) return b;
const data = JSON.parse(raw) as Partial<BlockShape>;
if (data.next_seq && data.next_seq > 0) b.next_seq = data.next_seq;
if (Array.isArray(data.entries)) b.entries = data.entries;
} catch (err: any) {
if (err?.code === 'ENOENT') return b;
throw err;
}
return b;
}
len(): number { return this.entries.length; }
has(id: number): boolean {
return this.entries.some((e) => e.id === id);
}
/** Add new entry. Returns it; null on duplicate (silent no-op per §9 #4). */
add(id: number, kb_code: string, source_topic: string, content: string, at_turn: number): Entry | null {
if (this.has(id)) return null;
const e: Entry = {
id, kb_code, source_topic, content,
insert_seq: this.next_seq,
added_at_turn: at_turn,
last_refresh_at_turn: at_turn,
};
this.next_seq += 1;
this.entries.push(e);
return e;
}
/** Remove given IDs. Returns IDs actually removed. */
remove(ids: number[]): number[] {
const want = new Set(ids);
const removed: number[] = [];
this.entries = this.entries.filter((e) => {
if (want.has(e.id)) {
removed.push(e.id);
return false;
}
return true;
});
return removed;
}
lookup(id: number): Entry | undefined {
return this.entries.find((e) => e.id === id);
}
/** Atomic save (tmp+rename, 0600). Empty block with no prior file = no-op. */
save(): void {
if (this.entries.length === 0) {
if (!fs.existsSync(this.path)) return;
}
fs.mkdirSync(path.dirname(this.path), { recursive: true });
const payload: BlockShape = {
version: VERSION,
next_seq: this.next_seq,
entries: this.entries,
};
const tmp = this.path + '.tmp';
fs.writeFileSync(tmp, JSON.stringify(payload, null, 2), { mode: 0o600 });
fs.renameSync(tmp, this.path);
}
/**
* Render the <kb-block> inner body — flat sequence of
* <kb-fact id=N kb=<code> source=topic:<slug>>content</kb-fact>
* ordered by insert_seq (§9 #4). Empty block → "".
*/
render(): string {
if (this.entries.length === 0) return '';
const ordered = [...this.entries].sort((a, b) => a.insert_seq - b.insert_seq);
const lines: string[] = [];
ordered.forEach((e, i) => {
if (i > 0) lines.push('');
let head = `<kb-fact id=${e.id} kb=${e.kb_code}`;
if (e.source_topic) head += ` source=topic:${e.source_topic}`;
head += '>';
lines.push(head);
lines.push(e.content);
lines.push('</kb-fact>');
});
return lines.join('\n') + '\n';
}
}

166
plugin/tools/kbclient.ts
View File

@@ -1,166 +0,0 @@
// kbclient.ts — TypeScript HTTP client for HarborForge.Backend KB
// REST routes. Mirrors HarborForge.PlexumPlugin/internal/kbclient.
// Routes verified against app/api/routers/knowledge.py:
//
// GET /knowledge-bases[?project=<code>] list KBs
// GET /knowledge-bases/{id|code}/topics list topics in a KB
// GET /knowledge-bases/{id|code}/tree full hierarchy
// GET /knowledge-facts/{id} single fact
//
// Auth: per-agent HF token (looked up via secret-mgr by caller; this
// client takes a pre-resolved token string). Cross-runtime parity
// note: Plexum client uses plugin-level APIKey from config because
// the Plexum SDK can't reach secret-mgr; openclaw side has agent
// context so we go per-agent here.
export interface KBSummary {
id: number;
knowledge_base_code: string;
title: string;
description: string;
}
export interface TopicSummary {
id: number;
topic: string;
description: string;
}
export interface FactSummary {
id: number;
topic_id: number;
topic_slug: string;
title: string;
snippet: string;
}
export interface Fact {
id: number;
kb_code: string;
topic_slug: string;
content: string;
}
interface TreeNode {
id: number;
topic?: string;
category?: string;
title?: string;
content?: string;
categories?: TreeNode[];
facts?: TreeNode[];
}
interface KBTree {
knowledge_base_code: string;
topics: TreeNode[];
}
export class KBClient {
private readonly baseUrl: string;
private readonly token: string;
constructor(baseUrl: string, token: string) {
this.baseUrl = baseUrl.replace(/\/$/, '');
this.token = token;
}
async listKBs(projectCode?: string): Promise<KBSummary[]> {
let path = '/knowledge-bases';
if (projectCode) path += '?project=' + encodeURIComponent(projectCode);
return this.get<KBSummary[]>(path);
}
async listTopics(kbCode: string): Promise<TopicSummary[]> {
if (!kbCode) throw new Error('kbclient: kb-code required');
return this.get<TopicSummary[]>('/knowledge-bases/' + encodeURIComponent(kbCode) + '/topics');
}
/** ListFacts pulls the tree once + flattens facts under topic-ids client-side. */
async listFacts(kbCode: string, topicIds: number[]): Promise<FactSummary[]> {
if (!kbCode) throw new Error('kbclient: kb-code required');
if (!topicIds || topicIds.length === 0) throw new Error('kbclient: topic-ids required');
const tree = await this.get<KBTree>('/knowledge-bases/' + encodeURIComponent(kbCode) + '/tree');
const wantTopic = new Set(topicIds);
const out: FactSummary[] = [];
for (const topic of tree.topics || []) {
if (!wantTopic.has(topic.id)) continue;
this.walkFactsInto(out, topic.id, topic.topic || '', topic.categories || [], topic.facts || []);
}
return out;
}
private walkFactsInto(
out: FactSummary[],
topicId: number,
topicSlug: string,
cats: TreeNode[],
facts: TreeNode[],
): void {
for (const f of facts) {
out.push({
id: f.id,
topic_id: topicId,
topic_slug: topicSlug,
title: f.title || '',
snippet: snippet(f.content || '', 120),
});
}
for (const c of cats) {
this.walkFactsInto(out, topicId, topicSlug, c.categories || [], c.facts || []);
}
}
/** GetFacts pulls each fact's full body. Backend has no batch route. */
async getFacts(kbCode: string, factIds: number[]): Promise<Fact[]> {
if (!kbCode) throw new Error('kbclient: kb-code required');
const out: Fact[] = [];
for (const id of factIds) {
try {
const node = await this.get<{ id: number; title: string; content: string; topic: string }>(
'/knowledge-facts/' + id,
);
out.push({
id: node.id,
kb_code: kbCode,
topic_slug: node.topic || '',
content: node.content || '',
});
} catch (err: any) {
if (err?.code === 404) continue; // skip missing
throw err;
}
}
return out;
}
private async get<T>(p: string): Promise<T> {
const res = await fetch(this.baseUrl + p, {
method: 'GET',
headers: {
Accept: 'application/json',
...(this.token ? { Authorization: 'Bearer ' + this.token } : {}),
},
});
if (res.status === 404) {
const e: any = new Error(`GET ${p}: 404 not found`);
e.code = 404;
throw e;
}
if (!res.ok) {
const body = await res.text().catch(() => '');
throw new Error(`GET ${p}: HTTP ${res.status}: ${truncate(body, 200)}`);
}
if (res.status === 204) return undefined as T;
return (await res.json()) as T;
}
}
function snippet(s: string, n: number): string {
s = s.trim();
return s.length <= n ? s : s.slice(0, n) + '...';
}
function truncate(s: string, n: number): string {
return s.length > n ? s.slice(0, n) + '...' : s;
}

52
scripts/install.mjs
View File

@@ -31,7 +31,6 @@ const OLD_PLUGIN_NAME = 'harborforge-monitor';
const PLUGIN_SRC_DIR = join(__dirname, 'plugin'); const PLUGIN_SRC_DIR = join(__dirname, 'plugin');
const SKILLS_SRC_DIR = join(__dirname, 'skills'); const SKILLS_SRC_DIR = join(__dirname, 'skills');
const MONITOR_REPO_URL = 'https://git.hangman-lab.top/zhi/HarborForge.Monitor.git'; 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 args = process.argv.slice(2);
const options = { const options = {
@@ -44,7 +43,6 @@ const options = {
installCli: args.includes('--install-cli'), installCli: args.includes('--install-cli'),
installMonitor: 'no', installMonitor: 'no',
monitorBranch: 'main', monitorBranch: 'main',
cliBranch: 'main',
}; };
const profileIdx = args.indexOf('--openclaw-profile-path'); const profileIdx = args.indexOf('--openclaw-profile-path');
@@ -62,11 +60,6 @@ if (monitorBranchIdx !== -1 && args[monitorBranchIdx + 1]) {
options.monitorBranch = String(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() { function resolveOpenclawPath() {
if (options.openclawProfilePath) return options.openclawProfilePath; if (options.openclawProfilePath) return options.openclawProfilePath;
if (process.env.OPENCLAW_PATH) return resolve(process.env.OPENCLAW_PATH); if (process.env.OPENCLAW_PATH) return resolve(process.env.OPENCLAW_PATH);
@@ -328,35 +321,34 @@ async function installCli() {
const binDir = join(openclawPath, 'bin'); const binDir = join(openclawPath, 'bin');
mkdirSync(binDir, { recursive: true }); mkdirSync(binDir, { recursive: true });
// Clone CLI repo to /tmp, build there, copy artifact out. Mirrors // Find CLI source — look for HarborForge.Cli relative to project root
// installManagedMonitor so the install never depends on a checked-out const projectRoot = resolve(__dirname, '..');
// sibling repo at a fixed path. const cliDir = join(projectRoot, 'HarborForge.Cli');
const tmpDir = join('/tmp', `harborforge-cli-${Date.now()}`);
const hfBinary = join(binDir, 'hf'); 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 { try {
log(` Cloning ${CLI_REPO_URL} (branch ${options.cliBranch}) → ${tmpDir}...`, 'blue'); const hfBinary = join(binDir, 'hf');
exec(`git clone --branch ${shellEscape(options.cliBranch)} --depth 1 ${shellEscape(CLI_REPO_URL)} ${shellEscape(tmpDir)}`, { silent: !options.verbose }); exec(`go build -o ${hfBinary} ./cmd/hf`, { cwd: effectiveCliDir, 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 });
chmodSync(hfBinary, 0o755); chmodSync(hfBinary, 0o755);
logOk(`hf binary → ${hfBinary} (branch hint: ${options.cliBranch})`); logOk(`hf binary → ${hfBinary}`);
} catch (err) { } catch (err) {
logErr(`Failed to build hf CLI: ${err.message}`); logErr(`Failed to build hf CLI: ${err.message}`);
logWarn('CLI installation failed, plugin still installed'); logWarn('CLI installation failed, plugin still installed');
} finally {
rmSync(tmpDir, { recursive: true, force: true });
} }
} }