openclaw-node-harness 2.0.0

package/lib/mesh-tasks.js

@@ -0,0 +1,306 @@
+/**
+ * mesh-tasks.js — Task schema and utilities for mesh task coordination.
+ *
+ * Defines the enriched task schema (budget, metric, on_fail) and
+ * provides helpers for task state management in NATS KV.
+ */
+
+const { StringCodec } = require('nats');
+const sc = StringCodec();
+
+const KV_BUCKET = 'MESH_TASKS';
+
+// ── Task Schema ─────────────────────────────────────
+
+/**
+ * Task statuses and their meaning:
+ *   queued    — available for claiming
+ *   claimed   — agent has claimed, not yet started work
+ *   running   — agent is actively working
+ *   completed — agent reports success (pending human review)
+ *   failed    — agent reports failure or budget exceeded
+ *   released  — automation exhausted all retries, needs human triage
+ *   cancelled — manually cancelled
+ */
+const TASK_STATUS = {
+  QUEUED: 'queued',
+  CLAIMED: 'claimed',
+  RUNNING: 'running',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  RELEASED: 'released',
+  CANCELLED: 'cancelled',
+};
+
+/**
+ * Create a new task with the enriched schema.
+ * Karpathy-inspired fields: budget_minutes, metric, on_fail, scope.
+ */
+function createTask({
+  task_id,
+  title,
+  description = '',
+  budget_minutes = 30,
+  metric = null,
+  on_fail = 'revert and log approach',
+  success_criteria = [],
+  scope = [],
+  priority = 0,
+  depends_on = [],
+  tags = [],
+}) {
+  return {
+    task_id,
+    title,
+    description,
+
+    // Execution contract (Karpathy pattern)
+    budget_minutes: parseInt(budget_minutes) || 30, // NaN → 30m default. Prevents silent safety bypass.
+    metric,                   // mechanical success check (e.g. "tests pass", "val_bpb < 0.99")
+    on_fail,                  // what to do on failure
+    scope,                    // which files/paths the agent can touch
+
+    // Standard fields
+    success_criteria,
+    priority,
+    depends_on,
+    tags,
+
+    // State (managed by daemon)
+    status: TASK_STATUS.QUEUED,
+    owner: null,              // node_id that claimed it
+    created_at: new Date().toISOString(),
+    claimed_at: null,
+    started_at: null,
+    completed_at: null,
+    budget_deadline: null,    // set when claimed: claimed_at + budget_minutes
+    last_activity: null,      // updated by agent heartbeats — stall detection key
+
+    // Result (filled by agent)
+    result: null,             // { success, summary, artifacts, attempts }
+    attempts: [],             // log of approaches tried
+  };
+}
+
+// ── KV Helpers ──────────────────────────────────────
+
+class TaskStore {
+  constructor(kv) {
+    this.kv = kv;
+  }
+
+  async put(task) {
+    await this.kv.put(task.task_id, sc.encode(JSON.stringify(task)));
+    return task;
+  }
+
+  async get(taskId, { withRevision = false } = {}) {
+    const entry = await this.kv.get(taskId);
+    if (!entry || !entry.value) return null;
+    const task = JSON.parse(sc.decode(entry.value));
+    if (withRevision) {
+      return { task, revision: entry.revision };
+    }
+    return task;
+  }
+
+  async delete(taskId) {
+    await this.kv.delete(taskId);
+  }
+
+  async list(filter = {}) {
+    const tasks = [];
+
+    // Collect keys first, then fetch — avoids NATS KV iterator interference
+    const allKeys = [];
+    const keys = await this.kv.keys();
+    for await (const key of keys) {
+      allKeys.push(key);
+    }
+
+    for (const key of allKeys) {
+      const entry = await this.kv.get(key);
+      if (!entry || !entry.value) continue;
+      const task = JSON.parse(sc.decode(entry.value));
+
+      // Apply filters
+      if (filter.status && task.status !== filter.status) continue;
+      if (filter.owner && task.owner !== filter.owner) continue;
+      if (filter.tag && !task.tags.includes(filter.tag)) continue;
+
+      tasks.push(task);
+    }
+
+    // Sort by priority (higher first), then created_at (older first)
+    tasks.sort((a, b) => {
+      if (b.priority !== a.priority) return b.priority - a.priority;
+      return new Date(a.created_at) - new Date(b.created_at);
+    });
+
+    return tasks;
+  }
+
+  /**
+   * Claim the highest-priority available task for a node.
+   * Uses NATS KV revision-based CAS to prevent race conditions.
+   * Returns the claimed task, or null if nothing available.
+   */
+  async claim(nodeId) {
+    const available = await this.list({ status: TASK_STATUS.QUEUED });
+
+    // Respect dependencies: only claim tasks whose deps are all completed
+    for (const task of available) {
+      if (task.depends_on.length > 0) {
+        const depsReady = await this._checkDeps(task.depends_on);
+        if (!depsReady) continue;
+      }
+
+      // Re-read with revision for CAS
+      const result = await this.get(task.task_id, { withRevision: true });
+      if (!result || result.task.status !== TASK_STATUS.QUEUED) continue;
+
+      // Claim it
+      result.task.status = TASK_STATUS.CLAIMED;
+      result.task.owner = nodeId;
+      result.task.claimed_at = new Date().toISOString();
+      result.task.budget_deadline = new Date(
+        Date.now() + result.task.budget_minutes * 60 * 1000
+      ).toISOString();
+
+      // Atomic CAS update — fails if another agent claimed it first
+      try {
+        await this.kv.update(
+          task.task_id,
+          sc.encode(JSON.stringify(result.task)),
+          result.revision
+        );
+        return result.task;
+      } catch (err) {
+        // Revision mismatch — another agent got there first, try next task
+        continue;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Mark a task as running (agent started work).
+   */
+  async markRunning(taskId) {
+    const task = await this.get(taskId);
+    if (!task) return null;
+    task.status = TASK_STATUS.RUNNING;
+    task.started_at = new Date().toISOString();
+    await this.put(task);
+    return task;
+  }
+
+  /**
+   * Mark a task as completed with result.
+   */
+  async markCompleted(taskId, result) {
+    const task = await this.get(taskId);
+    if (!task) return null;
+    task.status = TASK_STATUS.COMPLETED;
+    task.completed_at = new Date().toISOString();
+    task.result = result;
+    await this.put(task);
+    return task;
+  }
+
+  /**
+   * Mark a task as failed with reason.
+   */
+  async markFailed(taskId, reason, attempts = []) {
+    const task = await this.get(taskId);
+    if (!task) return null;
+    task.status = TASK_STATUS.FAILED;
+    task.completed_at = new Date().toISOString();
+    task.result = { success: false, summary: reason };
+    task.attempts = attempts;
+    await this.put(task);
+    return task;
+  }
+
+  /**
+   * Log an attempt on a task (agent tried something, may or may not have worked).
+   */
+  async logAttempt(taskId, attempt) {
+    const task = await this.get(taskId);
+    if (!task) return null;
+    task.attempts.push({
+      ...attempt,
+      timestamp: new Date().toISOString(),
+    });
+    await this.put(task);
+    return task;
+  }
+
+  /**
+   * Mark a task as released — automation gave up, human must triage.
+   * Distinct from failed: failed = "didn't work", released = "we tried everything."
+   */
+  async markReleased(taskId, reason, attempts = []) {
+    const task = await this.get(taskId);
+    if (!task) return null;
+    task.status = TASK_STATUS.RELEASED;
+    task.completed_at = new Date().toISOString();
+    task.result = { success: false, summary: reason, released: true };
+    if (attempts.length > 0) task.attempts = attempts;
+    await this.put(task);
+    return task;
+  }
+
+  /**
+   * Update last_activity timestamp (agent heartbeat).
+   */
+  async touchActivity(taskId) {
+    const task = await this.get(taskId);
+    if (!task) return null;
+    task.last_activity = new Date().toISOString();
+    await this.put(task);
+    return task;
+  }
+
+  /**
+   * Check if a task has exceeded its budget.
+   */
+  isOverBudget(task) {
+    if (!task.budget_deadline) return false;
+    return new Date() > new Date(task.budget_deadline);
+  }
+
+  /**
+   * Find all running tasks that have exceeded their budget.
+   */
+  async findOverBudget() {
+    const running = await this.list({ status: TASK_STATUS.RUNNING });
+    const claimed = await this.list({ status: TASK_STATUS.CLAIMED });
+    return [...running, ...claimed].filter(t => this.isOverBudget(t));
+  }
+
+  /**
+   * Find running tasks with no activity for `stallMinutes`.
+   * Stall detection is separate from budget — a task can be within budget
+   * but the agent process may have died silently.
+   */
+  async findStalled(stallMinutes = 5) {
+    const running = await this.list({ status: TASK_STATUS.RUNNING });
+    const cutoff = Date.now() - stallMinutes * 60 * 1000;
+    return running.filter(t => {
+      const lastSignal = t.last_activity || t.started_at;
+      return lastSignal && new Date(lastSignal) < cutoff;
+    });
+  }
+
+  async _checkDeps(depIds) {
+    for (const depId of depIds) {
+      const dep = await this.get(depId);
+      if (!dep || dep.status !== TASK_STATUS.COMPLETED) return false;
+    }
+    return true;
+  }
+}
+
+module.exports = { createTask, TaskStore, TASK_STATUS, KV_BUCKET };

package/lib/nats-resolve.js

@@ -0,0 +1,108 @@
+/**
+ * nats-resolve.js — Shared NATS URL + auth resolver for the OpenClaw mesh.
+ *
+ * Every CJS script in ~/openclaw/bin/ that connects to NATS should
+ * require() this module instead of hardcoding URLs.
+ *
+ * Resolution order (4-step chain, same for URL and token):
+ *   1. $OPENCLAW_NATS / $OPENCLAW_NATS_TOKEN env vars
+ *   2. ~/.openclaw/openclaw.env file (OPENCLAW_NATS=, OPENCLAW_NATS_TOKEN=)
+ *   3. ~/openclaw/.mesh-config file (same keys)
+ *   4. Localhost fallback / no auth
+ *
+ * Usage:
+ *   const { NATS_URL, natsConnectOpts } = require('../lib/nats-resolve');
+ *   const nc = await connect(natsConnectOpts());
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Fallback IP — last resort if env var, env file, and mesh-config are all missing.
+// localhost fallback — each node should have NATS URL configured via env or config file
+const NATS_FALLBACK = 'nats://127.0.0.1:4222';
+
+/**
+ * Resolve the NATS server URL using a 4-step chain.
+ * Called once at module load time — the result is cached as NATS_URL.
+ */
+function resolveNatsUrl() {
+  // 1. Environment variable (highest priority — set by service definitions)
+  if (process.env.OPENCLAW_NATS) return process.env.OPENCLAW_NATS;
+
+  // 2. Read from ~/.openclaw/openclaw.env (user-editable config file)
+  try {
+    const envFile = path.join(os.homedir(), '.openclaw', 'openclaw.env');
+    if (fs.existsSync(envFile)) {
+      const content = fs.readFileSync(envFile, 'utf8');
+      const match = content.match(/^\s*OPENCLAW_NATS\s*=\s*(.+)/m);
+      if (match && match[1].trim()) return match[1].trim();
+    }
+  } catch {
+    // File unreadable — fall through silently
+  }
+
+  // 3. Read from ~/openclaw/.mesh-config (set by mesh installer or deploy scripts)
+  try {
+    const meshConfig = path.join(os.homedir(), 'openclaw', '.mesh-config');
+    if (fs.existsSync(meshConfig)) {
+      const content = fs.readFileSync(meshConfig, 'utf8');
+      const match = content.match(/^\s*OPENCLAW_NATS\s*=\s*(.+)/m);
+      if (match && match[1].trim()) return match[1].trim();
+    }
+  } catch {
+    // File unreadable — fall through silently
+  }
+
+  // 4. Localhost fallback
+  return NATS_FALLBACK;
+}
+
+/**
+ * Resolve the NATS auth token using the same 4-step chain.
+ * Returns null if no token is configured (auth disabled — backward compatible).
+ */
+function resolveNatsToken() {
+  // 1. Environment variable
+  if (process.env.OPENCLAW_NATS_TOKEN) return process.env.OPENCLAW_NATS_TOKEN;
+
+  // 2. ~/.openclaw/openclaw.env
+  try {
+    const envFile = path.join(os.homedir(), '.openclaw', 'openclaw.env');
+    if (fs.existsSync(envFile)) {
+      const content = fs.readFileSync(envFile, 'utf8');
+      const match = content.match(/^\s*OPENCLAW_NATS_TOKEN\s*=\s*(.+)/m);
+      if (match && match[1].trim()) return match[1].trim();
+    }
+  } catch {}
+
+  // 3. ~/openclaw/.mesh-config
+  try {
+    const meshConfig = path.join(os.homedir(), 'openclaw', '.mesh-config');
+    if (fs.existsSync(meshConfig)) {
+      const content = fs.readFileSync(meshConfig, 'utf8');
+      const match = content.match(/^\s*OPENCLAW_NATS_TOKEN\s*=\s*(.+)/m);
+      if (match && match[1].trim()) return match[1].trim();
+    }
+  } catch {}
+
+  return null;
+}
+
+// Resolve once at require() time — all consumers get the same value
+const NATS_URL = resolveNatsUrl();
+const NATS_TOKEN = resolveNatsToken();
+
+/**
+ * Build NATS connect() options with auth if configured.
+ * Drop-in replacement for { servers: NATS_URL, timeout: 5000 }.
+ * Extra opts are merged in (name, timeout, reconnect, etc.).
+ */
+function natsConnectOpts(extra = {}) {
+  const opts = { servers: NATS_URL, ...extra };
+  if (NATS_TOKEN) opts.token = NATS_TOKEN;
+  return opts;
+}
+
+module.exports = { NATS_URL, NATS_TOKEN, resolveNatsUrl, resolveNatsToken, natsConnectOpts };

package/mission-control/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

package/mission-control/drizzle/0000_simple_silhouette.sql

@@ -0,0 +1,62 @@
+CREATE TABLE `activity_log` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`event_type` text NOT NULL,
+	`task_id` text,
+	`description` text NOT NULL,
+	`timestamp` text DEFAULT (datetime('now')) NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `memory_docs` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`source` text NOT NULL,
+	`category` text,
+	`file_path` text NOT NULL,
+	`title` text,
+	`date` text,
+	`frontmatter` text,
+	`content` text NOT NULL,
+	`modified_at` text,
+	`indexed_at` text DEFAULT (datetime('now')) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `memory_docs_file_path_unique` ON `memory_docs` (`file_path`);--> statement-breakpoint
+CREATE TABLE `soul_evolution_log` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`soul_id` text NOT NULL,
+	`event_id` text NOT NULL,
+	`event_type` text NOT NULL,
+	`description` text NOT NULL,
+	`review_status` text DEFAULT 'pending' NOT NULL,
+	`commit_hash` text,
+	`reviewed_by` text,
+	`reviewed_at` text,
+	`timestamp` text DEFAULT (datetime('now')) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `soul_evolution_log_event_id_unique` ON `soul_evolution_log` (`event_id`);--> statement-breakpoint
+CREATE TABLE `soul_handoffs` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`task_id` text NOT NULL,
+	`from_soul` text NOT NULL,
+	`to_soul` text NOT NULL,
+	`reason` text,
+	`context_path` text,
+	`timestamp` text DEFAULT (datetime('now')) NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `tasks` (
+	`id` text PRIMARY KEY NOT NULL,
+	`title` text NOT NULL,
+	`status` text NOT NULL,
+	`kanban_column` text NOT NULL,
+	`owner` text,
+	`soul_id` text,
+	`handoff_source` text,
+	`handoff_reason` text,
+	`success_criteria` text,
+	`artifacts` text,
+	`next_action` text,
+	`updated_at` text NOT NULL,
+	`created_at` text DEFAULT (datetime('now')) NOT NULL,
+	`sort_order` integer DEFAULT 0
+);