Compare commits
6 Commits
main
...
065b0d3da3
| Author | SHA1 | Date | |
|---|---|---|---|
| 065b0d3da3 | |||
|
afb8b25558 | ||
| 98e663a19b | |||
|
|
d5cea9a44d | ||
| f627845543 | |||
|
|
b878fa2a41 |
341
plugin/index.ts
341
plugin/index.ts
@@ -20,18 +20,6 @@ import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge.js
|
||||
import type { OpenClawAgentInfo } from './core/openclaw-agents.js';
|
||||
import { registerGatewayStartHook } from './hooks/gateway-start.js';
|
||||
import { registerGatewayStopHook } from './hooks/gateway-stop.js';
|
||||
import { Block as KBBlock } from './tools/kbblock.js';
|
||||
import { defaultFadeParams } from './tools/fade.js';
|
||||
import { bumpTurnForSession, currentTurnForSession } from './tools/turn-tracker.js';
|
||||
import { KBClient } from './tools/kbclient.js';
|
||||
import {
|
||||
type KBDeps,
|
||||
createListKBsTool,
|
||||
createListTopicsTool,
|
||||
createListFactsTool,
|
||||
createCacheTool,
|
||||
createEvictTool,
|
||||
} from './tools/dynamic-kb.js';
|
||||
import {
|
||||
createCalendarBridgeClient,
|
||||
CalendarScheduler,
|
||||
@@ -85,57 +73,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),
|
||||
@@ -144,43 +81,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);
|
||||
}
|
||||
@@ -188,9 +88,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';
|
||||
}
|
||||
|
||||
@@ -229,7 +127,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.3', // Bumped for PLG-CAL-004
|
||||
},
|
||||
timestamp: new Date().toISOString(),
|
||||
};
|
||||
@@ -246,25 +144,6 @@ function register(api: PluginAPI): void {
|
||||
* 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();
|
||||
@@ -272,7 +151,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
|
||||
@@ -283,7 +162,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.3',
|
||||
agents: agentNames.map(name => ({ name })),
|
||||
};
|
||||
|
||||
@@ -388,22 +267,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: {
|
||||
@@ -478,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
|
||||
@@ -940,112 +719,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: per-agent hf-token
|
||||
// resolved via secret-mgr (matches the rest of the Hangman-Lab
|
||||
// openclaw plugins). Falls back to plugin-level apiKey when no
|
||||
// per-agent token is configured.
|
||||
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: async (agentId: string): Promise<string | null> => {
|
||||
// Per-agent hf-token via secret-mgr (decision #20 mirror).
|
||||
// secret-mgr enforces AGENT_VERIFY + AGENT_WORKSPACE + AGENT_ID
|
||||
// (pcexec contract); for get-secret it indexes the store by
|
||||
// AGENT_ID alone, so AGENT_WORKSPACE only needs to be a syntactic
|
||||
// placeholder. openclaw's parent process doesn't carry these
|
||||
// env vars, so we synthesize them per-call.
|
||||
try {
|
||||
const { spawnSync } = await import('node:child_process');
|
||||
const res = spawnSync('secret-mgr', ['get-secret', '--key', 'hf-token'], {
|
||||
env: {
|
||||
...process.env,
|
||||
AGENT_VERIFY: 'IF YOU ARE AN AGENT/MODEL, YOU SHOULD NEVER TOUCH THIS ENV VARIABLE',
|
||||
AGENT_ID: agentId,
|
||||
AGENT_WORKSPACE: `/root/.openclaw/workspace/workspace-${agentId}`,
|
||||
},
|
||||
encoding: 'utf8',
|
||||
timeout: 5000,
|
||||
});
|
||||
if (res.status === 0 && res.stdout.trim()) return res.stdout.trim();
|
||||
return null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
},
|
||||
makeClient: (token: string) => new KBClient(kbBackendUrl, token),
|
||||
turnFor: (sessionId: string) => currentTurnForSession(sessionId),
|
||||
};
|
||||
|
||||
// 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).
|
||||
//
|
||||
// Per-turn fade: bump the session turn counter, then tick
|
||||
// (dropping entries past the m% threshold) + renderFaded so the
|
||||
// rendered text shows accumulated underscore masking. The Plexum
|
||||
// mirror runs the same algorithm inside RenderDynamicSubblock.
|
||||
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);
|
||||
const turn = bumpTurnForSession(sessionId, block);
|
||||
const fadeParams = defaultFadeParams();
|
||||
const dropped = block.tick(turn, fadeParams);
|
||||
if (dropped.length > 0) {
|
||||
logger.info(
|
||||
`kb-block fade tick agent=${agentId} session=${sessionId} dropped=[${dropped.join(',')}]`,
|
||||
);
|
||||
block.save();
|
||||
}
|
||||
body = block.renderFaded(turn, fadeParams);
|
||||
} 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)');
|
||||
}
|
||||
|
||||
|
||||
@@ -15,12 +15,7 @@
|
||||
"harborforge_calendar_abort",
|
||||
"harborforge_calendar_pause",
|
||||
"harborforge_calendar_resume",
|
||||
"harborforge_restart_status",
|
||||
"dynamic-kb-list-kbs",
|
||||
"dynamic-kb-list-topics",
|
||||
"dynamic-kb-list-facts",
|
||||
"dynamic-kb-cache",
|
||||
"dynamic-kb-evict"
|
||||
"harborforge_restart_status"
|
||||
]
|
||||
},
|
||||
"configSchema": {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "harbor-forge-plugin",
|
||||
"version": "0.3.4",
|
||||
"version": "0.3.3",
|
||||
"description": "OpenClaw plugin for HarborForge monitor bridge and CLI integration",
|
||||
"type": "module",
|
||||
"main": "dist/index.js",
|
||||
|
||||
@@ -1,283 +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 for a session; 0 is acceptable.
|
||||
* Wired against the same per-session counter that the
|
||||
* before_prompt_build hook bumps, so a fact added during turn N
|
||||
* reads back at d=0 on turn N+1.
|
||||
*/
|
||||
turnFor: (sessionId: 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.sessionId);
|
||||
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.',
|
||||
}),
|
||||
);
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -1,144 +0,0 @@
|
||||
// fade.ts — TypeScript port of Plexum-sdk-go/fade. Deterministic fade-
|
||||
// out for kb-block / future subblock entries. Matches Plexum decision
|
||||
// #30 (n=5/w=10/m=70 default) so cross-runtime behaviour stays
|
||||
// identical when ports are compared.
|
||||
//
|
||||
// The algorithm:
|
||||
// - For elapsed `d <= n` turns since last_refresh, content unchanged
|
||||
// - For d > n: ticks = d - n; each tick masks ceil(w%) of the
|
||||
// currently-unmasked maskable-rune positions with `_`. Mask set is
|
||||
// cumulative across ticks. PRNG is seeded by (entrySeed ^ tick),
|
||||
// so the masking pattern is reproducible across processes.
|
||||
// - Tick drops the entry when underscore_ratio > m% of maskable.
|
||||
//
|
||||
// Maskable runes (matches Go source):
|
||||
// - ASCII alphanumerics [0-9A-Za-z]
|
||||
// - CJK ideographs (U+4E00–U+9FFF)
|
||||
// - Hiragana (U+3040–U+309F) + Katakana (U+30A0–U+30FF)
|
||||
// - Hangul syllables (U+AC00–U+D7A3)
|
||||
// Everything else (whitespace, punctuation, XML structure characters)
|
||||
// stays unmodified so the rendered XML keeps parseable shape.
|
||||
|
||||
export interface FadeParams {
|
||||
n: number; // safe-period turns
|
||||
w: number; // % maskable chars masked per tick
|
||||
m: number; // % drop threshold on underscore_ratio
|
||||
}
|
||||
|
||||
export interface FadeResult {
|
||||
rendered: string;
|
||||
maskedCount: number;
|
||||
totalMaskable: number;
|
||||
}
|
||||
|
||||
export function defaultFadeParams(): FadeParams {
|
||||
return { n: 5, w: 10, m: 70 };
|
||||
}
|
||||
|
||||
/** shouldDrop returns true iff the entry's underscore ratio crosses m%. */
|
||||
export function shouldDrop(r: FadeResult, params: FadeParams): boolean {
|
||||
if (r.totalMaskable === 0) return false;
|
||||
return r.maskedCount * 100 > params.m * r.totalMaskable;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fade computes the rendered form of `content` given the entry seed +
|
||||
* elapsed turns since last refresh.
|
||||
*/
|
||||
export function fade(content: string, seed: number | bigint, d: number, params: FadeParams): FadeResult {
|
||||
const runes = Array.from(content); // surrogate-pair safe
|
||||
const maskable: number[] = [];
|
||||
for (let i = 0; i < runes.length; i++) {
|
||||
if (isMaskable(runes[i])) maskable.push(i);
|
||||
}
|
||||
if (d <= params.n) {
|
||||
return { rendered: content, maskedCount: 0, totalMaskable: maskable.length };
|
||||
}
|
||||
const ticks = d - params.n;
|
||||
const masked = positionsToMaskCumulative(maskable, BigInt(seed), ticks, params.w);
|
||||
return {
|
||||
rendered: applyUnderscores(runes, masked),
|
||||
maskedCount: masked.length,
|
||||
totalMaskable: maskable.length,
|
||||
};
|
||||
}
|
||||
|
||||
// ---- helpers ----
|
||||
|
||||
function isMaskable(s: string): boolean {
|
||||
if (s.length === 0) return false;
|
||||
// For surrogate pairs, take the first code point.
|
||||
const cp = s.codePointAt(0);
|
||||
if (cp === undefined) return false;
|
||||
if (cp >= 0x30 && cp <= 0x39) return true; // 0-9
|
||||
if ((cp >= 0x41 && cp <= 0x5A) || (cp >= 0x61 && cp <= 0x7A)) return true; // A-Z a-z
|
||||
if (cp >= 0x4E00 && cp <= 0x9FFF) return true; // CJK Unified Ideographs
|
||||
if (cp >= 0x3040 && cp <= 0x309F) return true; // Hiragana
|
||||
if (cp >= 0x30A0 && cp <= 0x30FF) return true; // Katakana
|
||||
if (cp >= 0xAC00 && cp <= 0xD7A3) return true; // Hangul syllables
|
||||
return false;
|
||||
}
|
||||
|
||||
function positionsToMaskCumulative(maskable: number[], seed: bigint, ticks: number, w: number): number[] {
|
||||
if (maskable.length === 0 || ticks <= 0 || w <= 0) return [];
|
||||
const used = new Set<number>();
|
||||
const result: number[] = [];
|
||||
for (let tick = 1; tick <= ticks; tick++) {
|
||||
const remaining = maskable.length - used.size;
|
||||
if (remaining === 0) break;
|
||||
let target = Math.ceil((w * remaining) / 100);
|
||||
if (target < 1) target = 1;
|
||||
if (target > remaining) target = remaining;
|
||||
const unmasked: number[] = [];
|
||||
for (const p of maskable) {
|
||||
if (!used.has(p)) unmasked.push(p);
|
||||
}
|
||||
// Deterministic shuffle using a tick-specific seed.
|
||||
const tickSeed = seed ^ BigInt(tick);
|
||||
shuffleDeterministic(unmasked, tickSeed);
|
||||
for (let i = 0; i < target; i++) {
|
||||
used.add(unmasked[i]);
|
||||
result.push(unmasked[i]);
|
||||
}
|
||||
}
|
||||
result.sort((a, b) => a - b);
|
||||
return result;
|
||||
}
|
||||
|
||||
function applyUnderscores(runes: string[], masked: number[]): string {
|
||||
if (masked.length === 0) return runes.join('');
|
||||
const maskSet = new Set(masked);
|
||||
let out = '';
|
||||
for (let i = 0; i < runes.length; i++) {
|
||||
out += maskSet.has(i) ? '_' : runes[i];
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fisher-Yates shuffle using a Mulberry32-style xorshift PRNG seeded
|
||||
* by `seed`. Deterministic for the same seed input.
|
||||
*
|
||||
* Note: the Go source uses math/rand.NewSource(seed).Shuffle, which
|
||||
* uses a different PRNG algorithm. So the SAME (seed, tick) on Go vs
|
||||
* TS will produce different mask positions. That's acceptable for v1
|
||||
* because no cross-runtime comparison of rendered fade is expected;
|
||||
* each runtime fades its own session-local kb-block independently.
|
||||
* If future use cases need cross-runtime parity, port Go's rand
|
||||
* algorithm to TS (~50 LOC).
|
||||
*/
|
||||
function shuffleDeterministic<T>(arr: T[], seed: bigint): void {
|
||||
// Mulberry32 needs a u32 seed.
|
||||
let s = Number(seed & 0xFFFFFFFFn) >>> 0;
|
||||
const rng = () => {
|
||||
s = (s + 0x6D2B79F5) >>> 0;
|
||||
let t = s;
|
||||
t = Math.imul(t ^ (t >>> 15), t | 1);
|
||||
t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
|
||||
return ((t ^ (t >>> 14)) >>> 0) / 0x100000000;
|
||||
};
|
||||
for (let i = arr.length - 1; i > 0; i--) {
|
||||
const j = Math.floor(rng() * (i + 1));
|
||||
[arr[i], arr[j]] = [arr[j], arr[i]];
|
||||
}
|
||||
}
|
||||
@@ -1,196 +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 algorithm wired in v0.3 via turn-tracker.ts: the
|
||||
// before_prompt_build hook bumps a per-session counter (seeded from
|
||||
// max(entry.last_refresh_at_turn) on the first touch after plugin
|
||||
// restart) and calls tick() + renderFaded() each turn. The Plexum
|
||||
// mirror runs the same algorithm inside RenderDynamicSubblock.
|
||||
|
||||
import * as fs from 'node:fs';
|
||||
import * as os from 'node:os';
|
||||
import * as path from 'node:path';
|
||||
import { fade, shouldDrop, type FadeParams } from './fade.js';
|
||||
|
||||
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;
|
||||
seed: number; // PRNG seed for fade — generated at add() time
|
||||
}
|
||||
|
||||
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,
|
||||
seed: Math.floor(Math.random() * 0x7FFFFFFF),
|
||||
};
|
||||
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 → "". No fade applied.
|
||||
*/
|
||||
render(): string {
|
||||
return this.renderInner(null);
|
||||
}
|
||||
|
||||
/**
|
||||
* RenderFaded mirrors render() but applies fade() per entry given
|
||||
* currentTurn + params. Used by the before_prompt_build hook (turn
|
||||
* source: tools/turn-tracker.ts).
|
||||
*/
|
||||
renderFaded(currentTurn: number, params: FadeParams): string {
|
||||
return this.renderInner((e) => fade(e.content, e.seed, currentTurn - e.last_refresh_at_turn, params).rendered);
|
||||
}
|
||||
|
||||
private renderInner(transform: ((e: Entry) => string) | null): 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(transform ? transform(e) : e.content);
|
||||
lines.push('</kb-fact>');
|
||||
});
|
||||
return lines.join('\n') + '\n';
|
||||
}
|
||||
|
||||
/**
|
||||
* Tick applies fade tick — drops entries whose underscore ratio
|
||||
* crossed the m% threshold. Returns IDs dropped. Caller must
|
||||
* save() after.
|
||||
*/
|
||||
tick(currentTurn: number, params: FadeParams): number[] {
|
||||
if (this.entries.length === 0) return [];
|
||||
const dropped: number[] = [];
|
||||
const kept: Entry[] = [];
|
||||
for (const e of this.entries) {
|
||||
const d = currentTurn - e.last_refresh_at_turn;
|
||||
const r = fade(e.content, e.seed, d, params);
|
||||
if (shouldDrop(r, params)) {
|
||||
dropped.push(e.id);
|
||||
} else {
|
||||
kept.push(e);
|
||||
}
|
||||
}
|
||||
this.entries = kept;
|
||||
return dropped;
|
||||
}
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
@@ -1,62 +0,0 @@
|
||||
// turn-tracker.ts — per-session monotonic turn counter for KB fade.
|
||||
//
|
||||
// The openclaw `before_prompt_build` hook does not expose currentTurn
|
||||
// to plugins (verified against the SDK hook-types: PluginHookAgentContext
|
||||
// has agentId/sessionId/workspaceDir/... but no turn). To make fade
|
||||
// effective, we maintain a small Map<sessionId, turn> that increments
|
||||
// once per before_prompt_build fire. The `dynamic-kb-cache` tool reads
|
||||
// the same counter so each new Entry's `last_refresh_at_turn` is
|
||||
// consistent with the hook's view of the clock.
|
||||
//
|
||||
// Restart safety: in-memory counters reset to 0 on plugin reload, but
|
||||
// `seedFromBlock` is called the first time we touch a given session
|
||||
// during a hook; it scans the loaded block's entries and seeds the
|
||||
// counter to max(last_refresh_at_turn). The next bump then yields a
|
||||
// strictly-greater turn, so existing entries keep their accumulated
|
||||
// fade distance instead of regressing to d=0.
|
||||
//
|
||||
// Process-local only. The Plexum side keeps the same semantics in Go
|
||||
// (it has currentTurn from the host).
|
||||
|
||||
import type { Block } from './kbblock.js';
|
||||
|
||||
const counters = new Map<string, number>();
|
||||
|
||||
/**
|
||||
* Return the latest turn assigned to this session, or 0 if untouched.
|
||||
* `dynamic-kb-cache` uses this for `at_turn` on Block.add so a fact
|
||||
* cached during turn N reads back at d=0 on turn N+1.
|
||||
*/
|
||||
export function currentTurnForSession(sessionId: string): number {
|
||||
if (!sessionId) return 0;
|
||||
return counters.get(sessionId) ?? 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Increment the counter for this session and return the new value.
|
||||
* If the counter is unset (first hook after plugin start), seed it to
|
||||
* max(entry.last_refresh_at_turn) so restart doesn't regress fade.
|
||||
*
|
||||
* Pass the loaded block so seeding doesn't need a second disk read.
|
||||
*/
|
||||
export function bumpTurnForSession(sessionId: string, block: Block): number {
|
||||
if (!sessionId) return 0;
|
||||
let cur = counters.get(sessionId);
|
||||
if (cur === undefined) {
|
||||
cur = 0;
|
||||
for (const e of block.entries) {
|
||||
if (e.last_refresh_at_turn > cur) cur = e.last_refresh_at_turn;
|
||||
}
|
||||
}
|
||||
const next = cur + 1;
|
||||
counters.set(sessionId, next);
|
||||
return next;
|
||||
}
|
||||
|
||||
/**
|
||||
* Test hook. Forget all in-memory counters. Not exported through any
|
||||
* stable contract — for unit tests only.
|
||||
*/
|
||||
export function _resetForTesting(): void {
|
||||
counters.clear();
|
||||
}
|
||||
@@ -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);
|
||||
@@ -328,35 +321,34 @@ async function installCli() {
|
||||
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()}`);
|
||||
// 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 {
|
||||
const hfBinary = join(binDir, 'hf');
|
||||
|
||||
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 });
|
||||
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 });
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user