openclaw-node-harness 2.0.0

package/workspace-bin/install-daemon

@@ -0,0 +1,299 @@
+#!/usr/bin/env bash
+# install-daemon — Cross-platform service installer for OpenClaw memory daemon
+#
+# Detects OS and installs the appropriate persistent service:
+#   - macOS:   launchd (~/Library/LaunchAgents/)
+#   - Linux:   systemd user service (~/.config/systemd/user/)
+#   - Other:   pm2 (requires: npm install -g pm2)
+#
+# Usage:
+#   bin/install-daemon              # install and start
+#   bin/install-daemon --uninstall  # stop and remove
+#   bin/install-daemon --status     # check service status
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+WORKSPACE="${OPENCLAW_WORKSPACE:-$(dirname "$SCRIPT_DIR")}"
+DAEMON_SCRIPT="$WORKSPACE/bin/memory-daemon.mjs"
+SERVICE_NAME="ai.openclaw.memory-daemon"
+SERVICES_DIR="$HOME/.openclaw/services"
+
+# Find Node.js
+NODE_BIN="$(command -v node 2>/dev/null || echo "")"
+if [ -z "$NODE_BIN" ]; then
+  echo "Error: Node.js not found in PATH"
+  echo "Install Node.js 18+ and try again"
+  exit 1
+fi
+
+NODE_VERSION=$("$NODE_BIN" -e "console.log(process.versions.node.split('.')[0])")
+if [ "$NODE_VERSION" -lt 18 ]; then
+  echo "Error: Node.js 18+ required (found v$NODE_VERSION)"
+  exit 1
+fi
+
+detect_os() {
+  case "$(uname -s)" in
+    Darwin)              echo "macos" ;;
+    Linux)               echo "linux" ;;
+    MINGW*|MSYS*|CYGWIN*) echo "windows" ;;
+    *)                   echo "unknown" ;;
+  esac
+}
+
+OS=$(detect_os)
+
+# ============================================================
+# macOS — launchd
+# ============================================================
+
+PLIST_PATH="$HOME/Library/LaunchAgents/${SERVICE_NAME}.plist"
+
+install_macos() {
+  mkdir -p "$HOME/Library/LaunchAgents" "$SERVICES_DIR"
+
+  # Build PATH for the daemon
+  local daemon_path="$WORKSPACE/.npm-global/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+
+  cat > "$PLIST_PATH" << PLISTEOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${SERVICE_NAME}</string>
+    <key>Comment</key>
+    <string>OpenClaw Memory Daemon v2 — Node.js long-running process</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>${NODE_BIN}</string>
+      <string>${DAEMON_SCRIPT}</string>
+    </array>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${WORKSPACE}/.tmp/memory-daemon.log</string>
+    <key>StandardErrorPath</key>
+    <string>${WORKSPACE}/.tmp/memory-daemon.err</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+      <key>HOME</key>
+      <string>${HOME}</string>
+      <key>PATH</key>
+      <string>${daemon_path}</string>
+      <key>TZ</key>
+      <string>America/Montreal</string>
+      <key>OPENCLAW_WORKSPACE</key>
+      <string>${WORKSPACE}</string>
+      <key>OPENCLAW_NATS</key>
+      <string>${OPENCLAW_NATS:-}</string>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+  </dict>
+</plist>
+PLISTEOF
+
+  # Copy to services dir for reference
+  cp "$PLIST_PATH" "$SERVICES_DIR/"
+
+  # Unload if already loaded (ignore errors)
+  launchctl unload "$PLIST_PATH" 2>/dev/null || true
+
+  # Load the service
+  launchctl load "$PLIST_PATH"
+
+  echo "Installed: launchd service at $PLIST_PATH"
+  echo "Status: $(launchctl list | grep "$SERVICE_NAME" || echo "loading...")"
+  echo ""
+  echo "Commands:"
+  echo "  launchctl start $SERVICE_NAME    # force start"
+  echo "  launchctl stop $SERVICE_NAME     # stop"
+  echo "  launchctl unload $PLIST_PATH     # disable"
+  echo "  tail -f $WORKSPACE/.tmp/memory-daemon.log  # watch logs"
+}
+
+uninstall_macos() {
+  if [ -f "$PLIST_PATH" ]; then
+    launchctl unload "$PLIST_PATH" 2>/dev/null || true
+    rm -f "$PLIST_PATH"
+    echo "Uninstalled: launchd service removed"
+  else
+    echo "Not installed (no plist found)"
+  fi
+}
+
+status_macos() {
+  if launchctl list | grep -q "$SERVICE_NAME"; then
+    echo "Running"
+    launchctl list | grep "$SERVICE_NAME"
+  else
+    echo "Not running"
+  fi
+}
+
+# ============================================================
+# Linux — systemd user service
+# ============================================================
+
+SYSTEMD_DIR="$HOME/.config/systemd/user"
+UNIT_PATH="$SYSTEMD_DIR/openclaw-memory-daemon.service"
+
+install_linux() {
+  mkdir -p "$SYSTEMD_DIR" "$SERVICES_DIR"
+
+  cat > "$UNIT_PATH" << UNITEOF
+[Unit]
+Description=OpenClaw Memory Daemon v2
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${NODE_BIN} ${DAEMON_SCRIPT}
+Restart=always
+RestartSec=5
+Environment=HOME=${HOME}
+Environment=TZ=America/Montreal
+Environment=OPENCLAW_WORKSPACE=${WORKSPACE}
+Environment=OPENCLAW_NATS=${OPENCLAW_NATS:-}
+Environment=PATH=${WORKSPACE}/.npm-global/bin:/usr/local/bin:/usr/bin:/bin
+StandardOutput=append:${WORKSPACE}/.tmp/memory-daemon.log
+StandardError=append:${WORKSPACE}/.tmp/memory-daemon.err
+WorkingDirectory=${WORKSPACE}
+
+[Install]
+WantedBy=default.target
+UNITEOF
+
+  # Copy to services dir for reference
+  cp "$UNIT_PATH" "$SERVICES_DIR/"
+
+  systemctl --user daemon-reload
+  systemctl --user enable openclaw-memory-daemon
+  systemctl --user start openclaw-memory-daemon
+
+  echo "Installed: systemd user service at $UNIT_PATH"
+  echo ""
+  echo "Commands:"
+  echo "  systemctl --user status openclaw-memory-daemon"
+  echo "  systemctl --user stop openclaw-memory-daemon"
+  echo "  systemctl --user restart openclaw-memory-daemon"
+  echo "  journalctl --user -u openclaw-memory-daemon -f  # watch logs"
+  echo "  tail -f $WORKSPACE/.tmp/memory-daemon.log"
+}
+
+uninstall_linux() {
+  if [ -f "$UNIT_PATH" ]; then
+    systemctl --user stop openclaw-memory-daemon 2>/dev/null || true
+    systemctl --user disable openclaw-memory-daemon 2>/dev/null || true
+    rm -f "$UNIT_PATH"
+    systemctl --user daemon-reload
+    echo "Uninstalled: systemd service removed"
+  else
+    echo "Not installed (no unit file found)"
+  fi
+}
+
+status_linux() {
+  if systemctl --user is-active openclaw-memory-daemon >/dev/null 2>&1; then
+    systemctl --user status openclaw-memory-daemon --no-pager
+  else
+    echo "Not running"
+  fi
+}
+
+# ============================================================
+# Windows/Fallback — pm2
+# ============================================================
+
+install_pm2() {
+  if ! command -v pm2 >/dev/null 2>&1; then
+    echo "pm2 not found. Installing globally..."
+    npm install -g pm2
+  fi
+
+  # Stop if already running
+  pm2 stop openclaw-memory-daemon 2>/dev/null || true
+  pm2 delete openclaw-memory-daemon 2>/dev/null || true
+
+  pm2 start "$DAEMON_SCRIPT" \
+    --name openclaw-memory-daemon \
+    --cwd "$WORKSPACE" \
+    --log "$WORKSPACE/.tmp/memory-daemon.log" \
+    --error "$WORKSPACE/.tmp/memory-daemon.err" \
+    --env "OPENCLAW_WORKSPACE=$WORKSPACE" \
+    --env "TZ=America/Montreal"
+
+  pm2 save
+
+  echo "Installed: pm2 process 'openclaw-memory-daemon'"
+  echo ""
+  echo "Commands:"
+  echo "  pm2 status openclaw-memory-daemon"
+  echo "  pm2 stop openclaw-memory-daemon"
+  echo "  pm2 restart openclaw-memory-daemon"
+  echo "  pm2 logs openclaw-memory-daemon"
+  echo ""
+  echo "To persist across reboots: pm2 startup"
+}
+
+uninstall_pm2() {
+  if command -v pm2 >/dev/null 2>&1; then
+    pm2 stop openclaw-memory-daemon 2>/dev/null || true
+    pm2 delete openclaw-memory-daemon 2>/dev/null || true
+    pm2 save
+    echo "Uninstalled: pm2 process removed"
+  else
+    echo "pm2 not found"
+  fi
+}
+
+status_pm2() {
+  if command -v pm2 >/dev/null 2>&1; then
+    pm2 describe openclaw-memory-daemon 2>/dev/null || echo "Not running"
+  else
+    echo "pm2 not found"
+  fi
+}
+
+# ============================================================
+# MAIN
+# ============================================================
+
+ACTION="${1:-install}"
+
+echo "OpenClaw Memory Daemon Installer"
+echo "OS: $OS | Node: $NODE_BIN (v$NODE_VERSION)"
+echo "Workspace: $WORKSPACE"
+echo ""
+
+case "$ACTION" in
+  install|--install)
+    case "$OS" in
+      macos)   install_macos ;;
+      linux)   install_linux ;;
+      *)       install_pm2 ;;
+    esac
+    ;;
+  uninstall|--uninstall)
+    case "$OS" in
+      macos)   uninstall_macos ;;
+      linux)   uninstall_linux ;;
+      *)       uninstall_pm2 ;;
+    esac
+    ;;
+  status|--status)
+    case "$OS" in
+      macos)   status_macos ;;
+      linux)   status_linux ;;
+      *)       status_pm2 ;;
+    esac
+    ;;
+  *)
+    echo "Usage: install-daemon [install|uninstall|status]"
+    exit 1
+    ;;
+esac

package/workspace-bin/lane-watchdog.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+/**
+ * lane-watchdog.js — Gateway Lane Deadlock Recovery
+ *
+ * Monitors gateway logs for stuck lanes (agent timeout → lane deadlock).
+ * When a lane is blocked beyond threshold, sends SIGUSR1 to trigger
+ * resetAllLanes() inside the gateway process.
+ *
+ * Created: 2026-03-08 22:10 America/Montreal
+ *
+ * Pattern: same as gateway health-monitor (stale Discord socket → restart).
+ * Difference: this catches lane-level deadlocks the health-monitor misses.
+ *
+ * Signals:
+ *   - "embedded run timeout" in logs → agent timed out
+ *   - "lane wait exceeded" with waitedMs > threshold → lane is stuck
+ *   - Both together within window → deadlock confirmed, send SIGUSR1
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// --- Configuration ---
+const GATEWAY_LOG = process.env.GATEWAY_LOG
+  || path.join(process.env.HOME, '.openclaw/logs/gateway.log');
+const GATEWAY_ERR_LOG = process.env.GATEWAY_ERR_LOG
+  || path.join(process.env.HOME, '.openclaw/logs/gateway.err.log');
+
+const LANE_STUCK_THRESHOLD_MS = 5 * 60 * 1000;   // 5 min before intervention
+const POLL_INTERVAL_MS = 15_000;                   // check every 15s
+const COOLDOWN_MS = 60_000;                        // 1 min cooldown after SIGUSR1
+const INCIDENT_LOG = path.join(process.env.HOME, 'openclaw/shared/lane-watchdog.log');
+
+// --- State ---
+let lastInterventionAt = 0;
+let logWatcher = null;
+let errWatcher = null;
+
+// Track detected events
+const events = {
+  agentTimeout: null,    // timestamp of last "embedded run timeout"
+  laneWaitExceeded: null // { timestamp, waitedMs, lane }
+};
+
+// --- Helpers ---
+function log(msg) {
+  const ts = new Date().toISOString();
+  const line = `${ts} [lane-watchdog] ${msg}`;
+  console.log(line);
+  try {
+    fs.appendFileSync(INCIDENT_LOG, line + '\n');
+  } catch { /* best effort */ }
+}
+
+function getGatewayPid() {
+  try {
+    // Gateway runs as "openclaw-gateway" process (renamed by the framework)
+    const out = execSync(
+      'pgrep -x openclaw-gateway',
+      { encoding: 'utf8', timeout: 5000 }
+    ).trim();
+    const pids = out.split('\n').filter(Boolean);
+    return pids.length > 0 ? parseInt(pids[0], 10) : null;
+  } catch {
+    return null;
+  }
+}
+
+function sendSigusr1(pid, reason) {
+  const now = Date.now();
+  if (now - lastInterventionAt < COOLDOWN_MS) {
+    log(`SKIP: cooldown active (${Math.round((COOLDOWN_MS - (now - lastInterventionAt)) / 1000)}s remaining)`);
+    return false;
+  }
+
+  log(`INTERVENTION: sending SIGUSR1 to gateway pid=${pid} reason="${reason}"`);
+  try {
+    process.kill(pid, 'SIGUSR1');
+    lastInterventionAt = now;
+    log(`SIGUSR1 sent successfully. Gateway will resetAllLanes().`);
+    // Clear tracked events after intervention
+    events.agentTimeout = null;
+    events.laneWaitExceeded = null;
+    return true;
+  } catch (err) {
+    log(`ERROR: failed to send SIGUSR1: ${err.message}`);
+    return false;
+  }
+}
+
+// --- Log Line Parsing ---
+function parseLine(line) {
+  // Match: embedded run timeout
+  // Example: 2026-03-08T21:31:23.589-05:00 [agent/embedded] embedded run timeout: runId=...
+  if (line.includes('embedded run timeout')) {
+    const tsMatch = line.match(/^(\d{4}-\d{2}-\d{2}T[\d:.+-]+)/);
+    const ts = tsMatch ? new Date(tsMatch[1]).getTime() : Date.now();
+    events.agentTimeout = ts;
+    log(`DETECTED: agent timeout at ${new Date(ts).toISOString()}`);
+    checkForDeadlock();
+    return;
+  }
+
+  // Match: lane wait exceeded
+  // Example: [diagnostic] lane wait exceeded: lane=session:agent:main:main waitedMs=551882 queueAhead=0
+  const laneMatch = line.match(/lane wait exceeded:.*?lane=(\S+)\s+waitedMs=(\d+)/);
+  if (laneMatch) {
+    const lane = laneMatch[1];
+    const waitedMs = parseInt(laneMatch[2], 10);
+    const tsMatch = line.match(/^(\d{4}-\d{2}-\d{2}T[\d:.+-]+)/);
+    const ts = tsMatch ? new Date(tsMatch[1]).getTime() : Date.now();
+
+    events.laneWaitExceeded = { timestamp: ts, waitedMs, lane };
+    log(`DETECTED: lane "${lane}" waited ${Math.round(waitedMs / 1000)}s`);
+
+    if (waitedMs >= LANE_STUCK_THRESHOLD_MS) {
+      checkForDeadlock();
+    }
+    return;
+  }
+
+  // Match: LLM request timed out (failover error)
+  if (line.includes('LLM request timed out') && line.includes('lane=')) {
+    const tsMatch = line.match(/^(\d{4}-\d{2}-\d{2}T[\d:.+-]+)/);
+    const ts = tsMatch ? new Date(tsMatch[1]).getTime() : Date.now();
+    events.agentTimeout = ts;
+    log(`DETECTED: LLM timeout at ${new Date(ts).toISOString()}`);
+    checkForDeadlock();
+    return;
+  }
+}
+
+function checkForDeadlock() {
+  // Case 1: Lane wait exceeded threshold on its own
+  if (events.laneWaitExceeded && events.laneWaitExceeded.waitedMs >= LANE_STUCK_THRESHOLD_MS) {
+    const pid = getGatewayPid();
+    if (pid) {
+      sendSigusr1(pid, `lane "${events.laneWaitExceeded.lane}" blocked for ${Math.round(events.laneWaitExceeded.waitedMs / 1000)}s`);
+    } else {
+      log('WARNING: gateway PID not found, cannot send signal');
+    }
+    return;
+  }
+
+  // Case 2: Agent timeout + lane wait within 2-minute window
+  if (events.agentTimeout && events.laneWaitExceeded) {
+    const timeDiff = Math.abs(events.agentTimeout - events.laneWaitExceeded.timestamp);
+    if (timeDiff < 2 * 60 * 1000) {
+      const pid = getGatewayPid();
+      if (pid) {
+        sendSigusr1(pid, `agent timeout + lane wait detected within ${Math.round(timeDiff / 1000)}s`);
+      } else {
+        log('WARNING: gateway PID not found, cannot send signal');
+      }
+    }
+  }
+}
+
+// --- Log Tailing ---
+function tailLog(filePath, label) {
+  let fileSize = 0;
+  try {
+    const stat = fs.statSync(filePath);
+    fileSize = stat.size; // Start from current end
+  } catch {
+    log(`WARNING: log file not found: ${filePath}`);
+    return null;
+  }
+
+  log(`Tailing ${label}: ${filePath} (from byte ${fileSize})`);
+
+  const watcher = fs.watch(filePath, { persistent: true }, () => {
+    try {
+      const stat = fs.statSync(filePath);
+      if (stat.size < fileSize) {
+        // Log was rotated
+        fileSize = 0;
+      }
+      if (stat.size > fileSize) {
+        const stream = fs.createReadStream(filePath, {
+          start: fileSize,
+          end: stat.size,
+          encoding: 'utf8'
+        });
+        let buffer = '';
+        stream.on('data', chunk => { buffer += chunk; });
+        stream.on('end', () => {
+          const lines = buffer.split('\n').filter(Boolean);
+          for (const line of lines) {
+            parseLine(line);
+          }
+          fileSize = stat.size;
+        });
+      }
+    } catch (err) {
+      log(`ERROR: reading ${label}: ${err.message}`);
+    }
+  });
+
+  return watcher;
+}
+
+// --- Main ---
+function main() {
+  log('Starting lane watchdog');
+  log(`Config: threshold=${LANE_STUCK_THRESHOLD_MS / 1000}s, poll=${POLL_INTERVAL_MS / 1000}s, cooldown=${COOLDOWN_MS / 1000}s`);
+
+  const pid = getGatewayPid();
+  if (pid) {
+    log(`Gateway PID: ${pid}`);
+  } else {
+    log('WARNING: gateway not running — will retry on detection');
+  }
+
+  logWatcher = tailLog(GATEWAY_LOG, 'gateway.log');
+  errWatcher = tailLog(GATEWAY_ERR_LOG, 'gateway.err.log');
+
+  // Graceful shutdown
+  for (const sig of ['SIGTERM', 'SIGINT']) {
+    process.on(sig, () => {
+      log(`Received ${sig}, shutting down`);
+      if (logWatcher) fs.unwatchFile(GATEWAY_LOG);
+      if (errWatcher) fs.unwatchFile(GATEWAY_ERR_LOG);
+      process.exit(0);
+    });
+  }
+
+  log('Lane watchdog active');
+}
+
+main();

package/workspace-bin/lib/frontmatter.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+"""
+Lightweight YAML frontmatter parser for SKILL.md files.
+Regex-based, no external dependencies.
+
+Usage:
+    from lib.frontmatter import parse_frontmatter
+
+    fm, body = parse_frontmatter(text)
+    # fm = dict with parsed fields
+    # body = remaining markdown after frontmatter
+"""
+
+import re
+
+_FM_RE = re.compile(r"\A---\s*\n(.*?\n)---\s*\n?", re.DOTALL)
+_LIST_ITEM_RE = re.compile(r'^\s*-\s+"?([^"]*?)"?\s*$')
+
+
+def parse_frontmatter(text: str) -> tuple[dict, str]:
+    """Parse YAML frontmatter from text.
+
+    Returns (frontmatter_dict, body_text).
+    If no frontmatter found, returns ({}, full_text).
+    """
+    m = _FM_RE.match(text)
+    if not m:
+        return {}, text
+
+    raw = m.group(1)
+    body = text[m.end():]
+    fm = _parse_yaml_lite(raw)
+    return fm, body
+
+
+def _parse_yaml_lite(raw: str) -> dict:
+    """Minimal YAML parser for SKILL.md frontmatter.
+
+    Handles:
+      - key: value (scalar)
+      - key: "quoted value"
+      - key: |  (multiline block)
+      - key:\\n  - item1\\n  - item2  (list)
+      - Nested metadata blocks (treated as raw string)
+    """
+    result = {}
+    lines = raw.split("\n")
+    i = 0
+
+    while i < len(lines):
+        line = lines[i]
+
+        # Skip blank lines and comments
+        if not line.strip() or line.strip().startswith("#"):
+            i += 1
+            continue
+
+        # Match top-level key: value
+        kv = re.match(r"^(\w[\w\-]*):\s*(.*)", line)
+        if not kv:
+            i += 1
+            continue
+
+        key = kv.group(1)
+        value = kv.group(2).strip()
+
+        # Check if next lines are list items
+        if value == "" and i + 1 < len(lines):
+            next_line = lines[i + 1] if i + 1 < len(lines) else ""
+            if re.match(r"^\s+-\s+", next_line):
+                # Parse list
+                items = []
+                i += 1
+                while i < len(lines) and re.match(r"^\s+-\s+", lines[i]):
+                    item_match = _LIST_ITEM_RE.match(lines[i])
+                    if item_match:
+                        items.append(item_match.group(1))
+                    else:
+                        val = re.sub(r"^\s+-\s+", "", lines[i]).strip().strip('"')
+                        items.append(val)
+                    i += 1
+                result[key] = items
+                continue
+            elif re.match(r"^\s+\S", next_line):
+                # Nested block (metadata, etc.) — capture as raw string
+                block_lines = []
+                i += 1
+                while i < len(lines) and (lines[i].startswith("  ") or lines[i].startswith("\t") or not lines[i].strip()):
+                    block_lines.append(lines[i])
+                    i += 1
+                result[key] = "\n".join(block_lines).strip()
+                continue
+
+        # Block scalar (| or >-)
+        if value in ("|", ">", ">-", "|-"):
+            block_lines = []
+            i += 1
+            while i < len(lines) and (lines[i].startswith("  ") or lines[i].startswith("\t") or not lines[i].strip()):
+                block_lines.append(lines[i].strip())
+                i += 1
+            if value.startswith(">"):
+                # Folded scalar: join lines with spaces
+                result[key] = " ".join(line for line in block_lines if line).strip()
+            else:
+                result[key] = "\n".join(block_lines).strip()
+            continue
+
+        # Simple scalar
+        value = value.strip('"').strip("'")
+        result[key] = value
+        i += 1
+
+    return result