fix: make LibraVDB installer fully automated

[fuller-stack-dev]

Summary

• expose the automated installer as package bins so users can run npx --yes @xdarkicex/openclaw-memory-libravdb --yes
• make manual daemon install provision the daemon, ONNX Runtime, Nomic/BGE/T5 assets, launchd/systemd env, and current plugins.entries OpenClaw config shape
• assign both exclusive slots: plugins.slots.memory and plugins.slots.contextEngine
• fall back from Homebrew to installer-managed daemon assets when Homebrew fails, tolerate launchd bootstrap failures by falling back to a background daemon, and handle already-installed plugin packages idempotently
• preserve the intended fallback profile contract: bge-small-en-v1.5

Installation issues addressed

• README/docs routed users through openclaw plugins install, which enabled the package but did not assign the required exclusive slots or write plugins.entries[libravdb-memory].config
• scripts/auto-install.sh wrote stale plugins.configs; it now writes plugins.entries while assigning both memory and contextEngine slots
• Homebrew failures were swallowed because the function ended with return 0; failures now return nonzero and trigger fallback
• rerunning the installer failed when the plugin was already installed; it now updates or continues with the existing package
• launchd bootstrap failures could abort before config assignment; the installer now falls back to a login-session background daemon
• manual macOS docs referenced service-template downloads that were not present; installer now writes service files directly
• manual installer launchd/runtime wiring missed the ONNX Runtime path actually produced by asset provisioning
• installer-managed model provisioning now uses bge-small-en-v1.5 for fallback, not all-minilm-l6-v2
• first-time BGE/CoreML startup can exceed the old readiness window; the installer now removes stale sockets and waits longer for the daemon socket

Verification

• bash -n scripts/auto-install.sh
• bash scripts/auto-install.sh --dry-run --yes
• bash scripts/auto-install.sh --yes
• npm pack --dry-run
• pnpm exec tsc -p tsconfig.tests.json && node --test .ts-build/test/integration/checklist-validation.test.js .ts-build/test/unit/sidecar.test.js .ts-build/test/unit/plugin-runtime.test.js .ts-build/test/integration/sidecar-lifecycle.test.js
• pnpm check
• pnpm run plugin:check
• openclaw memory status

Summary by CodeRabbit

• New Features

  • Automated installer (npx/bundled script) to provision daemon, ONNX runtime, model assets, plugin, and slot config; verifier via openclaw memory status.
  • Plugin now claims both memory and context-engine slots.

• Documentation

  • Install/uninstall/activation docs rewritten to center automated workflow and verification steps.
  • Security and troubleshooting guidance clarified.

• Improvements

  • macOS Homebrew fallback, asset provisioning, and installer repair flows improved.
  • Installer now checks for required CLI tools and cleans up installed assets on uninstall.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/install.md`:
- Around line 144-150: The example assumes ~/.local/bin is on PATH; update the
docs so the commands will work as-is by either (A) invoking the binary with its
full path after chmod (use "~/.local/bin/libravdbd serve" instead of "libravdbd
serve"), or (B) adding an explicit PATH export step before running (e.g.,
"export PATH=$HOME/.local/bin:$PATH") so the existing "libravdbd serve"
invocation succeeds; make the change near the shown chmod +x and libravdbd serve
lines.

In `@scripts/auto-install.sh`:
- Around line 495-501: The early return when the installed daemon matches the
desired version skips PATH bootstrapping; ensure PATH setup still runs before
returning by invoking append_path_once and exporting the temporary PATH (the
same logic used elsewhere) prior to the return in the block that checks
daemon_version/bin_path/tag_norm, and keep the call to provision_manual_assets;
update the block surrounding daemon_version, current_norm, and tag_norm so
append_path_once and the PATH export occur unconditionally when the daemon is
current.
- Around line 1062-1064: The install_daemon_macos_brew function currently masks
failures because errexit is disabled and several brew commands lack explicit
failure propagation; update install_daemon_macos_brew so each critical brew
command (e.g., any brew tap, brew install, and brew services commands inside
that function) is followed by "|| return 1" to ensure the function returns
non-zero on failure, allowing the caller's if ! install_daemon_macos_brew check
to trigger the fallback install_daemon_manual path.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d831beb3-31ac-48b0-beb9-1e134a48c5eb

📥 Commits

Reviewing files that changed from the base of the PR and between 8ada0a2 and 026c4ef.

📒 Files selected for processing (19)

• README.md
• docs/configuration.md
• docs/development.md
• docs/embedding-profiles.md
• docs/install.md
• docs/installation.md
• docs/models.md
• docs/security.md
• docs/uninstall.md
• openclaw.plugin.json
• package.json
• scripts/auto-install.sh
• src/index.ts
• src/plugin-runtime.ts
• src/sidecar.ts
• test/integration/checklist-validation.test.ts
• test/integration/sidecar-lifecycle.test.ts
• test/unit/plugin-runtime.test.ts
• test/unit/sidecar.test.ts

[compoodment]

CodeRabbit caught some valid script edge cases (the PATH append on early exit and the brew error propagation), but there's a much bigger issue here: the uninstall path abandons over a gigabyte of hidden assets.

If a user installs via the non-Homebrew path, the script downloads:

• ONNX Runtime to ~/.local/share/libravdb/onnxruntime/ (~150MB)
• Nomic/MiniLM/T5 ONNX weights to ~/.local/share/libravdb/models/ (~800MB)
• A daemon service file to ~/.config/systemd/user/ or ~/Library/LaunchAgents/

When running --uninstall, the script claims to be a "Safe Mode" uninstall that preserves user memory data (which is good), but it completely ignores the ~/.local/share/libravdb asset directory and the service definition files it created. It only removes the daemon binary and the OpenClaw config.

This means running --uninstall leaves a gigabyte of orphaned models and dormant service files permanently hidden in the user's home directory.

The run_uninstall_mode function needs to explicitly remove:

1. ~/.local/share/libravdb/onnxruntime/
2. ~/.local/share/libravdb/models/
3. The launchd .plist or systemd .service file it wrote

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

scripts/auto-install.sh (1)

1029-1033: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Uninstall leaves installer-managed ONNX/model assets behind.

At Line 1029 through Line 1033, uninstall performs service/config/plugin/binary cleanup but never removes ~/.local/share/libravdb/onnxruntime and ~/.local/share/libravdb/models, which are created by manual provisioning and can leave ~1GB orphaned data.

Suggested patch

+remove_manual_assets() {
+  local asset_root
+  asset_root="$(manual_asset_root)"
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    info "[dry-run] rm -rf ${asset_root}/onnxruntime ${asset_root}/models"
+    return 0
+  fi
+  rm -rf "${asset_root}/onnxruntime" "${asset_root}/models"
+  info "Removed installer-managed assets under ${asset_root}."
+}
+
 run_uninstall_mode() {
   local os
   os="$(detect_os)"
@@
   stop_daemon_services "$os"
   uninstall_openclaw_config
   uninstall_plugin_package
   remove_manual_daemon_binary
+  remove_manual_assets

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/auto-install.sh` around lines 1029 - 1033, The uninstall flow
currently calls stop_daemon_services, uninstall_openclaw_config,
uninstall_plugin_package and remove_manual_daemon_binary but never removes
installer-managed runtime/model assets, leaving
~/.local/share/libravdb/onnxruntime and ~/.local/share/libravdb/models behind;
add removal of these directories to the uninstall path (either by a new helper
like uninstall_libravdb_assets or by extending the existing uninstall sequence)
to recursively delete those two paths if present (handle non-existence safely
and avoid removing unrelated files). Ensure the new removal is invoked alongside
the other cleanup calls so the assets are cleaned up during uninstall.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@scripts/auto-install.sh`:
- Around line 1029-1033: The uninstall flow currently calls
stop_daemon_services, uninstall_openclaw_config, uninstall_plugin_package and
remove_manual_daemon_binary but never removes installer-managed runtime/model
assets, leaving ~/.local/share/libravdb/onnxruntime and
~/.local/share/libravdb/models behind; add removal of these directories to the
uninstall path (either by a new helper like uninstall_libravdb_assets or by
extending the existing uninstall sequence) to recursively delete those two paths
if present (handle non-existence safely and avoid removing unrelated files).
Ensure the new removal is invoked alongside the other cleanup calls so the
assets are cleaned up during uninstall.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 145526e5-37fb-4b1f-8667-b5556399bf05

📥 Commits

Reviewing files that changed from the base of the PR and between 026c4ef and 65b02a4.

📒 Files selected for processing (21)

• README.md
• docs/development.md
• docs/install.md
• docs/installation.md
• docs/performance-and-tuning.md
• docs/security.md
• docs/uninstall.md
• package.json
• scripts/auto-install.sh
• scripts/build-daemon.sh
• scripts/postinstall.js
• scripts/setup.ts
• src/index.ts
• src/plugin-runtime.ts
• src/sidecar.ts
• test/integration/checklist-validation.test.ts
• test/integration/sidecar-lifecycle.test.ts
• test/unit/cli.test.ts
• test/unit/memory-runtime.test.ts
• test/unit/plugin-runtime.test.ts
• test/unit/sidecar.test.ts

✅ Files skipped from review due to trivial changes (9)

• package.json
• test/unit/sidecar.test.ts
• docs/performance-and-tuning.md
• README.md
• src/index.ts
• docs/development.md
• docs/install.md
• docs/installation.md
• test/integration/sidecar-lifecycle.test.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• test/unit/plugin-runtime.test.ts
• docs/uninstall.md
• src/sidecar.ts
• docs/security.md
• src/plugin-runtime.ts

[fuller-stack-dev]

@compoodment addressed in 3c148db. --uninstall now removes installer-managed ~/.local/share/libravdb/onnxruntime and ~/.local/share/libravdb/models while preserving ~/.libravdbd memory data. I also made the systemd service file removal run even if systemctl is unavailable; launchd/systemd cleanup remains in stop_daemon_services. Added regression coverage and updated uninstall docs.

[compoodment]

Reviewed the follow-up commit. Three fixes all land correctly:

• Uninstall asset cleanup: remove_manual_assets() handles onnxruntime/ and models/ with dry-run and no-op-if-absent guards. Wired into the uninstall sequence. Good.
• systemd cleanup without systemctl: Now removes the stale .service file regardless. Bug fix, correct.
• PATH bootstrap on already-installed daemon: The early-return path now ensures $bin_dir is on PATH before calling provision_manual_assets. Correct.

I had a concern about brew error propagation in install_daemon_macos_brew, but on re-read every brew call already has || return 1 and the caller falls back to install_daemon_manual. That path is fine.

One minor note (not blocking): remove_manual_assets cleans onnxruntime/ and models/ but leaves the parent ~/.local/share/libravdb/ directory if it ends up empty. Not a real problem, just housekeeping.

LGTM.

[xDarkicex]

you guys do know its is not getting merged, not even close

[compoodment]

Two blockers on this PR:

1. Merge conflict with current main: Pushed 4e948f9 to merge current main, resolve the plugin-runtime and sidecar test conflicts, and keep the automated-installer provisioning hint. The merged branch also needed the sidecar retry stability-window fix; without it, the current integration suite failed sidecar enters degraded mode after exhausting retry budget.

Validated with:

bash -n scripts/auto-install.sh
pnpm run check
pnpm run test:integration

2. Scope leak — sidecar retry semantics: This installer PR also changes src/sidecar.ts with the same 15s stability-window retry reset under review in #162 (CONNECTION_STABILITY_WINDOW_MS, scheduleStabilityReset(), clearStabilityTimer(), this.stabilityTimer.unref?.()). That is not installer plumbing; it is the behavioral fix for the sidecar degraded-mode bug.

The only sidecar test updates are provisioning-hint/fallback-profile expectations — no deterministic stability-window coverage. This PR can silently merge the #162 behavior without the review/test coverage we're requiring there.

Please split/drop the sidecar retry change from this installer PR, or explicitly make this PR own the #132/#162 behavior with the same required coverage:

1. crash before the 15s stability window preserves/increments retry count and can degrade
2. surviving past the window resets retry count
3. shutdown clears the pending timer

— Vale

[compoodment]

Review — Vale

Summary

This PR adds an automated installer (npx --yes @xdarkicex/openclaw-memory-libravdb --yes) that provisions the daemon, ONNX Runtime, model assets, systemd/launchd service files, and plugin slot configuration. 693 additions, 219 deletions, 21 files changed. It's a big PR with a lot of surface area.

What this does well

• Stability timer in sidecar.ts — CONNECTION_STABILITY_WINDOW_MS extracted as a named constant, timer properly cleared in destroy(). Good.
• Slot assignment — claims both memory and contextEngine exclusive slots during install, which addresses the "plugin installed but not activated" gap.
• ONNX Runtime SHA256 verification — pinned hashes per OS/arch pair for the download. Correct security practice.
• Homebrew fallback — if Homebrew install fails, falls back to manual asset provisioning instead of silently succeeding.

Concerns

1. Massive scope for an installer PR. 21 files touched including source changes (sidecar.ts, plugin-runtime.ts, index.ts), 5 test files, 4 doc files, and the installer script itself. The sidecar stability timer and plugin-runtime error message changes should be separate PRs. Bundling them makes review harder and rollback riskier.

2. auto-install.sh is 700+ lines of shell. The script handles OS detection, Homebrew, asset download, SHA verification, systemd/launchd service templates, idempotent installs, and slot configuration. Shell scripts of this length are hard to test and maintain. Consider splitting the daemon provisioning into a separate script or a Node.js module that can be unit-tested.

3. verify_sha256 uses sha256_file which isn't defined in the diff. Is this a function from the script, or an external dependency? If it's shasum -a 256 or sha256sum, the command varies by OS. The diff doesn't show where it's defined.

4. ONNX Runtime version 1.25.1 is hardcoded. When the daemon updates to a new ONNX Runtime version, the installer SHA256 table and version constant both need manual updates. No CI check verifies that the pinned URLs still resolve.

5. plugin-runtime.ts error message matching — the PR changes the error sniff from message.includes("package does not provision the daemon binary") to a broader check matching three strings. This is fragile — if any of these strings appear in a different error context, the wrong remediation message will be shown. Consider an error code or structured error type instead.

6. Test coverage for the installer is bash -n (syntax check) and --dry-run only. There's no integration test that actually runs the installer end-to-end. The sidecar-lifecycle.test.ts changes test the stability timer, which is fine, but the installer itself has no automated verification beyond syntax.

7. Sidecar stability timer interacts with chore: close over-bundled runtime cleanup batch #221's reconnect timer fix. This PR adds clearStabilityTimer() in destroy(). PR chore: close over-bundled runtime cleanup batch #221 adds clearReconnectTimer() for the reconnect timer. If both merge, the destroy() method needs both. Currently they target different timers, so no conflict — but worth noting for merge order.

Verdict

The installer functionality is needed and the Homebrew fallback is a real improvement. But this PR is too broad — it mixes installer, sidecar, and plugin-runtime changes. Recommend splitting into: (a) sidecar stability timer, (b) plugin-runtime error message, (c) installer + docs. The installer script itself needs better testability and a strategy for version pinning.

– Vale

[xDarkicex]

Note: PR #231 (merged) deleted several files this PR touches — src/sidecar.ts, test/integration/sidecar-lifecycle.test.ts, test/unit/sidecar.test.ts — and heavily refactored src/plugin-runtime.ts and src/index.ts. The docs, scripts, and test changes may still be relevant but will need a rebase onto current main.