Merge pull request 'fix: lift calendarScheduler to module scope (multi-register singleton)' (#8 ) from fix/scheduler-module-singleton into main

fix(plugin): lift calendarScheduler to module scope (multi-register singleton)
Trying the prior multi-agent-handle fix in dind-t2 surfaced a second bug that PR #7 didn't reach: `harborforge_calendar_status` still returned `Calendar scheduler not running` even though the gateway log showed the scheduler had started 30+ seconds before the agent's call. ## Root cause `register()` is invoked once per agent — `grep -c "HarborForge plugin registered" /tmp/gw-stdout.log` reports 5 for a 5-agent claw. Every invocation creates its own `let calendarScheduler` closure binding. But `gateway_start` fires once and we only call `startCalendarScheduler()` through that single hook, so exactly one of the five closures sees the handle and the other four keep their bindings at `null`. The host's tool router picks one of the five duplicate `harborforge_calendar_status` registrations to dispatch to — most of the time it's one of the four "null" closures, which is why every wakeup the agent saw `Calendar scheduler not running`. ## Fix Lift `let calendarScheduler` out of `register()` and into module scope. All five register-call closures now reference the same binding; once the single `gateway_start` initialises it, every tool sees it. `startCalendarScheduler()` now early-returns when `calendarScheduler` is already set, so duplicate `gateway_start` firings (if the host ever does that) don't double-install intervals. Bumps version 0.3.2 → 0.3.3. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-21 09:54:55 +00:00 · 2026-05-21 10:54:36 +01:00 · 2026-05-21 09:39:51 +00:00 · 2026-05-21 10:38:57 +01:00 · 2026-05-20 14:48:06 +00:00 · 2026-05-20 12:02:25 +01:00
9 changed files with 34 additions and 1225 deletions
--- a/plugin/index.ts
+++ b/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
+      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';
    }
@@ -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 ` +
+          `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({
          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)');
 }
--- a/plugin/openclaw.plugin.json
+++ b/plugin/openclaw.plugin.json
@@ -15,12 +15,7 @@
      "harborforge_calendar_abort",
      "harborforge_calendar_pause",
      "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": {
--- a/plugin/package.json
+++ b/plugin/package.json
@@ -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",
--- a/plugin/tools/dynamic-kb.ts
+++ b/plugin/tools/dynamic-kb.ts
@@ -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.',
        }),
      );
    },
  };
 }
--- a/plugin/tools/fade.ts
+++ b/plugin/tools/fade.ts
@@ -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]];
  }
 }
--- a/plugin/tools/kbblock.ts
+++ b/plugin/tools/kbblock.ts
@@ -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;
  }
 }
--- a/plugin/tools/kbclient.ts
+++ b/plugin/tools/kbclient.ts
@@ -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;
 }
--- a/plugin/tools/turn-tracker.ts
+++ b/plugin/tools/turn-tracker.ts
@@ -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();
 }
--- a/scripts/install.mjs
+++ b/scripts/install.mjs
@@ -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
+  // 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()}`);
+  
  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');
-
+    exec(`go build -o ${hfBinary} ./cmd/hf`, { cwd: effectiveCliDir, silent: !options.verbose });
  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 });
    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 });
  }
 }
Author	SHA1	Message	Date
h z	065b0d3da3	Merge pull request 'fix: lift calendarScheduler to module scope (multi-register singleton)' (#8 ) from fix/scheduler-module-singleton into main	2026-05-21 09:54:55 +00:00
hanghang zhang	afb8b25558	fix(plugin): lift calendarScheduler to module scope (multi-register singleton) Trying the prior multi-agent-handle fix in dind-t2 surfaced a second bug that PR #7 didn't reach: `harborforge_calendar_status` still returned `Calendar scheduler not running` even though the gateway log showed the scheduler had started 30+ seconds before the agent's call. ## Root cause `register()` is invoked once per agent — `grep -c "HarborForge plugin registered" /tmp/gw-stdout.log` reports 5 for a 5-agent claw. Every invocation creates its own `let calendarScheduler` closure binding. But `gateway_start` fires once and we only call `startCalendarScheduler()` through that single hook, so exactly one of the five closures sees the handle and the other four keep their bindings at `null`. The host's tool router picks one of the five duplicate `harborforge_calendar_status` registrations to dispatch to — most of the time it's one of the four "null" closures, which is why every wakeup the agent saw `Calendar scheduler not running`. ## Fix Lift `let calendarScheduler` out of `register()` and into module scope. All five register-call closures now reference the same binding; once the single `gateway_start` initialises it, every tool sees it. `startCalendarScheduler()` now early-returns when `calendarScheduler` is already set, so duplicate `gateway_start` firings (if the host ever does that) don't double-install intervals. Bumps version 0.3.2 → 0.3.3. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-21 10:54:36 +01:00
h z	98e663a19b	Merge pull request 'fix: real per-agent slot handle for multi-agent calendar tools' (#7 ) from fix/multi-agent-scheduler-handle into main	2026-05-21 09:39:51 +00:00
hanghang zhang	d5cea9a44d	fix(plugin): real per-agent slot handle for multi-agent calendar tools In multi-agent sync mode every harborforge_calendar_* tool was returning `calendarScheduler.<method> is not a function`. The cause: index.ts replaced `calendarScheduler` (typed `CalendarScheduler \| null`) with a `{ stop() }` stub right after wiring the runSync/runCheck intervals, so `isRunning()`, `getCurrentSlot()`, `completeCurrentSlot()`, `abortCurrentSlot()`, `pauseCurrentSlot()`, `resumeCurrentSlot()`, `getState()`, `isRestartPending()` and `getStateFilePath()` all blew up at call time. Replaces the stub with a `MultiAgentSchedulerHandle` that: - tracks the last slot dispatched per agent (recorded by `wakeAgent`) - exposes status/complete/abort/pause/resume taking the calling agentId - resolves the implicit "current slot" via woken-cursor first then a cache scan over not_started/deferred/ongoing slots - PATCHes via `bridge.updateSlotAs(agentId, …)` so audit headers reflect the real caller (bridge constructor agentId is 'unused' in multi-agent) - mirrors the legacy `isRunning/isProcessing/getState/...` surface so the single-agent fallback (`CalendarScheduler`) keeps working unchanged Each calendar tool factory now takes `OpenClawPluginToolContext`, reads `ctx.agentId`, and dispatches through the handle. Single-agent path (when `calendarScheduler` is a real `CalendarScheduler`) is preserved behind `instanceof` checks. Drops the dead `trackSessionCompletion` poll loop (only definition, no caller) which referenced the removed `completeCurrentSlot`. Bumps plugin version 0.2.0 → 0.3.2. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-21 10:38:57 +01:00
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