From a1cbfd30534cd0e0c22da21f4c7df77b03eafed6 Mon Sep 17 00:00:00 2001 From: zhi Date: Sat, 21 Mar 2026 11:46:00 +0000 Subject: [PATCH] docs: add hf plugin and monitor integration requirements --- plans/harborforge-cli-go-plan.md | 148 ++++++++++++++++++++++++++++++- 1 file changed, 147 insertions(+), 1 deletion(-) diff --git a/plans/harborforge-cli-go-plan.md b/plans/harborforge-cli-go-plan.md index 8c64b67..dad1357 100644 --- a/plans/harborforge-cli-go-plan.md +++ b/plans/harborforge-cli-go-plan.md @@ -40,6 +40,133 @@ This CLI should work well in two environments: --- +## OpenClaw Plugin / Monitor Integration Requirements + +This CLI plan now also carries **cross-project integration constraints** for: + +- `HarborForge.OpenclawPlugin` +- `HarborForge.Monitor` +- `HarborForge.Cli` + +These requirements should be treated as part of the same roadmap because the CLI, plugin installation flow, and monitor data path are now coupled. + +### 1. OpenClaw plugin registration name + +The plugin currently known as HarborForge.OpenclawPlugin should register under the plugin name: + +```text +harbor-forge +``` + +This should replace the old plugin registration name used previously. + +### 2. Remove plugin sidecar server + +The plugin should no longer keep a separate `server/` sidecar process for telemetry collection. + +That means: +- remove the plugin-side `server` component +- remove the architecture where plugin telemetry is uploaded by a dedicated sidecar process +- any OpenClaw-specific monitor data should instead be served directly by the plugin via the plugin/runtime communication path described below + +### 3. Plugin install script: `--install-cli` + +The OpenClaw plugin install script should support: + +```bash +--install-cli +``` + +If present, the installer should: + +1. build `HarborForge.Cli` +2. produce the `hf` binary +3. copy the binary into the OpenClaw profile `bin` directory +4. `chmod +x` the installed binary + +Default target location: + +```text +~/.openclaw/bin/hf +``` + +The implementation should allow profile-aware resolution, but default to: + +```text +~/.openclaw/bin +``` + +### 4. Plugin config: add `monitor_port` + +The OpenClaw plugin configuration should add a new field: + +```text +monitor_port +``` + +This port is used for **local communication between HarborForge.Monitor and the plugin**. + +### 5. HarborForge.Monitor Docker env: `MONITOR_PORT` + +`HarborForge.Monitor` should add a Docker environment variable: + +```text +MONITOR_PORT +``` + +Behavior: +- Monitor listens on `127.0.0.1:` +- docker-compose should expose this port to the host on `127.0.0.1` +- the OpenClaw plugin communicates with Monitor through this local port + +This communication channel is specifically for supplementing OpenClaw-related telemetry, such as: +- OpenClaw version +- plugin version +- agent information +- other OpenClaw runtime metadata that used to come from the plugin-side sidecar telemetry path + +### 6. Monitor heartbeat behavior stays independent + +`HarborForge.Monitor` startup / heartbeat / telemetry upload must **not depend** on successful communication with the plugin over `MONITOR_PORT`. + +Required behavior: +- if no plugin communication happens, Monitor should behave exactly like it does now +- if plugin communication succeeds, Monitor should enrich uploaded telemetry with: + - OpenClaw version + - plugin version + - agent list / agent metadata + - related OpenClaw-side monitor fields + +In other words: +- hardware/host telemetry path remains primary and independent +- OpenClaw-side metadata becomes optional enrichment + +### 7. Plugin `skills/` folder deployment + +`HarborForge.OpenclawPlugin` should include a `skills/` directory. + +During plugin installation, installer logic should copy everything under that directory into the OpenClaw profile skills directory. + +Default target location: + +```text +~/.openclaw/skills +``` + +The implementation should be profile-aware, but default to the standard OpenClaw profile path above. + +### 8. Implication for implementation planning + +This means the CLI plan is no longer only about `hf` command syntax. +It also implies follow-up implementation work in: + +- `HarborForge.Cli` +- `HarborForge.OpenclawPlugin` +- `HarborForge.Monitor` +- Docker / install scripts / plugin packaging + +--- + ## Binary / Config Model ## CLI name @@ -846,13 +973,32 @@ The backend should support: - meeting commands - support commands -## Phase 6 — Hardening +## Phase 6 — Plugin / Install Integration + +- rename OpenClaw plugin registration to `harbor-forge` +- remove plugin-side telemetry `server/` sidecar architecture +- add plugin config field `monitor_port` +- add plugin installer flag `--install-cli` +- build and install `hf` into OpenClaw profile `bin/` +- copy plugin `skills/` into OpenClaw profile `skills/` + +## Phase 7 — Monitor / Plugin Local Bridge + +- add `MONITOR_PORT` to HarborForge.Monitor Docker runtime +- expose `127.0.0.1:` to host in compose +- let Monitor query plugin over this local port for OpenClaw metadata +- keep hardware heartbeat / telemetry upload independent of plugin communication +- enrich Monitor uploads with OpenClaw version / plugin version / agent metadata when available + +## Phase 8 — Hardening - tests for config-path behavior - tests for mode switching (`pass_mgr` present / absent) - tests for exact stderr messages - tests for help and help-brief rendering - tests for permission-aware help visibility +- tests for plugin installer behavior (`--install-cli`, skills copy) +- tests for monitor local bridge behavior with and without plugin connectivity - binary packaging / release pipeline ---