@kmmao/happy-agent 0.2.2 → 0.3.0

package/dist/index.cjs

@@ -10,14 +10,22 @@ var axios = require('axios');
 var qrcode = require('qrcode-terminal');
 var node_events = require('node:events');
 var socket_ioClient = require('socket.io-client');
+var child_process = require('child_process');
+var util = require('util');
+var promises = require('fs/promises');
+var crypto = require('crypto');
+var path = require('path');
+var fs = require('fs');
+var os = require('os');
 
-var version = "0.2.2";
+var version = "0.3.0";
 
 function loadConfig() {
-  const serverUrl = (process.env.HAPPY_SERVER_URL ?? "https://api.cluster-fluster.com").replace(/\/+$/, "");
+  const serverUrl = (process.env.HAPPY_SERVER_URL ?? "https://happyserve.xycloud.info").replace(/\/+$/, "");
+  const webappUrl = (process.env.HAPPY_WEBAPP_URL ?? "https://happyapp.xycloud.info").replace(/\/+$/, "");
   const homeDir = process.env.HAPPY_HOME_DIR ?? node_path.join(node_os.homedir(), ".happy");
   const credentialPath = node_path.join(homeDir, "agent.key");
-  return { serverUrl, homeDir, credentialPath };
+  return { serverUrl, webappUrl, homeDir, credentialPath };
 }
 
 function encodeBase64(buffer) {
@@ -184,7 +192,7 @@ function requireCredentials(config) {
 
 const POLL_INTERVAL_MS = 1e3;
 const AUTH_TIMEOUT_MS = 12e4;
-async function authLogin(config) {
+async function authLogin(config, opts) {
   const seed = getRandomBytes(32);
   const keypair = tweetnacl.box.keyPair.fromSecretKey(seed);
   const publicKeyBase64 = encodeBase64(keypair.publicKey);
@@ -198,15 +206,25 @@ async function authLogin(config) {
     }
     throw err;
   }
-  const qrData = `happy:///account?${encodeBase64Url(keypair.publicKey)}`;
-  console.log("");
-  qrcode.generate(qrData, { small: true }, (code) => {
-    console.log(code);
-  });
-  console.log("## Authentication");
-  console.log("- Action: Scan this QR code with the Happy app");
-  console.log("- Path: Settings -> Account -> Link New Device");
-  console.log("");
+  if (opts?.web) {
+    const publicKeyBase64Url = encodeBase64Url(keypair.publicKey);
+    const webUrl = `${config.webappUrl}/terminal/connect#key=${publicKeyBase64Url}`;
+    console.log("");
+    console.log("## Authentication (Web)");
+    console.log(`- Open this URL in your browser: ${webUrl}`);
+    console.log("- Then sign in with your Happy account to complete linking.");
+    console.log("");
+  } else {
+    const qrData = `happy:///account?${encodeBase64Url(keypair.publicKey)}`;
+    console.log("");
+    qrcode.generate(qrData, { small: true }, (code) => {
+      console.log(code);
+    });
+    console.log("## Authentication");
+    console.log("- Action: Scan this QR code with the Happy app");
+    console.log("- Path: Settings -> Account -> Link New Device");
+    console.log("");
+  }
   const startTime = Date.now();
   while (Date.now() - startTime < AUTH_TIMEOUT_MS) {
     await sleep(POLL_INTERVAL_MS);
@@ -390,9 +408,7 @@ async function deleteSession(config, creds, sessionId) {
   try {
     await axios.delete(
       `${config.serverUrl}/v1/sessions/${encodeURIComponent(sessionId)}`,
-      {
-        headers: authHeaders(creds)
-      }
+      { headers: authHeaders(creds) }
     );
   } catch (err) {
     handleApiError(err, `deleting session ${sessionId}`);
@@ -418,9 +434,602 @@ async function getSessionMessages(config, creds, sessionId, encryption) {
     updatedAt: msg.updatedAt
   }));
 }
+async function fetchMessagesAfterSeq(config, creds, sessionId, encryption, afterSeq, limit = 100) {
+  let data;
+  try {
+    const resp = await axios.get(
+      `${config.serverUrl}/v3/sessions/${encodeURIComponent(sessionId)}/messages`,
+      {
+        params: { after_seq: afterSeq, limit },
+        headers: authHeaders(creds),
+        timeout: 6e4
+      }
+    );
+    data = resp.data;
+  } catch (err) {
+    handleApiError(err, `fetching v3 messages for session ${sessionId}`);
+  }
+  const messages = data.messages.map((msg) => {
+    const content = decryptField(msg.content.c, encryption);
+    if (content === null) return null;
+    return {
+      id: msg.id,
+      seq: msg.seq,
+      content,
+      localId: msg.localId ?? null,
+      createdAt: msg.createdAt,
+      updatedAt: msg.updatedAt
+    };
+  }).filter((m) => m !== null);
+  return { messages, hasMore: data.hasMore };
+}
+async function sendMessagesBatch(config, creds, sessionId, encryption, contents) {
+  const messages = contents.map((content) => ({
+    content: encodeBase64(
+      encrypt(encryption.key, encryption.variant, content)
+    )
+  }));
+  let data;
+  try {
+    const resp = await axios.post(
+      `${config.serverUrl}/v3/sessions/${encodeURIComponent(sessionId)}/messages`,
+      { messages },
+      { headers: authHeaders(creds), timeout: 6e4 }
+    );
+    data = resp.data;
+  } catch (err) {
+    handleApiError(err, `sending v3 messages to session ${sessionId}`);
+  }
+  return data;
+}
+async function getOrCreateMachine(config, creds, metadata) {
+  const sessionKey = getRandomBytes(32);
+  const encryptedKey = libsodiumEncryptForPublicKey(
+    sessionKey,
+    creds.contentKeyPair.publicKey
+  );
+  const withVersion = new Uint8Array(1 + encryptedKey.length);
+  withVersion[0] = 0;
+  withVersion.set(encryptedKey, 1);
+  const encryptedMetadata = encryptWithDataKey(metadata, sessionKey);
+  let data;
+  try {
+    const resp = await axios.post(
+      `${config.serverUrl}/v2/machines`,
+      {
+        metadata: encodeBase64(encryptedMetadata),
+        dataEncryptionKey: encodeBase64(withVersion)
+      },
+      { headers: authHeaders(creds) }
+    );
+    data = resp.data;
+  } catch (err) {
+    handleApiError(err, "registering machine");
+  }
+  const raw = data.machine;
+  let encKey;
+  let encVariant;
+  if (raw.dataEncryptionKey) {
+    const encrypted = decodeBase64(raw.dataEncryptionKey);
+    const bundle = encrypted.slice(1);
+    const key = decryptBoxBundle(bundle, creds.contentKeyPair.secretKey);
+    if (!key) throw new Error("Failed to decrypt machine encryption key");
+    encKey = key;
+    encVariant = "dataKey";
+  } else {
+    encKey = creds.secret;
+    encVariant = "legacy";
+  }
+  return {
+    id: raw.id,
+    encryptionKey: encKey,
+    encryptionVariant: encVariant,
+    metadata: decryptField(raw.metadata, { key: encKey, variant: encVariant }) ?? metadata,
+    metadataVersion: raw.metadataVersion,
+    daemonState: raw.daemonState ? decryptField(raw.daemonState, { key: encKey, variant: encVariant }) : null,
+    daemonStateVersion: raw.daemonStateVersion
+  };
+}
+async function listMachines(config, creds) {
+  let data;
+  try {
+    const resp = await axios.get(`${config.serverUrl}/v2/machines`, {
+      headers: authHeaders(creds)
+    });
+    data = resp.data;
+  } catch (err) {
+    handleApiError(err, "listing machines");
+  }
+  return data.machines;
+}
+
+function timestamp() {
+  return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", {
+    hour12: false,
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    fractionalSecondDigits: 3
+  });
+}
+function filenameTimestamp() {
+  return (/* @__PURE__ */ new Date()).toLocaleString("sv-SE", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit"
+  }).replace(/[: ]/g, "-").replace(/,/g, "");
+}
+function resolveLogPath() {
+  const config = loadConfig();
+  const logsDir = node_path.join(config.homeDir, "logs");
+  node_fs.mkdirSync(logsDir, { recursive: true });
+  return node_path.join(logsDir, `agent-${filenameTimestamp()}-pid-${process.pid}.log`);
+}
+class Logger {
+  logFilePath;
+  constructor() {
+    this.logFilePath = resolveLogPath();
+  }
+  debug(message, ...args) {
+    this.write("DEBUG", message, ...args);
+  }
+  warn(message, ...args) {
+    this.write("WARN", message, ...args);
+  }
+  error(message, ...args) {
+    this.write("ERROR", message, ...args);
+  }
+  write(level, message, ...args) {
+    const extra = args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ");
+    const line = `[${timestamp()}] [${level}] ${message}${extra ? " " + extra : ""}
+`;
+    try {
+      node_fs.appendFileSync(this.logFilePath, line);
+    } catch {
+    }
+  }
+}
+const logger = new Logger();
+
+async function withBackoff(fn, options) {
+  const maxRetries = options?.maxRetries ?? 3;
+  const baseDelay = options?.baseDelayMs ?? 200;
+  const label = options?.label ?? "operation";
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt < maxRetries) {
+        const delay = baseDelay * 2 ** attempt;
+        logger.debug(`[backoff] ${label} attempt ${attempt + 1} failed, retrying in ${delay}ms`);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+  throw lastError;
+}
+
+class RpcHandlerManager {
+  handlers = /* @__PURE__ */ new Map();
+  scopePrefix;
+  encryptionKey;
+  encryptionVariant;
+  logger;
+  socket = null;
+  reregisterInterval = null;
+  constructor(config) {
+    this.scopePrefix = config.scopePrefix;
+    this.encryptionKey = config.encryptionKey;
+    this.encryptionVariant = config.encryptionVariant;
+    this.logger = config.logger ?? ((msg, data) => logger.debug(msg, data));
+  }
+  /**
+   * Register an RPC handler for a specific method
+   */
+  registerHandler(method, handler) {
+    const prefixedMethod = this.getPrefixedMethod(method);
+    this.handlers.set(prefixedMethod, handler);
+    if (this.socket) {
+      this.emitRegisterWithRetry(this.socket, prefixedMethod);
+    }
+  }
+  /**
+   * Handle an incoming RPC request
+   */
+  async handleRequest(request) {
+    try {
+      const handler = this.handlers.get(request.method);
+      if (!handler) {
+        this.logger("[RPC] [ERROR] Method not found", {
+          method: request.method
+        });
+        const errorResponse = { error: "Method not found" };
+        return encodeBase64(
+          encrypt(this.encryptionKey, this.encryptionVariant, errorResponse)
+        );
+      }
+      const decryptedParams = decrypt(
+        this.encryptionKey,
+        this.encryptionVariant,
+        decodeBase64(request.params)
+      );
+      this.logger("[RPC] Calling handler", { method: request.method });
+      const result = await handler(decryptedParams);
+      this.logger("[RPC] Handler returned", {
+        method: request.method,
+        hasResult: result !== void 0
+      });
+      const encryptedResponse = encodeBase64(
+        encrypt(this.encryptionKey, this.encryptionVariant, result)
+      );
+      return encryptedResponse;
+    } catch (error) {
+      this.logger("[RPC] [ERROR] Error handling request", { error });
+      const errorResponse = {
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+      return encodeBase64(
+        encrypt(this.encryptionKey, this.encryptionVariant, errorResponse)
+      );
+    }
+  }
+  onSocketConnect(socket) {
+    this.socket = socket;
+    this.registerAllHandlers(socket);
+    this.startReregisterInterval();
+  }
+  onSocketDisconnect() {
+    this.socket = null;
+    this.stopReregisterInterval();
+  }
+  getHandlerCount() {
+    return this.handlers.size;
+  }
+  hasHandler(method) {
+    return this.handlers.has(this.getPrefixedMethod(method));
+  }
+  clearHandlers() {
+    this.handlers.clear();
+    this.logger("Cleared all RPC handlers");
+  }
+  // -----------------------------------------------------------------------
+  // Private
+  // -----------------------------------------------------------------------
+  /**
+   * Register a single method with ack + retry.
+   * Falls back to fire-and-forget emit after all retries exhausted.
+   */
+  emitRegisterWithRetry(socket, method, maxRetries = 3) {
+    const attempt = (remaining) => {
+      if (this.socket !== socket) return;
+      socket.timeout(5e3).emit(
+        "rpc-register",
+        { method },
+        (err, ackResponse) => {
+          if (this.socket !== socket) return;
+          if (err && remaining > 0) {
+            this.logger("[RPC] rpc-register ack timeout, retrying", {
+              method,
+              remaining
+            });
+            setTimeout(() => attempt(remaining - 1), 1e3);
+          } else if (err) {
+            this.logger(
+              "[RPC] [WARN] rpc-register failed after retries, falling back to emit",
+              { method }
+            );
+            socket.emit("rpc-register", { method });
+          } else if (!ackResponse?.ok) {
+            this.logger("[RPC] [WARN] rpc-register rejected by server", {
+              method,
+              error: ackResponse?.error
+            });
+          }
+        }
+      );
+    };
+    attempt(maxRetries);
+  }
+  registerAllHandlers(socket) {
+    for (const [prefixedMethod] of this.handlers) {
+      this.emitRegisterWithRetry(socket, prefixedMethod);
+    }
+  }
+  /**
+   * Periodic re-registration every 60s as a safety net.
+   */
+  startReregisterInterval() {
+    this.stopReregisterInterval();
+    this.reregisterInterval = setInterval(() => {
+      if (this.socket && this.handlers.size > 0) {
+        this.registerAllHandlers(this.socket);
+      }
+    }, 6e4);
+  }
+  stopReregisterInterval() {
+    if (this.reregisterInterval) {
+      clearInterval(this.reregisterInterval);
+      this.reregisterInterval = null;
+    }
+  }
+  getPrefixedMethod(method) {
+    return `${this.scopePrefix}:${method}`;
+  }
+}
+function createRpcHandlerManager(config) {
+  return new RpcHandlerManager(config);
+}
+
+const execAsync = util.promisify(child_process.exec);
+const UPLOAD_TEMP_DIR = path.join(os.tmpdir(), "happy", "uploads");
+const MAX_WRITE_SIZE = 10 * 1024 * 1024;
+function validatePath(targetPath, workingDirectory, additionalAllowedDirs) {
+  const resolvedTarget = path.resolve(workingDirectory, targetPath);
+  let realTarget;
+  try {
+    realTarget = fs.realpathSync(resolvedTarget);
+  } catch {
+    const parentDir = path.resolve(resolvedTarget, "..");
+    try {
+      realTarget = fs.realpathSync(parentDir) + "/" + resolvedTarget.split("/").pop();
+    } catch {
+      realTarget = resolvedTarget;
+    }
+  }
+  const allowedDirs = [
+    workingDirectory,
+    ...additionalAllowedDirs ?? []
+  ].map((d) => {
+    const resolved = path.resolve(d);
+    try {
+      return fs.realpathSync(resolved);
+    } catch {
+      return resolved;
+    }
+  });
+  for (const dir of allowedDirs) {
+    if (realTarget.startsWith(dir + "/") || realTarget === dir) {
+      return { valid: true };
+    }
+  }
+  return {
+    valid: false,
+    error: `Access denied: Path '${targetPath}' is outside the allowed directories`
+  };
+}
+const BLOCKED_BASH_PATTERNS = [
+  { pattern: /\bprintenv\b/i, reason: "printenv is blocked for security" },
+  {
+    pattern: /\benv\b(?:\s|$|;|\|)/i,
+    reason: "env command is blocked for security"
+  },
+  {
+    pattern: /\bset\b\s*(?:$|;|\|)/i,
+    reason: "set (list env) is blocked for security"
+  },
+  {
+    pattern: /\bexport\s+-p\b/i,
+    reason: "export -p is blocked for security"
+  },
+  {
+    pattern: /\bcompgen\s+-e\b/i,
+    reason: "compgen -e is blocked for security"
+  },
+  {
+    pattern: /\bdeclare\s+-x\b/i,
+    reason: "declare -x is blocked for security"
+  },
+  {
+    pattern: /\/proc\/[^/]*\/environ/i,
+    reason: "reading /proc/environ is blocked for security"
+  },
+  {
+    pattern: /\$\{?\s*(ANTHROPIC_AUTH_TOKEN|ANTHROPIC_API_KEY|ANTHROPIC_BASE_URL|OPENAI_API_KEY|OPENAI_BASE_URL|DATABASE_URL|REDIS_URL|JWT_SECRET|ENCRYPTION_KEY|AWS_SECRET_ACCESS_KEY|GOOGLE_API_KEY|GEMINI_API_KEY|TOGETHER_API_KEY|GITHUB_CLIENT_SECRET|CLAUDE_CODE_OAUTH_TOKEN)\b/i,
+    reason: "accessing sensitive environment variables is blocked"
+  },
+  {
+    pattern: /\.(env|env\.local|env\.prod|env\.production|env\.dev)\b/i,
+    reason: "reading .env files is blocked for security"
+  },
+  {
+    pattern: /\.aws\/credentials/i,
+    reason: "reading AWS credentials is blocked for security"
+  },
+  {
+    pattern: /\.netrc/i,
+    reason: "reading .netrc is blocked for security"
+  }
+];
+function checkBlockedBashCommand(command) {
+  for (const { pattern, reason } of BLOCKED_BASH_PATTERNS) {
+    if (pattern.test(command)) {
+      return reason;
+    }
+  }
+  return null;
+}
+function registerAgentHandlers(rpcHandlerManager, workingDirectory, sessionId) {
+  const safeSessionId = sessionId.replace(/[^a-zA-Z0-9-]/g, "");
+  rpcHandlerManager.registerHandler(
+    "bash",
+    async (data) => {
+      logger.debug("Shell command request:", data.command);
+      const blockedReason = checkBlockedBashCommand(data.command);
+      if (blockedReason) {
+        logger.warn(
+          `[SECURITY] Blocked bash RPC command: ${blockedReason}`,
+          { command: data.command }
+        );
+        return { success: false, error: blockedReason };
+      }
+      if (data.cwd && data.cwd !== "/") {
+        const validation = validatePath(data.cwd, workingDirectory);
+        if (!validation.valid) {
+          return { success: false, error: validation.error };
+        }
+      }
+      try {
+        const options = {
+          cwd: data.cwd === "/" ? void 0 : data.cwd,
+          timeout: data.timeout ?? 3e4
+        };
+        const { stdout, stderr } = await execAsync(data.command, options);
+        return {
+          success: true,
+          stdout: stdout?.toString() ?? "",
+          stderr: stderr?.toString() ?? "",
+          exitCode: 0
+        };
+      } catch (error) {
+        const execError = error;
+        if (execError.code === "ETIMEDOUT" || execError.killed) {
+          return {
+            success: false,
+            stdout: execError.stdout ?? "",
+            stderr: execError.stderr ?? "",
+            exitCode: typeof execError.code === "number" ? execError.code : -1,
+            error: "Command timed out"
+          };
+        }
+        return {
+          success: false,
+          stdout: execError.stdout?.toString() ?? "",
+          stderr: execError.stderr?.toString() ?? execError.message ?? "Command failed",
+          exitCode: typeof execError.code === "number" ? execError.code : 1,
+          error: execError.message ?? "Command failed"
+        };
+      }
+    }
+  );
+  rpcHandlerManager.registerHandler(
+    "readFile",
+    async (data) => {
+      logger.debug("Read file request:", data.path);
+      const sessionUploadDir = path.join(UPLOAD_TEMP_DIR, safeSessionId);
+      const validation = validatePath(data.path, workingDirectory, [
+        sessionUploadDir
+      ]);
+      if (!validation.valid) {
+        return { success: false, error: validation.error };
+      }
+      try {
+        const resolvedPath = path.resolve(workingDirectory, data.path);
+        const buffer = await promises.readFile(resolvedPath);
+        return { success: true, content: buffer.toString("base64") };
+      } catch (error) {
+        logger.debug("Failed to read file:", error);
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : "Failed to read file"
+        };
+      }
+    }
+  );
+  rpcHandlerManager.registerHandler(
+    "writeFile",
+    async (data) => {
+      logger.debug("Write file request:", data.path);
+      if (data.content && data.content.length > MAX_WRITE_SIZE) {
+        return {
+          success: false,
+          error: `File content exceeds maximum allowed size (${MAX_WRITE_SIZE} bytes)`
+        };
+      }
+      const sessionUploadDir = path.join(UPLOAD_TEMP_DIR, safeSessionId);
+      const validation = validatePath(data.path, workingDirectory, [
+        sessionUploadDir
+      ]);
+      if (!validation.valid) {
+        return { success: false, error: validation.error };
+      }
+      try {
+        const resolvedPath = path.resolve(workingDirectory, data.path);
+        if (data.expectedHash !== null && data.expectedHash !== void 0) {
+          try {
+            const existingBuffer = await promises.readFile(resolvedPath);
+            const existingHash = crypto.createHash("sha256").update(existingBuffer).digest("hex");
+            if (existingHash !== data.expectedHash) {
+              return {
+                success: false,
+                error: `File hash mismatch. Expected: ${data.expectedHash}, Actual: ${existingHash}`
+              };
+            }
+          } catch {
+            return {
+              success: false,
+              error: "File does not exist but expectedHash was provided"
+            };
+          }
+        }
+        const dir = path.resolve(resolvedPath, "..");
+        await promises.mkdir(dir, { recursive: true });
+        const buffer = Buffer.from(data.content, "base64");
+        await promises.writeFile(resolvedPath, buffer);
+        const hash = crypto.createHash("sha256").update(buffer).digest("hex");
+        return { success: true, hash };
+      } catch (error) {
+        logger.debug("Failed to write file:", error);
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : "Failed to write file"
+        };
+      }
+    }
+  );
+  rpcHandlerManager.registerHandler("listDirectory", async (data) => {
+    logger.debug("List directory request:", data.path);
+    const validation = validatePath(data.path, workingDirectory);
+    if (!validation.valid) {
+      return { success: false, error: validation.error };
+    }
+    try {
+      const entries = await promises.readdir(data.path, { withFileTypes: true });
+      const directoryEntries = await Promise.all(
+        entries.map(async (entry) => {
+          const fullPath = path.join(data.path, entry.name);
+          let type = "other";
+          let size;
+          let modified;
+          if (entry.isDirectory()) type = "directory";
+          else if (entry.isFile()) type = "file";
+          try {
+            const stats = await promises.stat(fullPath);
+            size = stats.size;
+            modified = stats.mtime.getTime();
+          } catch {
+          }
+          return { name: entry.name, type, size, modified };
+        })
+      );
+      directoryEntries.sort((a, b) => {
+        if (a.type === "directory" && b.type !== "directory") return -1;
+        if (a.type !== "directory" && b.type === "directory") return 1;
+        return a.name.localeCompare(b.name);
+      });
+      return { success: true, entries: directoryEntries };
+    } catch (error) {
+      logger.debug("Failed to list directory:", error);
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Failed to list directory"
+      };
+    }
+  });
+  rpcHandlerManager.registerHandler("getUploadDir", async () => {
+    const uploadDir = path.join(UPLOAD_TEMP_DIR, safeSessionId);
+    await promises.mkdir(uploadDir, { recursive: true });
+    return { success: true, path: uploadDir };
+  });
+}
 
 class SessionClient extends node_events.EventEmitter {
   sessionId;
+  rpcHandlerManager;
   encryptionKey;
   encryptionVariant;
   socket;
@@ -429,6 +1038,7 @@ class SessionClient extends node_events.EventEmitter {
   agentState = null;
   agentStateVersion = 0;
   aliveInterval = null;
+  thinking = false;
   constructor(opts) {
     super();
     this.sessionId = opts.sessionId;
@@ -439,6 +1049,16 @@ class SessionClient extends node_events.EventEmitter {
     }
     this.on("error", () => {
     });
+    this.rpcHandlerManager = createRpcHandlerManager({
+      scopePrefix: `session:${opts.sessionId}`,
+      encryptionKey: opts.encryptionKey,
+      encryptionVariant: opts.encryptionVariant,
+      logger: (msg, data) => logger.debug(msg, data)
+    });
+    if (opts.enableRpc !== false) {
+      const workDir = opts.workingDirectory ?? process.cwd();
+      registerAgentHandlers(this.rpcHandlerManager, workDir, opts.sessionId);
+    }
     this.socket = socket_ioClient.io(opts.serverUrl, {
       auth: {
         token: opts.token,
@@ -453,84 +1073,17 @@ class SessionClient extends node_events.EventEmitter {
       transports: ["websocket"],
       autoConnect: false
     });
-    this.socket.on("connect", () => {
-      this.emit("connected");
-      this.aliveInterval = setInterval(() => {
-        this.socket.emit("session-alive", {
-          sid: this.sessionId,
-          time: Date.now()
-        });
-      }, 2e4);
-    });
-    this.socket.on("disconnect", (reason) => {
-      if (this.aliveInterval !== null) {
-        clearInterval(this.aliveInterval);
-        this.aliveInterval = null;
-      }
-      this.emit("disconnected", reason);
-    });
-    this.socket.on("connect_error", (error) => {
-      this.emit("connect_error", error);
-    });
-    this.socket.on("update", (data) => {
-      try {
-        const body = data?.body;
-        if (!body) return;
-        if (body.t === "new-message" && body.message?.content?.t === "encrypted") {
-          const msg = body.message;
-          const decrypted = decrypt(
-            this.encryptionKey,
-            this.encryptionVariant,
-            decodeBase64(msg.content.c)
-          );
-          if (decrypted === null) return;
-          this.emit("message", {
-            id: msg.id,
-            seq: msg.seq,
-            content: decrypted,
-            localId: msg.localId,
-            createdAt: msg.createdAt,
-            updatedAt: msg.updatedAt
-          });
-        } else if (body.t === "update-session") {
-          if (body.metadata && body.metadata.version > this.metadataVersion) {
-            this.metadata = decrypt(
-              this.encryptionKey,
-              this.encryptionVariant,
-              decodeBase64(body.metadata.value)
-            );
-            this.metadataVersion = body.metadata.version;
-          }
-          if (body.agentState && body.agentState.version > this.agentStateVersion) {
-            this.agentState = body.agentState.value ? decrypt(
-              this.encryptionKey,
-              this.encryptionVariant,
-              decodeBase64(body.agentState.value)
-            ) : null;
-            this.agentStateVersion = body.agentState.version;
-          }
-          this.emit("state-change", {
-            metadata: this.metadata,
-            agentState: this.agentState
-          });
-        }
-      } catch (err) {
-        this.emit("error", err);
-      }
-    });
+    this.setupSocketListeners();
     this.socket.connect();
   }
+  // -----------------------------------------------------------------------
+  // Public API (backward compatible)
+  // -----------------------------------------------------------------------
   sendMessage(text, meta) {
     const content = {
       role: "user",
-      content: {
-        type: "text",
-        text
-      },
-      meta: {
-        sentFrom: "happy-agent",
-        ...meta
-      }
+      content: { type: "text", text },
+      meta: { sentFrom: "happy-agent", ...meta }
     };
     const encrypted = encodeBase64(
       encrypt(this.encryptionKey, this.encryptionVariant, content)
@@ -546,6 +1099,9 @@ class SessionClient extends node_events.EventEmitter {
   getAgentState() {
     return this.agentState;
   }
+  setThinking(thinking) {
+    this.thinking = thinking;
+  }
   waitForConnect(timeoutMs = 1e4) {
     return new Promise((resolve, reject) => {
       if (this.socket.connected) {
@@ -575,13 +1131,9 @@ class SessionClient extends node_events.EventEmitter {
     return new Promise((resolve, reject) => {
       const checkIdle = () => {
         const meta = this.metadata;
-        if (meta?.lifecycleState === "archived") {
-          return "archived";
-        }
+        if (meta?.lifecycleState === "archived") return "archived";
         const state = this.agentState;
-        if (!state) {
-          return false;
-        }
+        if (!state) return false;
         const controlledByUser = state.controlledByUser === true;
         const requests = state.requests;
         const hasRequests = requests != null && typeof requests === "object" && !Array.isArray(requests) && Object.keys(requests).length > 0;
@@ -638,8 +1190,352 @@ class SessionClient extends node_events.EventEmitter {
       clearInterval(this.aliveInterval);
       this.aliveInterval = null;
     }
+    this.rpcHandlerManager.onSocketDisconnect();
     this.socket.close();
   }
+  // -----------------------------------------------------------------------
+  // New: OCC metadata/state updates
+  // -----------------------------------------------------------------------
+  async updateMetadata(newMetadata) {
+    const encrypted = encodeBase64(
+      encrypt(this.encryptionKey, this.encryptionVariant, newMetadata)
+    );
+    await withBackoff(
+      () => new Promise((resolve, reject) => {
+        this.socket.emit(
+          "update-metadata",
+          {
+            sid: this.sessionId,
+            expectedVersion: this.metadataVersion,
+            metadata: encrypted
+          },
+          (answer) => {
+            if (answer.result === "success" && answer.version !== void 0) {
+              this.metadataVersion = answer.version;
+              this.metadata = newMetadata;
+              resolve();
+            } else if (answer.result === "version-mismatch" && answer.version !== void 0) {
+              this.metadataVersion = answer.version;
+              if (answer.metadata) {
+                this.metadata = decrypt(
+                  this.encryptionKey,
+                  this.encryptionVariant,
+                  decodeBase64(answer.metadata)
+                );
+              }
+              reject(new Error("version-mismatch"));
+            } else {
+              reject(new Error(`update-metadata failed: ${answer.result}`));
+            }
+          }
+        );
+      }),
+      { maxRetries: 3, label: "updateMetadata" }
+    );
+  }
+  async updateAgentState(newState) {
+    const encrypted = newState !== null ? encodeBase64(encrypt(this.encryptionKey, this.encryptionVariant, newState)) : null;
+    await withBackoff(
+      () => new Promise((resolve, reject) => {
+        this.socket.emit(
+          "update-state",
+          {
+            sid: this.sessionId,
+            expectedVersion: this.agentStateVersion,
+            agentState: encrypted
+          },
+          (answer) => {
+            if (answer.result === "success" && answer.version !== void 0) {
+              this.agentStateVersion = answer.version;
+              this.agentState = newState;
+              resolve();
+            } else if (answer.result === "version-mismatch" && answer.version !== void 0) {
+              this.agentStateVersion = answer.version;
+              if (answer.agentState) {
+                this.agentState = decrypt(
+                  this.encryptionKey,
+                  this.encryptionVariant,
+                  decodeBase64(answer.agentState)
+                );
+              }
+              reject(new Error("version-mismatch"));
+            } else {
+              reject(new Error(`update-state failed: ${answer.result}`));
+            }
+          }
+        );
+      }),
+      { maxRetries: 3, label: "updateAgentState" }
+    );
+  }
+  // -----------------------------------------------------------------------
+  // Private: socket listeners
+  // -----------------------------------------------------------------------
+  setupSocketListeners() {
+    this.socket.on("connect", () => {
+      this.emit("connected");
+      this.rpcHandlerManager.onSocketConnect(this.socket);
+      this.aliveInterval = setInterval(() => {
+        this.socket.emit("session-alive", {
+          sid: this.sessionId,
+          time: Date.now(),
+          thinking: this.thinking
+        });
+      }, 2e4);
+    });
+    this.socket.on("disconnect", (reason) => {
+      if (this.aliveInterval !== null) {
+        clearInterval(this.aliveInterval);
+        this.aliveInterval = null;
+      }
+      this.rpcHandlerManager.onSocketDisconnect();
+      this.emit("disconnected", reason);
+    });
+    this.socket.on("connect_error", (error) => {
+      this.emit("connect_error", error);
+    });
+    this.socket.on("rpc-request", async (data, callback) => {
+      try {
+        const response = await this.rpcHandlerManager.handleRequest(data);
+        callback(response);
+      } catch (err) {
+        logger.error("[RPC] Unhandled error in rpc-request handler", err);
+      }
+    });
+    this.socket.on("update", (data) => {
+      try {
+        const body = data?.body;
+        if (!body) return;
+        if (body.t === "new-message" && body.message?.content?.t === "encrypted") {
+          const msg = body.message;
+          const decrypted = decrypt(
+            this.encryptionKey,
+            this.encryptionVariant,
+            decodeBase64(msg.content.c)
+          );
+          if (decrypted === null) return;
+          this.emit("message", {
+            id: msg.id,
+            seq: msg.seq,
+            content: decrypted,
+            localId: msg.localId,
+            createdAt: msg.createdAt,
+            updatedAt: msg.updatedAt
+          });
+        } else if (body.t === "update-session") {
+          if (body.metadata && body.metadata.version > this.metadataVersion) {
+            this.metadata = decrypt(
+              this.encryptionKey,
+              this.encryptionVariant,
+              decodeBase64(body.metadata.value)
+            );
+            this.metadataVersion = body.metadata.version;
+          }
+          if (body.agentState && body.agentState.version > this.agentStateVersion) {
+            this.agentState = body.agentState.value ? decrypt(
+              this.encryptionKey,
+              this.encryptionVariant,
+              decodeBase64(body.agentState.value)
+            ) : null;
+            this.agentStateVersion = body.agentState.version;
+          }
+          this.emit("state-change", {
+            metadata: this.metadata,
+            agentState: this.agentState
+          });
+        }
+      } catch (err) {
+        this.emit("error", err);
+      }
+    });
+  }
+}
+
+class MachineClient {
+  machine;
+  rpcHandlerManager;
+  socket;
+  keepAliveInterval = null;
+  token;
+  serverUrl;
+  onEphemeral;
+  constructor(opts) {
+    this.token = opts.token;
+    this.machine = opts.machine;
+    this.serverUrl = opts.serverUrl;
+    this.onEphemeral = opts.onEphemeral;
+    this.rpcHandlerManager = new RpcHandlerManager({
+      scopePrefix: opts.machine.id,
+      encryptionKey: opts.machine.encryptionKey,
+      encryptionVariant: opts.machine.encryptionVariant,
+      logger: (msg, data) => logger.debug(msg, data)
+    });
+    const workDir = opts.workingDirectory ?? process.cwd();
+    registerAgentHandlers(this.rpcHandlerManager, workDir, opts.machine.id);
+  }
+  // -----------------------------------------------------------------------
+  // Connection
+  // -----------------------------------------------------------------------
+  connect() {
+    logger.debug(`[MACHINE] Connecting to ${this.serverUrl}`);
+    this.socket = socket_ioClient.io(this.serverUrl, {
+      transports: ["websocket"],
+      auth: {
+        token: this.token,
+        clientType: "machine-scoped",
+        machineId: this.machine.id
+      },
+      path: "/v1/updates",
+      reconnection: true,
+      reconnectionDelay: 1e3,
+      reconnectionDelayMax: 5e3
+    });
+    this.socket.on("connect", () => {
+      logger.debug("[MACHINE] Connected to server");
+      this.rpcHandlerManager.onSocketConnect(this.socket);
+      this.startKeepAlive();
+    });
+    this.socket.on("disconnect", () => {
+      logger.debug("[MACHINE] Disconnected from server");
+      this.rpcHandlerManager.onSocketDisconnect();
+      this.stopKeepAlive();
+    });
+    this.socket.on(
+      "rpc-request",
+      async (data, callback) => {
+        logger.debug("[MACHINE] Received RPC request:", data.method);
+        callback(await this.rpcHandlerManager.handleRequest(data));
+      }
+    );
+    this.socket.on("update", (data) => {
+      const body = data?.body;
+      if (body?.t === "update-machine" && body.machineId === this.machine.id) {
+        if (body.metadata && body.metadata.version > this.machine.metadataVersion) {
+          this.machine.metadata = decrypt(
+            this.machine.encryptionKey,
+            this.machine.encryptionVariant,
+            decodeBase64(body.metadata.value)
+          );
+          this.machine.metadataVersion = body.metadata.version;
+        }
+        if (body.daemonState && body.daemonState.version > this.machine.daemonStateVersion) {
+          this.machine.daemonState = decrypt(
+            this.machine.encryptionKey,
+            this.machine.encryptionVariant,
+            decodeBase64(body.daemonState.value)
+          );
+          this.machine.daemonStateVersion = body.daemonState.version;
+        }
+      }
+    });
+    if (this.onEphemeral) {
+      this.socket.on("ephemeral", (data) => {
+        logger.debug("[MACHINE] Received ephemeral event:", data.type);
+        this.onEphemeral?.(data);
+      });
+    }
+    this.socket.on("connect_error", (error) => {
+      logger.debug(`[MACHINE] Connection error: ${error.message}`);
+    });
+  }
+  // -----------------------------------------------------------------------
+  // OCC updates
+  // -----------------------------------------------------------------------
+  async updateMachineMetadata(handler) {
+    await withBackoff(async () => {
+      const updated = handler(this.machine.metadata);
+      const answer = await new Promise((resolve) => {
+        this.socket.emit(
+          "machine-update-metadata",
+          {
+            machineId: this.machine.id,
+            metadata: encodeBase64(
+              encrypt(this.machine.encryptionKey, this.machine.encryptionVariant, updated)
+            ),
+            expectedVersion: this.machine.metadataVersion
+          },
+          resolve
+        );
+      });
+      if (answer.result === "success") {
+        this.machine.metadata = decrypt(
+          this.machine.encryptionKey,
+          this.machine.encryptionVariant,
+          decodeBase64(answer.metadata)
+        );
+        this.machine.metadataVersion = answer.version;
+      } else if (answer.result === "version-mismatch") {
+        this.machine.metadataVersion = answer.version;
+        this.machine.metadata = decrypt(
+          this.machine.encryptionKey,
+          this.machine.encryptionVariant,
+          decodeBase64(answer.metadata)
+        );
+        throw new Error("Metadata version mismatch");
+      }
+    }, { maxRetries: 3, label: "updateMachineMetadata" });
+  }
+  async updateDaemonState(handler) {
+    await withBackoff(async () => {
+      const updated = handler(this.machine.daemonState);
+      const answer = await new Promise((resolve) => {
+        this.socket.emit(
+          "machine-update-state",
+          {
+            machineId: this.machine.id,
+            daemonState: encodeBase64(
+              encrypt(this.machine.encryptionKey, this.machine.encryptionVariant, updated)
+            ),
+            expectedVersion: this.machine.daemonStateVersion
+          },
+          resolve
+        );
+      });
+      if (answer.result === "success") {
+        this.machine.daemonState = decrypt(
+          this.machine.encryptionKey,
+          this.machine.encryptionVariant,
+          decodeBase64(answer.daemonState)
+        );
+        this.machine.daemonStateVersion = answer.version;
+      } else if (answer.result === "version-mismatch") {
+        this.machine.daemonStateVersion = answer.version;
+        this.machine.daemonState = decrypt(
+          this.machine.encryptionKey,
+          this.machine.encryptionVariant,
+          decodeBase64(answer.daemonState)
+        );
+        throw new Error("Daemon state version mismatch");
+      }
+    }, { maxRetries: 3, label: "updateDaemonState" });
+  }
+  // -----------------------------------------------------------------------
+  // Lifecycle
+  // -----------------------------------------------------------------------
+  shutdown() {
+    logger.debug("[MACHINE] Shutting down");
+    this.stopKeepAlive();
+    this.rpcHandlerManager.onSocketDisconnect();
+    this.socket?.close();
+  }
+  // -----------------------------------------------------------------------
+  // Private
+  // -----------------------------------------------------------------------
+  startKeepAlive() {
+    this.stopKeepAlive();
+    this.keepAliveInterval = setInterval(() => {
+      this.socket.emit("machine-alive", {
+        machineId: this.machine.id,
+        time: Date.now()
+      });
+    }, 2e4);
+  }
+  stopKeepAlive() {
+    if (this.keepAliveInterval) {
+      clearInterval(this.keepAliveInterval);
+      this.keepAliveInterval = null;
+    }
+  }
 }
 
 function formatTime(ts) {
@@ -819,9 +1715,9 @@ function createClient(session, creds, config) {
 const program = new commander.Command();
 program.name("happy-agent").description("CLI client for controlling Happy Coder agents remotely").version(version);
 program.command("auth").description("Manage authentication").addCommand(
-  new commander.Command("login").description("Authenticate via QR code").action(async () => {
+  new commander.Command("login").description("Authenticate via QR code or web URL").option("--web", "Use web URL instead of QR code (for SSH/headless environments)").action(async (opts) => {
     const config = loadConfig();
-    await authLogin(config);
+    await authLogin(config, { web: opts.web });
   })
 ).addCommand(
   new commander.Command("logout").description("Clear stored credentials").action(async () => {
@@ -1031,7 +1927,74 @@ program.command("wait").description("Wait for agent to become idle").argument("<
     client.close();
   }
 });
+program.command("machine").description("Manage machine identity").addCommand(
+  new commander.Command("register").description("Register this machine with the server").option("--json", "Output as JSON").action(async (opts) => {
+    const config = loadConfig();
+    const creds = requireCredentials(config);
+    const metadata = {
+      host: node_os.hostname(),
+      platform: process.platform,
+      happyCliVersion: version,
+      homeDir: config.homeDir,
+      happyHomeDir: config.homeDir,
+      happyLibDir: config.homeDir
+    };
+    const machine = await getOrCreateMachine(config, creds, metadata);
+    if (opts.json) {
+      console.log(formatJson({ id: machine.id, metadata: machine.metadata }));
+    } else {
+      console.log(
+        [
+          "## Machine Registered",
+          "",
+          `- Machine ID: \`${machine.id}\``,
+          `- Host: ${machine.metadata.host}`,
+          `- Platform: ${machine.metadata.platform}`
+        ].join("\n")
+      );
+    }
+  })
+).addCommand(
+  new commander.Command("list").description("List all registered machines").option("--json", "Output as JSON").action(async (opts) => {
+    const config = loadConfig();
+    const creds = requireCredentials(config);
+    const machines = await listMachines(config, creds);
+    if (opts.json) {
+      console.log(formatJson(machines));
+    } else {
+      if (machines.length === 0) {
+        console.log("No machines registered.");
+      } else {
+        console.log(`## Machines (${machines.length})`);
+        for (const m of machines) {
+          console.log(`- \`${m.id}\``);
+        }
+      }
+    }
+  })
+);
 program.parseAsync(process.argv).catch((err) => {
   console.error(err instanceof Error ? err.message : String(err));
   process.exitCode = 1;
 });
+
+exports.MachineClient = MachineClient;
+exports.RpcHandlerManager = RpcHandlerManager;
+exports.SessionClient = SessionClient;
+exports.authLogin = authLogin;
+exports.authLogout = authLogout;
+exports.authStatus = authStatus;
+exports.createRpcHandlerManager = createRpcHandlerManager;
+exports.createSession = createSession;
+exports.deleteSession = deleteSession;
+exports.fetchMessagesAfterSeq = fetchMessagesAfterSeq;
+exports.getOrCreateMachine = getOrCreateMachine;
+exports.getSessionMessages = getSessionMessages;
+exports.listActiveSessions = listActiveSessions;
+exports.listMachines = listMachines;
+exports.listSessions = listSessions;
+exports.loadConfig = loadConfig;
+exports.readCredentials = readCredentials;
+exports.requireCredentials = requireCredentials;
+exports.resolveSessionEncryption = resolveSessionEncryption;
+exports.sendMessagesBatch = sendMessagesBatch;