sample-services: split reset scripts between matcher and laptop hosts

Author: FUDCo

packages/agentmask/openclaw-plugin-discovery/VALIDATION.md

@@ -2,7 +2,9 @@
 
 This document walks through end-to-end validation of the discovery
 plugin against a running Phase 1 provider (MetaMask extension) and a
-Phase 2 matcher (daemon on VPS). Everything lives on a single VPS.
+Phase 2 matcher (daemon on VPS). The deployment is split across two
+hosts: matcher infrastructure on a VPS, and the MetaMask extension
+plus its sample-services daemon on the laptop.
 
 ## Topology
 
@@ -15,10 +17,6 @@ Phase 2 matcher (daemon on VPS). Everything lives on a single VPS.
 │    (subcluster running the matcher vat,             │
 │     plus the llm-bridge process)                    │
 │                                                     │
-│  sample-services daemon — OCAP_HOME=~/.ocap-services│
-│    (one subcluster per non-MetaMask service:        │
-│     Echo, RandomNumber)                             │
-│                                                     │
 │  consumer daemon  — OCAP_HOME=~/.ocap-consumer      │
 │    (no subclusters; hosts the openclaw plugin's     │
 │     RPC target)                                     │
@@ -28,19 +26,26 @@ Phase 2 matcher (daemon on VPS). Everything lives on a single VPS.
 └─────────────────────────────────────────────────────┘
                            │ relay hints
                            ▼
-                Browser on laptop
-    MetaMask extension with the PersonalMessageSigner
-        provider vat, registered against the matcher
+                         Laptop
+┌─────────────────────────────────────────────────────┐
+│  MetaMask extension                                 │
+│    with the PersonalMessageSigner provider vat,     │
+│    registered against the matcher                   │
+│                                                     │
+│  sample-services daemon — OCAP_HOME=~/.ocap-services│
+│    (one subcluster per non-MetaMask service:        │
+│     Echo, RandomNumber)                             │
+└─────────────────────────────────────────────────────┘
 ```
 
-Three daemons live on the same VPS with different home directories
-so they don't clobber each other's state. The matcher uses the
-default `~/.ocap`; sample-services uses `~/.ocap-services`; the
-consumer uses `~/.ocap-consumer`. Every `ocap` invocation that wants
-a non-default daemon passes `--home <dir>`; invocations without
-`--home` hit the matcher. All three talk to each other (and to the
-browser-side PMS provider) over the relay, same as they would across
-machines — the shared VPS is purely for convenience during dev.
+The VPS hosts the matcher and consumer daemons in separate home
+directories so they don't clobber each other's state: the matcher uses
+the default `~/.ocap`, the consumer uses `~/.ocap-consumer`. Every
+`ocap` invocation that wants a non-default daemon passes
+`--home <dir>`; invocations without `--home` hit the matcher. The
+sample-services daemon lives on the laptop alongside the MetaMask
+extension and uses `~/.ocap-services`. All daemons (and the
+browser-side PMS provider) talk to each other over the relay.
 
 ## Prerequisites
 
@@ -81,14 +86,19 @@ Four things must be live before starting this validation:
     `/v1/chat/completions` endpoint. That adds two requirements,
     described in the next two subsections.
 
-3.  **Sample-services daemon** on the VPS, started via
+3.  **Sample-services daemon** on the laptop (the same machine as the
+    MetaMask extension), started via
     `packages/sample-services/scripts/start-services.sh <matcher-url>`
     (or with `MATCHER_OCAP_URL` exported in the shell). It launches
     one subcluster per service: Echo and RandomNumber. Each
     subcluster's bootstrap registers with the matcher using the URL
-    threaded through its vat parameters, so the matcher daemon log
-    should grow two `[matcher] registered svc:N:` lines once this
-    starts.
+    threaded through its vat parameters, so the matcher daemon log on
+    the VPS should grow two `[matcher] registered svc:N:` lines once
+    this starts.
+
+    For the laptop-side reset-and-restart cycle (stop services, clear
+    log, re-launch pointed at the current matcher URL), use
+    `packages/sample-services/scripts/reset-services.sh <matcher-url>`.
 
 4.  **Provider extension** — MetaMask loaded in a browser with the
     matcher URL baked in via `.metamaskrc`

packages/sample-services/scripts/reset-services.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Reset the laptop-side sample-services daemon for a fresh test cycle:
+#
+#   - stop the sample-services daemon (~/.ocap-services);
+#   - clear its log;
+#   - bring it back up via start-services.sh, registering Echo and
+#     RandomNumber with the supplied matcher URL.
+#
+# The matcher (which runs on the VPS) is reset separately by
+# reset-everything.sh on that side.
+#
+# The matcher OCAP URL is required and is resolved in this order:
+#   1. <matcher-url>            (positional argument)
+#   2. $MATCHER_OCAP_URL        (environment variable)
+#
+# Prereqs: the relay must already be reachable from this host
+# (`yarn ocap relay` locally, or a remote relay specified via
+# --relay / $OCAP_RELAY_MULTIADDR).
+#
+# Usage:
+#   reset-services.sh [<matcher-url>] [--no-build]
+#
+#   <matcher-url>   OCAP URL of the matcher to register with. Falls back
+#                   to $MATCHER_OCAP_URL if omitted.
+#   --no-build      Skip building/bundling the sample-services vats
+#                   (passed through to start-services.sh).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+START_SERVICES_SCRIPT="$SCRIPT_DIR/start-services.sh"
+OCAP_BIN="$REPO_ROOT/packages/kernel-cli/dist/app.mjs"
+SERVICES_HOME="${OCAP_SERVICES_HOME:-${HOME}/.ocap-services}"
+
+PASSTHROUGH_ARGS=()
+MATCHER_URL_ARG=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --no-build)
+      PASSTHROUGH_ARGS+=(--no-build); shift ;;
+    --help|-h)
+      sed -n '2,/^$/p' "$0" >&2; exit 0 ;;
+    --*)
+      echo "Error: unknown argument: $1" >&2; exit 1 ;;
+    *)
+      if [[ -z "$MATCHER_URL_ARG" ]]; then
+        MATCHER_URL_ARG="$1"; shift
+      else
+        echo "Error: unexpected positional argument: $1" >&2; exit 1
+      fi
+      ;;
+  esac
+done
+
+info() { echo "[reset-services] $*" >&2; }
+
+MATCHER_URL="${MATCHER_URL_ARG:-${MATCHER_OCAP_URL:-}}"
+if [[ -z "$MATCHER_URL" ]]; then
+  echo "[reset-services] ERROR: matcher URL required (pass as first argument or set \$MATCHER_OCAP_URL)." >&2
+  exit 1
+fi
+
+if [[ ! -f "$OCAP_BIN" ]]; then
+  echo "[reset-services] ERROR: ocap CLI not found at $OCAP_BIN." >&2
+  echo "                 Run 'yarn workspace @metamask/kernel-cli build' first." >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# 1. Stop the services daemon.
+# ---------------------------------------------------------------------------
+
+info "Stopping sample-services daemon (if running)..."
+node "$OCAP_BIN" --home "$SERVICES_HOME" daemon stop >/dev/null 2>&1 || true
+
+# ---------------------------------------------------------------------------
+# 2. Clear the daemon log.
+# ---------------------------------------------------------------------------
+
+info "Clearing daemon log..."
+rm -f "$SERVICES_HOME/daemon.log"
+
+# ---------------------------------------------------------------------------
+# 3. Bring the services daemon back up.
+# ---------------------------------------------------------------------------
+
+info "Starting sample-services daemon..."
+"$START_SERVICES_SCRIPT" "$MATCHER_URL" "${PASSTHROUGH_ARGS[@]}" >&2
+
+cat <<EOF >&2
+
+================================================================
+SERVICES RESET COMPLETE.
+
+  Echo and RandomNumber have re-registered with:
+    $MATCHER_URL
+================================================================
+EOF

packages/service-matcher/scripts/reset-everything.sh

@@ -1,17 +1,13 @@
 #!/usr/bin/env bash
 # Reset everything VPS-side for a fresh test cycle:
 #
-#   - stop the matcher (~/.ocap), sample-services (~/.ocap-services),
-#     and consumer (~/.ocap-consumer) daemons, plus the matcher's
-#     llm-bridge subprocess; sweep up any orphan daemon-entry / bridge
-#     processes;
-#   - purge consumer + sample-services state and clear daemon logs in
-#     all three homes (the matcher's state is purged by
-#     start-matcher.sh as a side effect of its default behavior);
+#   - stop both daemons (matcher under ~/.ocap, consumer under
+#     ~/.ocap-consumer) and sweep up any orphan daemon-entry processes;
+#   - purge consumer state and clear daemon logs in both homes
+#     (the matcher's state is purged by start-matcher.sh as a side
+#     effect of its default behavior);
 #   - bring the matcher back up via start-matcher.sh, capturing the
 #     newly-issued OCAP URL on stdout;
-#   - bring the sample-services daemon back up via start-services.sh,
-#     pointed at that URL, so Echo and RandomNumber register;
 #   - bring the consumer daemon back up with --local-relay;
 #   - update the openclaw discovery plugin's matcherUrl config and
 #     restart the gateway so the new URL takes effect.
@@ -25,28 +21,25 @@
 # Usage:
 #   reset-everything.sh [--no-build]
 #
-#   --no-build   Skip building/bundling the matcher vat and the sample
-#                services (passed through to start-matcher.sh and
-#                start-services.sh).
+#   --no-build   Skip building/bundling the matcher vat (passed through
+#                to start-matcher.sh).
 
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
-START_SERVICES_SCRIPT="$REPO_ROOT/packages/sample-services/scripts/start-services.sh"
 OCAP_BIN="$REPO_ROOT/packages/kernel-cli/dist/app.mjs"
 CONSUMER_HOME="${OCAP_CONSUMER_HOME:-${HOME}/.ocap-consumer}"
-SERVICES_HOME="${OCAP_SERVICES_HOME:-${HOME}/.ocap-services}"
 MATCHER_HOME="${HOME}/.ocap"
 LLM_BRIDGE_PID_PATH="$MATCHER_HOME/matcher-llm-bridge.pid"
 LLM_BRIDGE_LOG_PATH="$MATCHER_HOME/matcher-llm-bridge.log"
 LLM_SOCKET_PATH="$MATCHER_HOME/matcher-llm.sock"
 
-PASSTHROUGH_ARGS=()
+START_MATCHER_ARGS=()
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --no-build)
-      PASSTHROUGH_ARGS+=(--no-build); shift ;;
+      START_MATCHER_ARGS+=(--no-build); shift ;;
     --help|-h)
       sed -n '2,/^$/p' "$0" >&2; exit 0 ;;
     *)
@@ -69,9 +62,6 @@ fi
 info "Stopping consumer daemon (if running)..."
 node "$OCAP_BIN" --home "$CONSUMER_HOME" daemon stop >/dev/null 2>&1 || true
 
-info "Stopping sample-services daemon (if running)..."
-node "$OCAP_BIN" --home "$SERVICES_HOME" daemon stop >/dev/null 2>&1 || true
-
 info "Stopping matcher daemon (if running)..."
 node "$OCAP_BIN" --home "$MATCHER_HOME" daemon stop >/dev/null 2>&1 || true
 
@@ -114,37 +104,26 @@ fi
 info "Purging consumer daemon state..."
 node "$OCAP_BIN" --home "$CONSUMER_HOME" daemon purge --force >/dev/null 2>&1 || true
 
-info "Purging sample-services daemon state..."
-node "$OCAP_BIN" --home "$SERVICES_HOME" daemon purge --force >/dev/null 2>&1 || true
-
 info "Clearing daemon and bridge logs..."
 rm -f \
   "$MATCHER_HOME/daemon.log" \
   "$CONSUMER_HOME/daemon.log" \
-  "$SERVICES_HOME/daemon.log" \
   "$LLM_BRIDGE_LOG_PATH"
 
 # ---------------------------------------------------------------------------
 # 6. Bring the matcher back up; capture the URL on stdout.
 # ---------------------------------------------------------------------------
 
 info "Starting matcher..."
-MATCHER_URL="$("$SCRIPT_DIR/start-matcher.sh" "${PASSTHROUGH_ARGS[@]}")"
+MATCHER_URL="$("$SCRIPT_DIR/start-matcher.sh" "${START_MATCHER_ARGS[@]}")"
 if [[ -z "$MATCHER_URL" ]]; then
   echo "[reset] ERROR: start-matcher.sh produced no URL." >&2
   exit 1
 fi
 info "Matcher URL: $MATCHER_URL"
 
 # ---------------------------------------------------------------------------
-# 7. Bring the sample-services daemon back up, pointed at the matcher.
-# ---------------------------------------------------------------------------
-
-info "Starting sample-services daemon..."
-"$START_SERVICES_SCRIPT" "$MATCHER_URL" "${PASSTHROUGH_ARGS[@]}" >&2
-
-# ---------------------------------------------------------------------------
-# 8. Bring the consumer daemon back up.
+# 7. Bring the consumer daemon back up.
 # ---------------------------------------------------------------------------
 
 info "Starting consumer daemon (--local-relay)..."