clawmatrix 0.1.23 → 0.2.1

package/src/handoff.ts

@@ -1,6 +1,6 @@
 import type { PeerManager } from "./peer-manager.ts";
 import type { ClawMatrixConfig } from "./config.ts";
-import { spawnProcess } from "./compat.ts";
+import type { GatewayInfo } from "./tool-proxy.ts";
 import type {
   HandoffRequest,
   HandoffResponse,
@@ -12,6 +12,7 @@ import type {
   HandoffInput,
   HandoffStatus,
 } from "./types.ts";
+import { TaskActivityBroadcaster } from "./task-activity.ts";
 
 const DEFAULT_HANDOFF_TIMEOUT = 600_000; // 10 minutes (resets on each stream chunk)
 const MAX_RETRIES = 2;
@@ -32,7 +33,7 @@ interface PendingHandoff {
 }
 
 interface ActiveHandoff {
-  proc: { kill: () => void; exited: Promise<number> } | null;
+  abortController: AbortController | null;
   status: HandoffStatus;
   sessionId: string;
   agent: string;
@@ -44,19 +45,46 @@ interface ActiveHandoff {
 export class HandoffManager {
   private config: ClawMatrixConfig;
   private peerManager: PeerManager;
+  private gatewayInfo: GatewayInfo;
   private pending = new Map<string, PendingHandoff>();
   private active = new Map<string, ActiveHandoff>();
   private inputRequiredTargets = new Map<string, string>(); // handoffId → targetNodeId
   private staleCleanupTimer: ReturnType<typeof setInterval> | null = null;
+  private taskActivity: TaskActivityBroadcaster;
+  // Multi-device sync: track which nodes are watching each handoff session (by sessionId)
+  private sessionWatchers = new Map<string, Set<string>>();
 
-  constructor(config: ClawMatrixConfig, peerManager: PeerManager) {
+  constructor(config: ClawMatrixConfig, peerManager: PeerManager, gatewayInfo: GatewayInfo) {
     this.config = config;
     this.peerManager = peerManager;
+    this.gatewayInfo = gatewayInfo;
+    this.taskActivity = new TaskActivityBroadcaster(config, peerManager);
 
     // Periodically clean up stale input_required entries
     this.staleCleanupTimer = setInterval(() => this.cleanupStale(), STALE_CLEANUP_INTERVAL);
   }
 
+  // ── Multi-device sync helpers ──────────────────────────────────
+
+  private addSessionWatcher(sessionId: string, nodeId: string) {
+    let watchers = this.sessionWatchers.get(sessionId);
+    if (!watchers) {
+      watchers = new Set();
+      this.sessionWatchers.set(sessionId, watchers);
+    }
+    watchers.add(nodeId);
+  }
+
+  /** Send a handoff frame to all session watchers except the specified node. */
+  private sendToOtherWatchers(sessionId: string, exclude: string, frame: HandoffStreamChunk | HandoffResponse | HandoffInputRequired) {
+    const watchers = this.sessionWatchers.get(sessionId);
+    if (!watchers) return;
+    for (const nodeId of watchers) {
+      if (nodeId === exclude) continue;
+      this.peerManager.sendTo(nodeId, { ...frame, to: nodeId });
+    }
+  }
+
   /** Remove stale input_required and canceled entries that exceeded TTL. */
   private cleanupStale() {
     const now = Date.now();
@@ -260,13 +288,21 @@ export class HandoffManager {
       return;
     }
 
-    const sessionId = `handoff-${id}`;
+    // Derive a stable session key from agent + requester nodeId.
+    // This keeps OpenClaw sessions persistent across handoffs from the same peer,
+    // avoiding repeated Session Startup (bootstrap file loading).
+    const sessionId = payload.sessionId ?? `handoff-${from}`;
+    const sessionKey = `agent:${agent.id}:clawmatrix-handoff:${sessionId}`;
     const message = payload.context
       ? `${payload.task}\n\nContext:\n${payload.context}`
       : payload.task;
+    const images = payload.images;
+
+    // Track this node as a session watcher for multi-device sync
+    this.addSessionWatcher(sessionId, from);
 
     const activeEntry: ActiveHandoff = {
-      proc: null,
+      abortController: null,
       status: "working",
       sessionId,
       agent: agent.id,
@@ -276,7 +312,14 @@ export class HandoffManager {
     };
     this.active.set(id, activeEntry);
 
-    await this.runAgentTurn(id, agent.id, message, sessionId, from, activeEntry);
+    // Broadcast task started to mobile nodes
+    this.taskActivity.broadcast(id, "handoff", "started", agent.id, activeEntry.startedAt, payload.task.slice(0, 100));
+
+    // Send the user's message directly — no special startup handling needed.
+    // If this is a new OpenClaw session, the agent will execute its Session Startup
+    // naturally (reading AGENTS.md, SOUL.md, etc.) before responding, just like
+    // Feishu/Telegram do on a new session with a user message.
+    await this.runAgentTurn(id, agent.id, message, sessionKey, from, activeEntry, images);
   }
 
   /** Handle incoming handoff_input (resume agent with user reply). */
@@ -288,67 +331,82 @@ export class HandoffManager {
     if (frame.from !== entry.from) return;
 
     entry.status = "working";
-    await this.runAgentTurn(frame.id, entry.agent, frame.payload.message, entry.sessionId, entry.from, entry);
+    const sessionKey = `agent:${entry.agent}:clawmatrix-handoff:${entry.sessionId}`;
+    await this.runAgentTurn(frame.id, entry.agent, frame.payload.message, sessionKey, entry.from, entry, frame.payload.images);
   }
 
-  /** Shared logic: spawn agent subprocess, stream output, handle input_required or completion. */
+  /** Invoke agent via local gateway HTTP API (/v1/chat/completions). */
   private async runAgentTurn(
     id: string,
     agent: string,
     message: string,
-    sessionId: string,
+    sessionKey: string,
     from: string,
     activeEntry: ActiveHandoff,
+    images?: import("./types.ts").ImageContent[],
   ): Promise<void> {
-    try {
-      const proc = spawnProcess(
-        ["openclaw", "agent", "--agent", agent, "--message", message, "--session-id", sessionId],
-        { stdout: "pipe", stderr: "pipe" },
-      );
-      activeEntry.proc = proc;
+    const { port, authHeader } = this.gatewayInfo;
+    const abortController = new AbortController();
+    activeEntry.abortController = abortController;
 
-      // If cancel arrived between active.set() and proc assignment, kill immediately
-      if (activeEntry.status === "canceled") {
-        proc.kill();
-        this.active.delete(id);
-        return;
+    if (activeEntry.status === "canceled") {
+      this.active.delete(id);
+      return;
+    }
+
+    try {
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        "X-OpenClaw-Agent-Id": agent,
+        "X-OpenClaw-Session-Key": sessionKey,
+        "X-OpenClaw-Message-Channel": "clawmatrix",
+      };
+      if (authHeader) headers["Authorization"] = authHeader;
+
+      // Build message content: plain string if no images, multimodal array otherwise
+      let content: string | unknown[];
+      if (images && images.length > 0) {
+        content = [
+          { type: "text", text: message },
+          ...images.map((img) => ({
+            type: "image_url",
+            image_url: { url: `data:${img.mediaType};base64,${img.data}` },
+          })),
+        ];
+      } else {
+        content = message;
       }
 
-      // Consume stderr concurrently to prevent pipe buffer deadlock
-      const stderrPromise = proc.stderr ? drainStream(proc.stderr) : Promise.resolve("");
-      const { output, inputRequired } = await this.streamStdout(proc.stdout, id, from);
-      const [exitCode, stderr] = await Promise.all([proc.exited, stderrPromise]);
+      const res = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          model: "openclaw",
+          stream: true,
+          messages: [{ role: "user", content }],
+        }),
+        signal: abortController.signal,
+      });
 
-      if (activeEntry.status === "canceled") {
-        this.active.delete(id);
-        return;
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Gateway returned ${res.status}: ${text}`);
       }
 
-      if (inputRequired) {
-        const marker = "[INPUT_REQUIRED]";
-        const question = output.slice(output.indexOf(marker) + marker.length).trim();
-        activeEntry.status = "input_required";
-        activeEntry.inputRequiredAt = Date.now();
+      const output = await this.streamSSE(res, id, from, activeEntry.sessionId);
 
-        this.peerManager.sendTo(from, {
-          type: "handoff_input_required",
-          id,
-          from: this.config.nodeId,
-          to: from,
-          timestamp: Date.now(),
-          payload: { message: question },
-        } satisfies HandoffInputRequired);
+      if (activeEntry.status === "canceled") {
+        this.active.delete(id);
         return;
       }
 
-      if (exitCode !== 0) {
-        throw new Error(`Agent exited with code ${exitCode}: ${stderr}`);
-      }
-
       activeEntry.status = "completed";
       this.active.delete(id);
 
-      this.peerManager.sendTo(from, {
+      // Broadcast task completed
+      this.taskActivity.broadcast(id, "handoff", "completed", agent, activeEntry.startedAt);
+
+      const resFrame: HandoffResponse = {
         type: "handoff_res",
         id,
         from: this.config.nodeId,
@@ -359,8 +417,11 @@ export class HandoffManager {
           nodeId: this.config.nodeId,
           agent,
           result: output.trim(),
+          sessionId: activeEntry.sessionId,
         },
-      } satisfies HandoffResponse);
+      };
+      this.peerManager.sendTo(from, resFrame);
+      this.sendToOtherWatchers(activeEntry.sessionId, from, resFrame);
     } catch (err) {
       if (activeEntry.status === "canceled") {
         this.active.delete(id);
@@ -369,6 +430,12 @@ export class HandoffManager {
       activeEntry.status = "failed";
       this.active.delete(id);
 
+      // Broadcast task failed
+      this.taskActivity.broadcast(
+        id, "handoff", "failed", agent, activeEntry.startedAt,
+        err instanceof Error ? err.message : String(err),
+      );
+
       this.peerManager.sendTo(from, {
         type: "handoff_res",
         id,
@@ -385,55 +452,82 @@ export class HandoffManager {
     }
   }
 
-  /** Read stdout incrementally, sending handoff_stream chunks to the caller. */
-  private async streamStdout(
-    stdout: ReadableStream | null,
+  /** Parse SSE streaming response and relay as handoff_stream chunks. */
+  private async streamSSE(
+    res: Response,
     handoffId: string,
     to: string,
-  ): Promise<{ output: string; inputRequired: boolean }> {
-    if (!stdout) return { output: "", inputRequired: false };
+    sessionId?: string,
+  ): Promise<string> {
+    const body = res.body;
+    if (!body) return "";
 
-    const reader = stdout.getReader();
+    const reader = body.getReader();
     const decoder = new TextDecoder();
     let full = "";
+    let buffer = "";
 
     try {
       while (true) {
         const { done, value } = await reader.read();
         if (done) break;
 
-        const chunk = decoder.decode(value, { stream: true });
-        full += chunk;
-
-        this.peerManager.sendTo(to, {
-          type: "handoff_stream",
-          id: handoffId,
-          from: this.config.nodeId,
-          to,
-          timestamp: Date.now(),
-          payload: { delta: chunk, done: false },
-        } satisfies HandoffStreamChunk);
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop()!; // keep incomplete line
+
+        for (const line of lines) {
+          if (!line.startsWith("data: ")) continue;
+          const data = line.slice(6);
+          if (data === "[DONE]") continue;
+
+          try {
+            const parsed = JSON.parse(data);
+            const delta = parsed.choices?.[0]?.delta?.content;
+            if (delta) {
+              full += delta;
+              const streamFrame: HandoffStreamChunk = {
+                type: "handoff_stream",
+                id: handoffId,
+                from: this.config.nodeId,
+                to,
+                timestamp: Date.now(),
+                payload: { delta, done: false, sessionId },
+              };
+              this.peerManager.sendTo(to, streamFrame);
+              if (sessionId) this.sendToOtherWatchers(sessionId, to, streamFrame);
+
+              // Broadcast progress to mobile nodes (throttled, detail is just
+              // a heartbeat — don't send token-level deltas as they're meaningless fragments)
+              const activeEntry = this.active.get(handoffId);
+              if (activeEntry) {
+                this.taskActivity.broadcast(
+                  handoffId, "handoff", "progress", activeEntry.agent, activeEntry.startedAt,
+                );
+              }
+            }
+          } catch {
+            // skip malformed SSE lines
+          }
+        }
       }
     } finally {
       reader.releaseLock();
     }
 
-    const INPUT_MARKER = "[INPUT_REQUIRED]";
-    if (full.indexOf(INPUT_MARKER) !== -1) {
-      return { output: full, inputRequired: true };
-    }
-
-    // Send final done marker
-    this.peerManager.sendTo(to, {
+    // Send final done marker to requester + watchers
+    const doneFrame: HandoffStreamChunk = {
       type: "handoff_stream",
       id: handoffId,
       from: this.config.nodeId,
       to,
       timestamp: Date.now(),
-      payload: { delta: "", done: true },
-    } satisfies HandoffStreamChunk);
+      payload: { delta: "", done: true, sessionId },
+    };
+    this.peerManager.sendTo(to, doneFrame);
+    if (sessionId) this.sendToOtherWatchers(sessionId, to, doneFrame);
 
-    return { output: full, inputRequired: false };
+    return full;
   }
 
   /** Handle incoming input_required from remote (requester side). */
@@ -496,7 +590,7 @@ export class HandoffManager {
 
     const wasInputRequired = entry.status === "input_required";
     entry.status = "canceled";
-    entry.proc?.kill();
+    entry.abortController?.abort();
 
     // If canceled during input_required, no runAgentTurn is running to clean up
     if (wasInputRequired) {
@@ -572,30 +666,15 @@ export class HandoffManager {
     }
     this.pending.clear();
 
-    // Kill all active tasks (working and input_required)
+    // Abort all active tasks (working and input_required)
     for (const [, entry] of this.active) {
       if (entry.status === "working" || entry.status === "input_required") {
-        entry.proc?.kill();
+        entry.abortController?.abort();
       }
     }
     this.active.clear();
     this.inputRequiredTargets.clear();
+    this.sessionWatchers.clear();
   }
 }
 
-/** Drain a ReadableStream into a string (for stderr consumption). */
-async function drainStream(stream: ReadableStream): Promise<string> {
-  const reader = stream.getReader();
-  const decoder = new TextDecoder();
-  let result = "";
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      result += decoder.decode(value, { stream: true });
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  return result;
-}

package/src/identity.ts

@@ -0,0 +1,95 @@
+/**
+ * Persistent node identity based on X25519 key pair.
+ *
+ * ## Security model (TOFU — Trust On First Use)
+ *
+ * Each node generates a persistent X25519 key pair stored in `.clawmatrix/identity.json`.
+ * The public key serves as the node's cryptographic identity:
+ *
+ * - On first connection, a new peer's public key is recorded during approval.
+ * - On subsequent connections, the peer's public key is verified against the
+ *   approved record. If the key doesn't match, the peer is treated as a new
+ *   device and must be re-approved.
+ * - This prevents nodeId impersonation: even if an attacker obtains the shared
+ *   secret and sets the same nodeId, they cannot forge the private key, so
+ *   their public key won't match the approved record.
+ *
+ * This is the same trust model used by SSH (known_hosts) and Signal (safety
+ * numbers). The known limitation is that the very first connection is vulnerable
+ * to MITM — after that, the public key is pinned.
+ *
+ * The key pair also serves as the E2EE session key exchange material. Unlike
+ * the previous ephemeral-per-connection design, using a persistent key pair
+ * means forward secrecy is reduced (compromising the private key allows
+ * decryption of past sessions). This is an acceptable tradeoff for identity
+ * binding — and the session key is still unique per connection due to the
+ * ECDH exchange with the peer's key.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import {
+  generateX25519KeyPair,
+  publicKeyToBase64,
+  type KeyPair,
+} from "./crypto.ts";
+
+const IDENTITY_FILE = "identity.json";
+
+interface IdentityData {
+  publicKey: string;   // base64
+  privateKey: string;  // base64 (PKCS8 DER)
+  createdAt: number;
+}
+
+/**
+ * Load or generate a persistent X25519 identity key pair.
+ * Stored in `<stateDir>/identity.json`.
+ */
+export function loadOrCreateIdentity(stateDir: string): KeyPair {
+  const filePath = path.join(stateDir, IDENTITY_FILE);
+
+  // Try loading existing identity
+  try {
+    if (fs.existsSync(filePath)) {
+      const raw = fs.readFileSync(filePath, "utf-8");
+      const data: IdentityData = JSON.parse(raw);
+      return keyPairFromSerialized(data.publicKey, data.privateKey);
+    }
+  } catch {
+    // Corrupted file — regenerate
+  }
+
+  // Generate new identity
+  const keyPair = generateX25519KeyPair();
+  const data: IdentityData = {
+    publicKey: publicKeyToBase64(keyPair.publicKey),
+    privateKey: keyPair.privateKey.toString("base64"),
+    createdAt: Date.now(),
+  };
+
+  // Ensure directory exists
+  if (!fs.existsSync(stateDir)) {
+    fs.mkdirSync(stateDir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+
+  return keyPair;
+}
+
+/** Reconstruct a KeyPair from serialized base64 strings. */
+function keyPairFromSerialized(publicKeyB64: string, privateKeyB64: string): KeyPair {
+  const { createPrivateKey } = require("node:crypto");
+  const publicKey = Buffer.from(publicKeyB64, "base64");
+  const privateKey = Buffer.from(privateKeyB64, "base64");
+
+  return {
+    publicKey,
+    privateKey,
+    _privateKeyObject: createPrivateKey({
+      key: privateKey,
+      format: "der",
+      type: "pkcs8",
+    }),
+  };
+}