openclaw-node-harness 2.0.0

package/lib/kanban-io.js

@@ -0,0 +1,352 @@
+/**
+ * kanban-io.js — Read/write active-tasks.md for the mesh bridge.
+ *
+ * Standalone parser (no Mission Control dependency).
+ * Handles in-place field updates to avoid clobbering concurrent writers.
+ *
+ * ARCHITECTURE NOTE — SHELF LIFE:
+ * This module uses flock() for write safety across 2-3 local processes
+ * (mesh-bridge, memory-daemon, Mission Control). flock() is a LOCAL file lock —
+ * it does NOT work across machines. When multi-node writes become necessary
+ * (e.g., remote agents updating task state), active-tasks.md as the kanban
+ * backing store must be replaced with a shared-state layer (cr-sqlite / JetStream KV).
+ * That migration is Phase 3 in the original architecture plan.
+ * Do NOT add more writers to this file. If you need a new writer, that's the signal
+ * to migrate to the shared-state layer instead.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const ACTIVE_TASKS_PATH = path.join(
+  process.env.HOME, '.openclaw', 'workspace', 'memory', 'active-tasks.md'
+);
+// ── File Locking ─────────────────────────────────────
+// mkdir-based mutual exclusion for read-modify-write cycles.
+// mkdir is atomic on POSIX — it either succeeds or fails, no partial state.
+// Prevents lost updates when mesh-bridge and memory-daemon write concurrently.
+// See architecture note above for why this is local-only.
+
+function withMkdirLock(filePath, fn) {
+  const lockDir = filePath + '.lk';
+  const maxWait = 5000; // 5s max wait
+  const start = Date.now();
+
+  // Acquire: mkdir is atomic on POSIX
+  while (true) {
+    try {
+      fs.mkdirSync(lockDir);
+      break; // got the lock
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      // Lock held by another process — check for stale lock (>30s)
+      try {
+        const lockAge = Date.now() - fs.statSync(lockDir).mtimeMs;
+        if (lockAge > 30000) {
+          // Stale lock — previous holder crashed
+          fs.rmdirSync(lockDir);
+          continue;
+        }
+      } catch { /* stat failed, lock was just released */ continue; }
+
+      if (Date.now() - start > maxWait) {
+        throw new Error(`kanban-io: lock timeout after ${maxWait}ms on ${filePath}`);
+      }
+      // Non-blocking 10ms pause (busy-wait would peg CPU in Node's single thread)
+      require('child_process').spawnSync('sleep', ['0.01']);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    try { fs.rmdirSync(lockDir); } catch { /* already released */ }
+  }
+}
+
+// ── Parser ──────────────────────────────────────────
+
+/**
+ * Parse active-tasks.md into task objects.
+ * Only reads the "## Live Tasks" section.
+ */
+function readTasks(filePath = ACTIVE_TASKS_PATH) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  return parseTasks(content);
+}
+
+function parseTasks(content) {
+  const tasks = [];
+  const liveIdx = content.indexOf('## Live Tasks');
+  if (liveIdx === -1) return tasks;
+
+  const afterLive = content.slice(liveIdx);
+  const nextSectionIdx = afterLive.indexOf('\n## ', 1); // skip the current ## Live Tasks
+  const liveSection = nextSectionIdx >= 0 ? afterLive.slice(0, nextSectionIdx) : afterLive;
+  const lines = liveSection.split('\n');
+
+  let current = null;
+  let currentArrayKey = null;
+
+  function flush() {
+    if (current && current.task_id) {
+      tasks.push({
+        task_id: current.task_id,
+        title: current.title || '',
+        status: current.status || 'queued',
+        owner: current.owner || null,
+        success_criteria: current.success_criteria || [],
+        artifacts: current.artifacts || [],
+        next_action: current.next_action || null,
+        description: current.description || null,
+        needs_approval: current.needs_approval !== false, // default true
+        auto_priority: current.auto_priority || 0,
+        project: current.project || null,
+        parent_id: current.parent_id || null,
+        // Mesh-specific fields
+        execution: current.execution || null,
+        metric: current.metric || null,
+        budget_minutes: current.budget_minutes || 30,
+        scope: current.scope || [],
+        updated_at: current.updated_at || '',
+      });
+    }
+  }
+
+  for (const line of lines) {
+    // New task block
+    const taskIdMatch = line.match(/^- task_id:\s*(.+)$/);
+    if (taskIdMatch) {
+      flush();
+      current = { task_id: taskIdMatch[1].trim(), success_criteria: [], artifacts: [], scope: [] };
+      currentArrayKey = null;
+      continue;
+    }
+
+    if (!current) continue;
+
+    // Array item: 4-space indent + dash
+    const arrayItemMatch = line.match(/^    - (.+)$/);
+    if (arrayItemMatch && currentArrayKey) {
+      current[currentArrayKey].push(arrayItemMatch[1].trim());
+      continue;
+    }
+
+    // Field: 2-space indent
+    const fieldMatch = line.match(/^  (\w[\w_]*):\s*(.*)$/);
+    if (fieldMatch) {
+      const [, key, rawValue] = fieldMatch;
+      const value = rawValue.trim();
+
+      switch (key) {
+        case 'title': current.title = value; currentArrayKey = null; break;
+        case 'status': current.status = value; currentArrayKey = null; break;
+        case 'owner': current.owner = value || null; currentArrayKey = null; break;
+        case 'next_action': current.next_action = value || null; currentArrayKey = null; break;
+        case 'project': current.project = value || null; currentArrayKey = null; break;
+        case 'parent_id': current.parent_id = value || null; currentArrayKey = null; break;
+        case 'auto_priority': current.auto_priority = parseInt(value, 10) || 0; currentArrayKey = null; break;
+        case 'updated_at': current.updated_at = value; currentArrayKey = null; break;
+        case 'description':
+          current.description = value ? value.replace(/\\n/g, '\n') : null;
+          currentArrayKey = null;
+          break;
+        case 'needs_approval':
+          current.needs_approval = value === 'true' || value === '1';
+          currentArrayKey = null;
+          break;
+        // Mesh fields
+        case 'execution': current.execution = value || null; currentArrayKey = null; break;
+        case 'metric': current.metric = value || null; currentArrayKey = null; break;
+        case 'budget_minutes':
+          current.budget_minutes = parseInt(value, 10) || 30;
+          currentArrayKey = null;
+          break;
+        // Array fields
+        case 'success_criteria':
+          current.success_criteria = [];
+          currentArrayKey = 'success_criteria';
+          break;
+        case 'artifacts':
+          current.artifacts = [];
+          currentArrayKey = 'artifacts';
+          break;
+        case 'scope':
+          current.scope = [];
+          currentArrayKey = 'scope';
+          break;
+        default:
+          currentArrayKey = null;
+          break;
+      }
+      continue;
+    }
+
+    if (line.trim() === '') {
+      currentArrayKey = null;
+    }
+  }
+
+  flush();
+  return tasks;
+}
+
+// ── In-Place Updater ────────────────────────────────
+
+/**
+ * Update specific fields of a task in active-tasks.md without re-serializing the whole file.
+ * Finds the task block by task_id, modifies/adds fields, writes atomically.
+ *
+ * fieldUpdates: { status: 'waiting-user', owner: 'mesh-agent', ... }
+ * arrayUpdates: { artifacts: ['path/to/log'], success_criteria: ['Step 1 PASS'] }
+ *   - Arrays are APPENDED to existing values, not replaced
+ * arrayReplace: { success_criteria: ['new list'] }
+ *   - Arrays are REPLACED entirely
+ */
+function updateTaskInPlace(filePath, taskId, fieldUpdates = {}, arrayAppend = {}, arrayReplace = {}) {
+  return withMkdirLock(filePath, () => _updateTaskInPlaceUnsafe(filePath, taskId, fieldUpdates, arrayAppend, arrayReplace));
+}
+
+function _updateTaskInPlaceUnsafe(filePath, taskId, fieldUpdates = {}, arrayAppend = {}, arrayReplace = {}) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+
+  // Find task block boundaries
+  let blockStart = -1;
+  let blockEnd = lines.length;
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(/^- task_id:\s*(.+)$/);
+    if (match) {
+      if (match[1].trim() === taskId) {
+        blockStart = i;
+      } else if (blockStart >= 0) {
+        blockEnd = i;
+        break;
+      }
+    }
+  }
+
+  if (blockStart === -1) {
+    throw new Error(`Task ${taskId} not found in ${filePath}`);
+  }
+
+  // Extract the block
+  const blockLines = lines.slice(blockStart, blockEnd);
+
+  // Update scalar fields
+  for (const [key, value] of Object.entries(fieldUpdates)) {
+    const fieldRegex = new RegExp(`^  ${key}:\\s*.*$`);
+    let found = false;
+    for (let i = 1; i < blockLines.length; i++) {
+      if (fieldRegex.test(blockLines[i])) {
+        blockLines[i] = `  ${key}: ${value}`;
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      // Insert before updated_at if it exists, otherwise at end of block
+      const updatedAtIdx = blockLines.findIndex(l => l.match(/^  updated_at:/));
+      const insertIdx = updatedAtIdx >= 0 ? updatedAtIdx : blockLines.length;
+      blockLines.splice(insertIdx, 0, `  ${key}: ${value}`);
+    }
+  }
+
+  // Replace arrays entirely
+  for (const [key, items] of Object.entries(arrayReplace)) {
+    const headerRegex = new RegExp(`^  ${key}:`);
+    let headerIdx = blockLines.findIndex(l => headerRegex.test(l));
+
+    if (headerIdx === -1) {
+      // Insert the array before updated_at
+      const updatedAtIdx = blockLines.findIndex(l => l.match(/^  updated_at:/));
+      const insertIdx = updatedAtIdx >= 0 ? updatedAtIdx : blockLines.length;
+      const newLines = [`  ${key}:`];
+      for (const item of items) {
+        newLines.push(`    - ${item}`);
+      }
+      blockLines.splice(insertIdx, 0, ...newLines);
+    } else {
+      // Remove existing array items
+      let endIdx = headerIdx + 1;
+      while (endIdx < blockLines.length && blockLines[endIdx].match(/^    - /)) {
+        endIdx++;
+      }
+      const newLines = [`  ${key}:`];
+      for (const item of items) {
+        newLines.push(`    - ${item}`);
+      }
+      blockLines.splice(headerIdx, endIdx - headerIdx, ...newLines);
+    }
+  }
+
+  // Append to arrays
+  for (const [key, items] of Object.entries(arrayAppend)) {
+    const headerRegex = new RegExp(`^  ${key}:`);
+    let headerIdx = blockLines.findIndex(l => headerRegex.test(l));
+
+    if (headerIdx === -1) {
+      // Insert the array before updated_at
+      const updatedAtIdx = blockLines.findIndex(l => l.match(/^  updated_at:/));
+      const insertIdx = updatedAtIdx >= 0 ? updatedAtIdx : blockLines.length;
+      const newLines = [`  ${key}:`];
+      for (const item of items) {
+        newLines.push(`    - ${item}`);
+      }
+      blockLines.splice(insertIdx, 0, ...newLines);
+    } else {
+      // Find end of existing array items
+      let endIdx = headerIdx + 1;
+      while (endIdx < blockLines.length && blockLines[endIdx].match(/^    - /)) {
+        endIdx++;
+      }
+      // Append new items
+      const newLines = [];
+      for (const item of items) {
+        newLines.push(`    - ${item}`);
+      }
+      blockLines.splice(endIdx, 0, ...newLines);
+    }
+  }
+
+  // Reassemble
+  const newLines = [
+    ...lines.slice(0, blockStart),
+    ...blockLines,
+    ...lines.slice(blockEnd),
+  ];
+
+  // Atomic write
+  const tmpPath = filePath + '.tmp.' + process.pid;
+  fs.writeFileSync(tmpPath, newLines.join('\n'));
+  fs.renameSync(tmpPath, filePath);
+}
+
+// ── Timestamp Helper ────────────────────────────────
+
+function montrealTimestamp() {
+  return new Intl.DateTimeFormat('en-CA', {
+    timeZone: 'America/Montreal',
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  }).format(new Date()).replace(',', '') + ' America/Montreal';
+}
+
+function isoTimestamp() {
+  return new Date().toISOString();
+}
+
+module.exports = {
+  readTasks,
+  parseTasks,
+  updateTaskInPlace,
+  montrealTimestamp,
+  isoTimestamp,
+  ACTIVE_TASKS_PATH,
+};

package/lib/mesh-registry.js

@@ -0,0 +1,194 @@
+/**
+ * mesh-registry.js — NATS KV tool registry for OpenClaw mesh.
+ *
+ * Shared library for:
+ *   - Registering tools in MESH_TOOLS KV bucket
+ *   - Heartbeat refresh (keeps tools alive via TTL)
+ *   - Calling remote tools via NATS request/reply
+ *   - Listing available tools from KV
+ *
+ * Usage:
+ *   const { MeshRegistry } = require('./mesh-registry');
+ *   const registry = new MeshRegistry(natsConnection, nodeId);
+ *   await registry.register(manifest);
+ *   await registry.startHeartbeat();
+ *   const result = await registry.call('discord-history', 'readMessages', { channelId: '123' });
+ */
+
+const { connect, StringCodec } = require('nats');
+const os = require('os');
+
+const sc = StringCodec();
+const { NATS_URL, natsConnectOpts } = require('./nats-resolve');
+const KV_BUCKET = 'MESH_TOOLS';
+const HEARTBEAT_INTERVAL = 60000; // 60s (TTL is 120s — refreshes well before expiry)
+
+class MeshRegistry {
+  constructor(nc, nodeId) {
+    this.nc = nc;
+    this.nodeId = nodeId || os.hostname().toLowerCase().replace(/[^a-z0-9-]/g, '-');
+    this.kv = null;
+    this.manifests = new Map(); // toolName -> manifest
+    this.handlers = new Map(); // toolName.methodName -> handler function
+    this.heartbeatTimer = null;
+    this.subscriptions = [];
+  }
+
+  async init() {
+    const js = this.nc.jetstream();
+    this.kv = await js.views.kv(KV_BUCKET);
+    return this;
+  }
+
+  /**
+   * Register a tool manifest and subscribe to its NATS subjects.
+   * @param {object} manifest - Tool manifest (name, methods, etc.)
+   * @param {object} handlers - Map of methodName -> async function(params)
+   */
+  async register(manifest, handlers = {}) {
+    const toolName = manifest.name;
+    const kvKey = `${this.nodeId}.${toolName}`;
+
+    // Store manifest
+    const entry = {
+      ...manifest,
+      node_id: this.nodeId,
+      registered_at: new Date().toISOString(),
+    };
+    this.manifests.set(toolName, entry);
+
+    // Publish to KV
+    await this.kv.put(kvKey, sc.encode(JSON.stringify(entry)));
+
+    // Register handlers and subscribe to NATS subjects
+    for (const method of (manifest.methods || [])) {
+      const handlerKey = `${toolName}.${method.name}`;
+      const subject = `mesh.tool.${this.nodeId}.${toolName}.${method.name}`;
+
+      if (handlers[method.name]) {
+        this.handlers.set(handlerKey, handlers[method.name]);
+
+        const sub = this.nc.subscribe(subject);
+        this.subscriptions.push(sub);
+
+        // Process requests in background
+        this._processSubscription(sub, handlerKey);
+      }
+    }
+
+    return entry;
+  }
+
+  async _processSubscription(sub, handlerKey) {
+    for await (const msg of sub) {
+      try {
+        const request = JSON.parse(sc.decode(msg.data));
+        const handler = this.handlers.get(handlerKey);
+
+        if (!handler) {
+          msg.respond(sc.encode(JSON.stringify({
+            error: `No handler for ${handlerKey}`,
+          })));
+          continue;
+        }
+
+        const result = await handler(request.args || request);
+        msg.respond(sc.encode(JSON.stringify({ data: result })));
+      } catch (err) {
+        msg.respond(sc.encode(JSON.stringify({
+          error: err.message,
+          stack: process.env.NODE_ENV === 'development' ? err.stack : undefined,
+        })));
+      }
+    }
+  }
+
+  /**
+   * Start heartbeat loop — refreshes all manifests in KV every 60s.
+   */
+  startHeartbeat() {
+    this.heartbeatTimer = setInterval(async () => {
+      for (const [toolName, manifest] of this.manifests) {
+        const kvKey = `${this.nodeId}.${toolName}`;
+        try {
+          await this.kv.put(kvKey, sc.encode(JSON.stringify(manifest)));
+        } catch (err) {
+          console.error(`[mesh-registry] heartbeat failed for ${kvKey}: ${err.message}`);
+        }
+      }
+    }, HEARTBEAT_INTERVAL);
+    // Don't block process exit
+    if (this.heartbeatTimer.unref) this.heartbeatTimer.unref();
+  }
+
+  /**
+   * Call a remote tool method via NATS request/reply.
+   * @param {string} nodeId - Target node
+   * @param {string} toolName - Tool name
+   * @param {string} methodName - Method name
+   * @param {object} args - Arguments
+   * @param {number} timeoutMs - Timeout in ms (default 30s)
+   */
+  async call(nodeId, toolName, methodName, args = {}, timeoutMs = 30000) {
+    const subject = `mesh.tool.${nodeId}.${toolName}.${methodName}`;
+    const payload = JSON.stringify({ args, caller: this.nodeId });
+
+    const msg = await this.nc.request(subject, sc.encode(payload), { timeout: timeoutMs });
+    const response = JSON.parse(sc.decode(msg.data));
+
+    if (response.error) {
+      throw new Error(`Remote tool error (${subject}): ${response.error}`);
+    }
+    return response.data;
+  }
+
+  /**
+   * List all registered tools from KV bucket.
+   * @returns {Array} Array of tool manifests
+   */
+  async listTools() {
+    const tools = [];
+    const keys = await this.kv.keys();
+    for await (const key of keys) {
+      const entry = await this.kv.get(key);
+      if (entry && entry.value) {
+        tools.push(JSON.parse(sc.decode(entry.value)));
+      }
+    }
+    return tools;
+  }
+
+  /**
+   * Clean shutdown — purge own KV keys and unsubscribe.
+   */
+  async shutdown() {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+
+    // Purge own KV entries
+    for (const toolName of this.manifests.keys()) {
+      const kvKey = `${this.nodeId}.${toolName}`;
+      try {
+        await this.kv.delete(kvKey);
+      } catch (err) {
+        // Best effort
+      }
+    }
+
+    // Unsubscribe
+    for (const sub of this.subscriptions) {
+      sub.unsubscribe();
+    }
+  }
+}
+
+/**
+ * Connect to NATS and create a registry instance.
+ */
+async function createRegistry(nodeId) {
+  const nc = await connect(natsConnectOpts({ timeout: 5000 }));
+  const registry = new MeshRegistry(nc, nodeId);
+  await registry.init();
+  return { nc, registry };
+}
+
+module.exports = { MeshRegistry, createRegistry, NATS_URL, KV_BUCKET };

package/lib/mesh-roles.js

@@ -0,0 +1,13 @@
+/**
+ * mesh-roles.js — Shared role->component mapping for the OpenClaw mesh.
+ * Must match nodeFilter values in the mesh-deploy manifest.
+ */
+const ROLE_COMPONENTS = {
+  lead: ['mesh-daemons', 'mesh-cli', 'shared-lib', 'mc', 'memory-daemon',
+         'memory-harness', 'souls', 'skills', 'boot', 'workspace-docs',
+         'gateway', 'companion-bridge', 'service-defs'],
+  worker: ['mesh-daemons', 'mesh-cli', 'shared-lib', 'souls', 'skills',
+           'workspace-docs', 'service-defs'],
+};
+
+module.exports = { ROLE_COMPONENTS };