@kmmao/happy-agent 0.3.10 → 0.4.0

package/dist/index.cjs

@@ -18,7 +18,7 @@ var path = require('path');
 var fs = require('fs');
 var os = require('os');
 
-var version = "0.3.10";
+var version = "0.4.0";
 
 function loadConfig() {
   const serverUrl = (process.env.HAPPY_SERVER_URL ?? "https://happyserve.xycloud.info").replace(/\/+$/, "");
@@ -789,6 +789,7 @@ function createRpcHandlerManager(config) {
 }
 
 const execAsync = util.promisify(child_process.exec);
+const execFileAsync$1 = util.promisify(child_process.execFile);
 const UPLOAD_TEMP_DIR = path.join(os.tmpdir(), "happy", "uploads");
 const MAX_WRITE_SIZE = 10 * 1024 * 1024;
 function validatePath(targetPath, workingDirectory, additionalAllowedDirs) {
@@ -1048,6 +1049,367 @@ function registerAgentHandlers(rpcHandlerManager, workingDirectory, sessionId) {
     await promises.mkdir(uploadDir, { recursive: true });
     return { success: true, path: uploadDir };
   });
+  rpcHandlerManager.registerHandler("getDirectoryTree", async (data) => {
+    logger.debug("Get directory tree request:", data.path, "maxDepth:", data.maxDepth);
+    const validation = validatePath(data.path, workingDirectory);
+    if (!validation.valid) {
+      return { success: false, error: validation.error };
+    }
+    async function buildTree(dirPath, name, currentDepth) {
+      try {
+        const stats = await promises.stat(dirPath);
+        const node = {
+          name,
+          path: dirPath,
+          type: stats.isDirectory() ? "directory" : "file",
+          size: stats.size,
+          modified: stats.mtime.getTime()
+        };
+        if (stats.isDirectory() && currentDepth < data.maxDepth) {
+          const entries = await promises.readdir(dirPath, { withFileTypes: true });
+          const children = [];
+          await Promise.all(
+            entries.map(async (entry) => {
+              if (entry.isSymbolicLink()) return;
+              const childPath = path.join(dirPath, entry.name);
+              const childNode = await buildTree(childPath, entry.name, currentDepth + 1);
+              if (childNode) children.push(childNode);
+            })
+          );
+          children.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);
+          });
+          node.children = children;
+        }
+        return node;
+      } catch (error) {
+        logger.debug(`Failed to process ${dirPath}:`, error instanceof Error ? error.message : String(error));
+        return null;
+      }
+    }
+    try {
+      if (data.maxDepth < 0) {
+        return { success: false, error: "maxDepth must be non-negative" };
+      }
+      const baseName = data.path === "/" ? "/" : data.path.split("/").pop() || data.path;
+      const tree = await buildTree(data.path, baseName, 0);
+      if (!tree) {
+        return { success: false, error: "Failed to access the specified path" };
+      }
+      return { success: true, tree };
+    } catch (error) {
+      logger.debug("Failed to get directory tree:", error);
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Failed to get directory tree"
+      };
+    }
+  });
+  rpcHandlerManager.registerHandler(
+    "ripgrep",
+    async (data) => {
+      const cwd = data.cwd || workingDirectory;
+      if (data.cwd) {
+        const validation = validatePath(data.cwd, workingDirectory);
+        if (!validation.valid) {
+          return { success: false, error: validation.error };
+        }
+      }
+      try {
+        const { stdout, stderr } = await execFileAsync$1("rg", data.args, {
+          cwd,
+          timeout: 3e4,
+          maxBuffer: 10 * 1024 * 1024
+        });
+        return { success: true, stdout: stdout?.toString() ?? "", stderr: stderr?.toString() ?? "", exitCode: 0 };
+      } catch (error) {
+        const e = error;
+        if (e.code === "ENOENT") {
+          return { success: false, error: "ripgrep (rg) is not installed on this machine" };
+        }
+        if (e.code === "1" || e.status === 1) {
+          return { success: true, stdout: e.stdout?.toString() ?? "", stderr: e.stderr?.toString() ?? "", exitCode: 1 };
+        }
+        return {
+          success: false,
+          stdout: e.stdout?.toString() ?? "",
+          stderr: e.stderr?.toString() ?? "",
+          exitCode: typeof e.code === "number" ? e.code : 1,
+          error: e.message ?? "ripgrep failed"
+        };
+      }
+    }
+  );
+  rpcHandlerManager.registerHandler(
+    "difftastic",
+    async (data) => {
+      const cwd = data.cwd || workingDirectory;
+      if (data.cwd) {
+        const validation = validatePath(data.cwd, workingDirectory);
+        if (!validation.valid) {
+          return { success: false, error: validation.error };
+        }
+      }
+      try {
+        const { stdout, stderr } = await execFileAsync$1("difft", data.args, {
+          cwd,
+          timeout: 3e4,
+          maxBuffer: 10 * 1024 * 1024
+        });
+        return { success: true, stdout: stdout?.toString() ?? "", stderr: stderr?.toString() ?? "", exitCode: 0 };
+      } catch (error) {
+        const e = error;
+        if (e.code === "ENOENT") {
+          return { success: false, error: "difftastic (difft) is not installed on this machine" };
+        }
+        return {
+          success: false,
+          stdout: e.stdout?.toString() ?? "",
+          stderr: e.stderr?.toString() ?? "",
+          exitCode: typeof e.code === "number" ? e.code : 1,
+          error: e.message ?? "difftastic failed"
+        };
+      }
+    }
+  );
+  rpcHandlerManager.registerHandler("listRemoteGitRepos", async (data) => {
+    const page = data.page ?? 1;
+    const perPage = data.perPage ?? 30;
+    const query = data.query?.trim() || "";
+    logger.debug("listRemoteGitRepos request:", { provider: data.provider, host: data.host, page, perPage, query });
+    if (!data.apiToken) return { success: false, error: "API token is required" };
+    if (!data.host?.trim()) return { success: false, error: "Host is required" };
+    try {
+      const baseUrl = buildGitApiBase(data.provider, data.host);
+      const headers = buildGitApiHeaders(data.apiToken);
+      let repos;
+      let hasMore;
+      if (data.provider === "github") {
+        const listUrl = `${baseUrl}/user/repos?per_page=${perPage}&page=${page}&sort=updated&affiliation=owner,collaborator,organization_member`;
+        const response = await fetch(listUrl, { headers });
+        if (!response.ok) {
+          const errorText = await response.text().catch(() => "");
+          throw new Error(`HTTP ${response.status}: ${errorText}`);
+        }
+        const items = await response.json();
+        repos = normalizeRemoteRepoEntries(items);
+        hasMore = items.length >= perPage;
+      } else {
+        const searchParams = new URLSearchParams({ sort: "updated", order: "desc", limit: String(perPage), page: String(page) });
+        if (query) searchParams.set("q", query);
+        const searchUrl = `${baseUrl}/repos/search?${searchParams.toString()}`;
+        const response = await fetch(searchUrl, { headers });
+        if (!response.ok) {
+          const errorText = await response.text().catch(() => "");
+          throw new Error(`HTTP ${response.status}: ${errorText}`);
+        }
+        const body = await response.json();
+        const items = Array.isArray(body) ? body : body.data || [];
+        repos = normalizeRemoteRepoEntries(items);
+        hasMore = items.length >= perPage;
+      }
+      return { success: true, repos, hasMore };
+    } catch (error) {
+      logger.debug("listRemoteGitRepos failed:", error);
+      return { success: false, error: error instanceof Error ? error.message : "Failed to load remote repositories" };
+    }
+  });
+  rpcHandlerManager.registerHandler(
+    "cloneGitRepo",
+    async (data) => {
+      logger.debug("cloneGitRepo request:", { repoUrl: data.repoUrl, targetDirectory: data.targetDirectory });
+      if (!data.repoUrl?.trim()) return { success: false, error: "Repository URL is required" };
+      if (!data.targetDirectory?.trim()) return { success: false, error: "Target directory is required" };
+      if (!data.targetDirectory.startsWith("/")) return { success: false, error: "Target directory must be an absolute path" };
+      const coords = parseCloneCoordinates(data.repoUrl);
+      if (!coords) return { success: false, error: "Invalid repository URL" };
+      const repoPath = path.join(path.resolve(data.targetDirectory), coords.repo);
+      try {
+        await promises.mkdir(path.resolve(data.targetDirectory), { recursive: true });
+        try {
+          const existing = await promises.stat(repoPath);
+          if (existing.isDirectory()) {
+            return { success: false, error: `Destination already exists: ${repoPath}` };
+          }
+        } catch {
+        }
+        const cloneUrl = resolveCloneUrl(data.repoUrl, data.host);
+        const options = {
+          cwd: path.resolve(data.targetDirectory),
+          timeout: 3e5,
+          maxBuffer: 4 * 1024 * 1024,
+          env: buildCloneAuthEnv(data.provider, data.apiToken)
+        };
+        const { stdout, stderr } = await execFileAsync$1("git", ["clone", cloneUrl, repoPath], options);
+        return { success: true, repoPath, stdout: stdout?.toString() ?? "", stderr: stderr?.toString() ?? "" };
+      } catch (error) {
+        const e = error;
+        logger.debug("cloneGitRepo failed:", { message: e.message, stderr: e.stderr });
+        return { success: false, repoPath, stdout: e.stdout || "", stderr: e.stderr || "", error: e.message || "Failed to clone repository" };
+      }
+    }
+  );
+  rpcHandlerManager.registerHandler("createRemoteWebhook", async (data) => {
+    logger.debug("createRemoteWebhook request:", { provider: data.provider, repoUrl: data.repoUrl });
+    try {
+      const parsed = parseRepoOwnerFromUrl(data.repoUrl);
+      if (!parsed) return { success: false, error: "Invalid repo URL" };
+      const { origin, owner, repo } = parsed;
+      const isGitHubCom = origin === "https://github.com" || origin === "http://github.com";
+      const baseUrl = data.provider === "github" && isGitHubCom ? "https://api.github.com" : data.provider === "github" ? `${origin}/api/v3` : `${origin}/api/v1`;
+      const headers = {
+        Authorization: `token ${data.apiToken}`,
+        "Content-Type": "application/json",
+        Accept: "application/json"
+      };
+      const hooksEndpoint = `${baseUrl}/repos/${owner}/${repo}/hooks`;
+      const giteaEvents = [
+        "issues",
+        "issue_assign",
+        "issue_label",
+        "issue_milestone",
+        "issue_comment",
+        "pull_request",
+        "pull_request_assign",
+        "pull_request_label",
+        "pull_request_milestone",
+        "pull_request_comment",
+        "pull_request_review",
+        "pull_request_sync"
+      ];
+      const events = data.provider === "gitea" ? giteaEvents : data.events;
+      const listRes = await fetch(hooksEndpoint, { headers });
+      if (listRes.ok) {
+        const hooks = await listRes.json();
+        const existing = hooks.find((h) => h.config.url === data.webhookUrl);
+        if (existing) {
+          const patchRes = await fetch(`${hooksEndpoint}/${existing.id}`, {
+            method: "PATCH",
+            headers,
+            body: JSON.stringify({ config: { url: data.webhookUrl, content_type: "json", secret: data.webhookSecret }, events, active: true })
+          });
+          if (!patchRes.ok) {
+            const errText = await patchRes.text().catch(() => "");
+            return { success: false, error: `PATCH ${patchRes.status}: ${errText}` };
+          }
+          return { success: true, created: false, webhookId: existing.id };
+        }
+      }
+      const createBody = {
+        name: "web",
+        config: { url: data.webhookUrl, content_type: "json", secret: data.webhookSecret },
+        events,
+        active: true
+      };
+      if (data.provider === "gitea") createBody.type = "gitea";
+      const createRes = await fetch(hooksEndpoint, { method: "POST", headers, body: JSON.stringify(createBody) });
+      if (createRes.ok || createRes.status === 201) {
+        const body = await createRes.json().catch(() => ({}));
+        return { success: true, created: true, webhookId: body.id };
+      }
+      const errBody = await createRes.text().catch(() => "");
+      return { success: false, error: `HTTP ${createRes.status}: ${errBody}` };
+    } catch (error) {
+      logger.debug("createRemoteWebhook failed:", error);
+      return { success: false, error: error instanceof Error ? error.message : "Failed to create webhook" };
+    }
+  });
+  rpcHandlerManager.registerHandler("deleteRemoteWebhook", async (data) => {
+    logger.debug("deleteRemoteWebhook request:", { provider: data.provider, repoUrl: data.repoUrl });
+    try {
+      const parsed = parseRepoOwnerFromUrl(data.repoUrl);
+      if (!parsed) return { success: false, error: "Invalid repo URL" };
+      const { origin, owner, repo } = parsed;
+      const isGitHubCom = origin === "https://github.com" || origin === "http://github.com";
+      const baseUrl = data.provider === "github" && isGitHubCom ? "https://api.github.com" : data.provider === "github" ? `${origin}/api/v3` : `${origin}/api/v1`;
+      const headers = { Authorization: `token ${data.apiToken}`, Accept: "application/json" };
+      const hooksEndpoint = `${baseUrl}/repos/${owner}/${repo}/hooks`;
+      const listRes = await fetch(hooksEndpoint, { headers });
+      if (!listRes.ok) return { success: false, error: `List hooks failed: HTTP ${listRes.status}` };
+      const hooks = await listRes.json();
+      const existing = hooks.find((h) => h.config.url === data.webhookUrl);
+      if (!existing) return { success: true, deleted: false };
+      const deleteRes = await fetch(`${hooksEndpoint}/${existing.id}`, { method: "DELETE", headers });
+      if (deleteRes.ok || deleteRes.status === 204) return { success: true, deleted: true };
+      const errBody = await deleteRes.text().catch(() => "");
+      return { success: false, error: `DELETE ${deleteRes.status}: ${errBody}` };
+    } catch (error) {
+      logger.debug("deleteRemoteWebhook failed:", error);
+      return { success: false, error: error instanceof Error ? error.message : "Failed to delete webhook" };
+    }
+  });
+}
+function parseHostEntry(host) {
+  const match = host.match(/^(https?):\/\/(.+)/);
+  if (match) return { bare: match[2].replace(/\/$/, ""), protocol: match[1] };
+  return { bare: host.replace(/\/$/, ""), protocol: null };
+}
+function buildGitApiBase(provider, host) {
+  const { bare, protocol } = parseHostEntry(host);
+  const normalizedProtocol = protocol ?? "https";
+  const origin = `${normalizedProtocol}://${bare}`;
+  const isGitHubCom = bare === "github.com" || bare === "www.github.com";
+  if (provider === "github") {
+    return isGitHubCom ? "https://api.github.com" : `${origin}/api/v3`;
+  }
+  return `${origin}/api/v1`;
+}
+function buildGitApiHeaders(apiToken) {
+  return {
+    Authorization: `token ${apiToken}`,
+    Accept: "application/json",
+    "Content-Type": "application/json"
+  };
+}
+function normalizeRemoteRepoEntries(pageRepos) {
+  return pageRepos.filter((repo) => !!repo.name).map((repo) => {
+    const owner = repo.owner?.login || repo.owner?.username || "";
+    const fullName = repo.full_name || (owner ? `${owner}/${repo.name}` : repo.name || "");
+    const htmlUrl = repo.html_url || "";
+    const cloneUrl = repo.clone_url || (htmlUrl ? `${htmlUrl}.git` : "");
+    return { name: repo.name || fullName, fullName, cloneUrl, htmlUrl, private: !!repo.private, updatedAt: repo.updated_at ? Date.parse(repo.updated_at) : null };
+  }).filter((repo) => !!repo.cloneUrl);
+}
+function parseCloneCoordinates(repoUrl) {
+  const trimmed = repoUrl.trim();
+  const sshMatch = trimmed.match(/^git@([^:]+):([^/]+)\/([^/.]+?)(?:\.git)?$/);
+  if (sshMatch) return { host: sshMatch[1], owner: sshMatch[2], repo: sshMatch[3] };
+  const sshUrlMatch = trimmed.match(/^ssh:\/\/[^@]+@([^/]+)\/([^/]+)\/([^/.]+?)(?:\.git)?$/);
+  if (sshUrlMatch) return { host: sshUrlMatch[1], owner: sshUrlMatch[2], repo: sshUrlMatch[3] };
+  const httpsMatch = trimmed.match(/^https?:\/\/([^/]+)\/([^/]+)\/([^/.]+?)(?:\.git)?$/);
+  if (httpsMatch) return { host: httpsMatch[1], owner: httpsMatch[2], repo: httpsMatch[3] };
+  return null;
+}
+function resolveCloneUrl(repoUrl, configuredHost) {
+  if (/^https?:\/\//.test(repoUrl)) return repoUrl;
+  const coords = parseCloneCoordinates(repoUrl);
+  if (!coords) return repoUrl;
+  const hostEntry = configuredHost ? parseHostEntry(configuredHost) : null;
+  const protocol = hostEntry?.protocol ?? "https";
+  const bareHost = hostEntry?.bare ?? coords.host;
+  return `${protocol}://${bareHost}/${coords.owner}/${coords.repo}.git`;
+}
+function buildCloneAuthEnv(provider, apiToken) {
+  if (!apiToken) return void 0;
+  const username = provider === "github" ? "x-access-token" : "oauth2";
+  const authValue = Buffer.from(`${username}:${apiToken}`).toString("base64");
+  return {
+    ...process.env,
+    GIT_CONFIG_COUNT: "1",
+    GIT_CONFIG_KEY_0: "http.extraHeader",
+    GIT_CONFIG_VALUE_0: `Authorization: Basic ${authValue}`
+  };
+}
+function parseRepoOwnerFromUrl(repoUrl) {
+  try {
+    const url = new URL(repoUrl);
+    const parts = url.pathname.replace(/^\//, "").replace(/\.git$/, "").split("/");
+    if (parts.length >= 2) return { origin: url.origin, owner: parts[0], repo: parts[1] };
+  } catch {
+  }
+  return null;
 }
 
 class SessionClient extends node_events.EventEmitter {
@@ -1475,6 +1837,340 @@ function isNotFound(err) {
   return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
 }
 
+const pidToSession = /* @__PURE__ */ new Map();
+function trackSession(session) {
+  pidToSession.set(session.pid, session);
+}
+function untrackSession(pid) {
+  const session = pidToSession.get(pid);
+  pidToSession.delete(pid);
+  return session;
+}
+function getAllTrackedSessions() {
+  return [...pidToSession.values()];
+}
+
+const execFileAsync = util.promisify(child_process.execFile);
+const SERVER_INTERNAL_SECRETS = /* @__PURE__ */ new Set([
+  "DATABASE_URL",
+  "REDIS_URL",
+  "JWT_SECRET",
+  "ENCRYPTION_KEY",
+  "GITHUB_CLIENT_SECRET",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SESSION_TOKEN",
+  "STRIPE_SECRET_KEY",
+  "SENDGRID_API_KEY",
+  "S3_ACCESS_KEY",
+  "S3_SECRET_KEY"
+]);
+function buildSpawnEnv(extra) {
+  const base = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!SERVER_INTERNAL_SECRETS.has(key) && key !== "CLAUDECODE") {
+      base[key] = value;
+    }
+  }
+  if (extra) {
+    for (const [key, value] of Object.entries(extra)) {
+      if (value !== void 0) {
+        base[key] = value;
+      }
+    }
+  }
+  return base;
+}
+let happyBinaryPath;
+async function findHappyBinary() {
+  if (happyBinaryPath !== void 0) return happyBinaryPath;
+  try {
+    const { stdout } = await execFileAsync("which", ["happy"]);
+    happyBinaryPath = stdout.trim() || null;
+  } catch {
+    happyBinaryPath = null;
+  }
+  return happyBinaryPath;
+}
+async function spawnSession(options) {
+  const {
+    directory,
+    agent = "claude",
+    approvedNewDirectoryCreation = false,
+    happySessionId,
+    automationContext,
+    environmentVariables
+  } = options;
+  const happyPath = await findHappyBinary();
+  if (!happyPath) {
+    return {
+      type: "error",
+      errorMessage: "happy CLI not found. Install with: npm install -g @kmmao/happy-coder"
+    };
+  }
+  try {
+    const dirStat = await promises.stat(directory);
+    if (!dirStat.isDirectory()) {
+      return { type: "error", errorMessage: `Path exists but is not a directory: ${directory}` };
+    }
+  } catch {
+    if (!approvedNewDirectoryCreation) {
+      return { type: "requestToApproveDirectoryCreation", directory };
+    }
+    try {
+      await promises.mkdir(directory, { recursive: true });
+      logger.debug(`[SPAWN] Created directory: ${directory}`);
+    } catch (mkdirError) {
+      return {
+        type: "error",
+        errorMessage: `Failed to create directory: ${mkdirError instanceof Error ? mkdirError.message : String(mkdirError)}`
+      };
+    }
+  }
+  const args = [
+    agent,
+    "--happy-starting-mode",
+    "remote",
+    "--started-by",
+    "daemon"
+  ];
+  if (happySessionId) {
+    args.push("--happy-session-id", happySessionId);
+  }
+  const spawnEnv = buildSpawnEnv(environmentVariables);
+  logger.debug(`[SPAWN] ${happyPath} ${args.join(" ")} in ${directory}`);
+  let happyProcess;
+  try {
+    happyProcess = child_process.spawn(happyPath, args, {
+      cwd: directory,
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: spawnEnv
+    });
+  } catch (spawnError) {
+    return {
+      type: "error",
+      errorMessage: `Failed to spawn: ${spawnError instanceof Error ? spawnError.message : String(spawnError)}`
+    };
+  }
+  const pid = happyProcess.pid;
+  if (!pid) {
+    return { type: "error", errorMessage: "Spawned process has no PID" };
+  }
+  const tracked = {
+    pid,
+    directory,
+    startedAt: Date.now(),
+    childProcess: happyProcess,
+    lastActivityAt: Date.now(),
+    automationContext
+  };
+  trackSession(tracked);
+  happyProcess.stdout?.on("data", () => {
+    tracked.lastActivityAt = Date.now();
+  });
+  happyProcess.stderr?.on("data", () => {
+    tracked.lastActivityAt = Date.now();
+  });
+  happyProcess.on("exit", (code, signal) => {
+    logger.debug(`[SPAWN] Process ${pid} exited: code=${code} signal=${signal}`);
+    const session = untrackSession(pid);
+    if (session) {
+      session.terminationReason = signal ? `signal:${signal}` : code !== 0 ? `exit:${code}` : "completed";
+    }
+  });
+  happyProcess.unref();
+  logger.debug(`[SPAWN] Spawned PID ${pid} in ${directory}`);
+  return { type: "success", pid, directory };
+}
+function stopSession(pid) {
+  const tracked = untrackSession(pid);
+  if (!tracked) {
+    try {
+      process.kill(pid, "SIGTERM");
+      return { stopped: true };
+    } catch {
+      return { stopped: false, error: `No tracked session with PID ${pid}` };
+    }
+  }
+  try {
+    if (tracked.childProcess && !tracked.childProcess.killed) {
+      tracked.childProcess.kill("SIGTERM");
+    } else {
+      process.kill(pid, "SIGTERM");
+    }
+    tracked.terminationReason = "user_stop";
+    logger.debug(`[SPAWN] Stopped session PID ${pid}`);
+    return { stopped: true };
+  } catch (error) {
+    return {
+      stopped: false,
+      error: error instanceof Error ? error.message : "Failed to stop session"
+    };
+  }
+}
+
+const PROMPT_DIR = path.join(os.tmpdir(), "happy", "agent-prompts");
+async function writePromptFile(prefix, content) {
+  await promises.mkdir(PROMPT_DIR, { recursive: true });
+  const filename = `${prefix}-${Date.now()}.md`;
+  const filepath = path.join(PROMPT_DIR, filename);
+  await promises.writeFile(filepath, content, "utf-8");
+  return filepath;
+}
+function buildWebhookPrompt(data) {
+  return [
+    `# Issue #${data.issueNumber}: ${data.issueTitle}`,
+    "",
+    `Author: ${data.issueAuthor}`,
+    `Labels: ${data.issueLabels.join(", ") || "none"}`,
+    `URL: ${data.issueUrl}`,
+    "",
+    data.issueBody
+  ].join("\n");
+}
+function buildSupervisorPrompt(data) {
+  const parts = [
+    `# Supervisor Run: ${data.runId}`,
+    "",
+    `Trigger: ${data.trigger}`,
+    `Project: ${data.projectId}`
+  ];
+  if (data.mode) parts.push(`Mode: ${data.mode}`);
+  if (data.dimensions?.length) parts.push(`Dimensions: ${data.dimensions.join(", ")}`);
+  if (data.changedFiles?.length) {
+    parts.push("", "## Changed Files", ...data.changedFiles.map((f) => `- ${f}`));
+  }
+  if (data.customRules) parts.push("", "## Custom Rules", data.customRules);
+  return parts.join("\n");
+}
+async function handleWebhookTrigger(data, client, serverUrl, authToken) {
+  logger.debug(`[TRIGGER] Webhook: issue #${data.issueNumber} in ${data.repoPath}`);
+  client.emitWebhookStatus({
+    webhookEventId: data.webhookEventId,
+    status: "dispatched"
+  });
+  try {
+    const promptFile = await writePromptFile("webhook", buildWebhookPrompt(data));
+    const result = await spawnSession({
+      directory: data.repoPath,
+      approvedNewDirectoryCreation: false,
+      automationContext: {
+        kind: "webhook",
+        trigger: `issue#${data.issueNumber}`
+      },
+      environmentVariables: {
+        HAPPY_INITIAL_PROMPT_FILE: promptFile,
+        HAPPY_WEBHOOK_EVENT_ID: data.webhookEventId,
+        HAPPY_WEBHOOK_ISSUE_URL: data.issueUrl,
+        HAPPY_SERVER_URL: serverUrl,
+        HAPPY_AUTH_TOKEN: authToken
+      }
+    });
+    if (result.type === "success") {
+      logger.debug(`[TRIGGER] Webhook session spawned: PID ${result.pid}`);
+    } else {
+      logger.debug(`[TRIGGER] Webhook spawn failed: ${result.type === "error" ? result.errorMessage : "needs approval"}`);
+      client.emitWebhookStatus({
+        webhookEventId: data.webhookEventId,
+        status: "failed",
+        errorMessage: result.type === "error" ? result.errorMessage : "Directory creation not approved"
+      });
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    logger.debug(`[TRIGGER] Webhook error: ${msg}`);
+    client.emitWebhookStatus({
+      webhookEventId: data.webhookEventId,
+      status: "failed",
+      errorMessage: msg
+    });
+  }
+}
+async function handleSupervisorTrigger(data, client, serverUrl, authToken) {
+  logger.debug(`[TRIGGER] Supervisor: run ${data.runId} in ${data.repoPath}`);
+  client.emitSupervisorRunStatus({
+    runId: data.runId,
+    projectId: data.projectId,
+    status: "running"
+  });
+  try {
+    const promptFile = await writePromptFile("supervisor", buildSupervisorPrompt(data));
+    const result = await spawnSession({
+      directory: data.repoPath,
+      approvedNewDirectoryCreation: false,
+      automationContext: {
+        kind: "supervisor",
+        trigger: data.trigger,
+        projectId: data.projectId,
+        runId: data.runId
+      },
+      environmentVariables: {
+        HAPPY_INITIAL_PROMPT_FILE: promptFile,
+        HAPPY_SUPERVISOR_RUN_ID: data.runId,
+        HAPPY_SUPERVISOR_PROJECT_ID: data.projectId,
+        HAPPY_SUPERVISOR_SERVER_URL: serverUrl,
+        HAPPY_SUPERVISOR_AUTH_TOKEN: authToken
+      }
+    });
+    if (result.type !== "success") {
+      client.emitSupervisorRunStatus({
+        runId: data.runId,
+        projectId: data.projectId,
+        status: "failed",
+        errorMessage: result.type === "error" ? result.errorMessage : "Directory creation not approved"
+      });
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    logger.debug(`[TRIGGER] Supervisor error: ${msg}`);
+    client.emitSupervisorRunStatus({
+      runId: data.runId,
+      projectId: data.projectId,
+      status: "failed",
+      errorMessage: msg
+    });
+  }
+}
+async function handleTaskTrigger(data, serverUrl, _authToken) {
+  logger.debug(`[TRIGGER] Task: ${data.taskId} in ${data.directory}`);
+  try {
+    const promptFile = await writePromptFile("task", data.prompt);
+    const skillEnv = {};
+    if (data.skillContents?.length) {
+      skillEnv.HAPPY_TASK_SKILL_COUNT = String(data.skillContents.length);
+      for (let i = 0; i < data.skillContents.length; i++) {
+        skillEnv[`HAPPY_TASK_SKILL_${i}_NAME`] = data.skillContents[i].name;
+        skillEnv[`HAPPY_TASK_SKILL_${i}_CONTENT`] = data.skillContents[i].content;
+      }
+    }
+    const result = await spawnSession({
+      directory: data.directory,
+      approvedNewDirectoryCreation: true,
+      // Tasks always auto-approve directory
+      automationContext: {
+        kind: "task",
+        trigger: "task-dispatch",
+        projectId: data.projectId
+      },
+      environmentVariables: {
+        HAPPY_INITIAL_PROMPT_FILE: promptFile,
+        HAPPY_TASK_ID: data.taskId,
+        HAPPY_TASK_PRIORITY: data.priority,
+        HAPPY_TASK_SERVER_URL: serverUrl,
+        HAPPY_TASK_RESULT_TOKEN: data.resultToken ?? "",
+        HAPPY_TASK_REPORT_URL: `${serverUrl}/v1/tasks/${data.taskId}/result`,
+        ...skillEnv
+      }
+    });
+    if (result.type !== "success") {
+      logger.debug(`[TRIGGER] Task spawn failed: ${result.type === "error" ? result.errorMessage : "needs approval"}`);
+    }
+  } catch (error) {
+    logger.debug(`[TRIGGER] Task error: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 const TAILSCALE_REFRESH_MS = 5 * 60 * 1e3;
 class MachineClient {
   machine;
@@ -1486,11 +2182,17 @@ class MachineClient {
   tunnelManager = null;
   token;
   serverUrl;
+  agentVersion;
+  startTime = Date.now();
   onEphemeral;
+  automationEnabled = false;
+  automationServerUrl = "";
+  automationAuthToken = "";
   constructor(opts) {
     this.token = opts.token;
     this.machine = opts.machine;
     this.serverUrl = opts.serverUrl;
+    this.agentVersion = opts.agentVersion ?? "unknown";
     this.onEphemeral = opts.onEphemeral;
     this.rpcHandlerManager = new RpcHandlerManager({
       scopePrefix: opts.machine.id,
@@ -1500,6 +2202,32 @@ class MachineClient {
     });
     const workDir = opts.workingDirectory ?? process.cwd();
     registerAgentHandlers(this.rpcHandlerManager, workDir, opts.machine.id);
+    this.registerMachineHandlers();
+  }
+  // -----------------------------------------------------------------------
+  // Machine-scoped RPC handlers
+  // -----------------------------------------------------------------------
+  registerMachineHandlers() {
+    this.rpcHandlerManager.registerHandler(
+      "spawn-happy-session",
+      async (data) => {
+        logger.debug("[MACHINE] spawn-happy-session request:", data.directory);
+        return spawnSession(data);
+      }
+    );
+    this.rpcHandlerManager.registerHandler("stop-session", async (data) => {
+      logger.debug("[MACHINE] stop-session request:", data.pid);
+      return stopSession(data.pid);
+    });
+    this.rpcHandlerManager.registerHandler("list-tracked-sessions", async () => {
+      const sessions = getAllTrackedSessions().map((s) => ({
+        pid: s.pid,
+        directory: s.directory,
+        startedAt: s.startedAt,
+        happySessionId: s.happySessionId
+      }));
+      return { sessions };
+    });
   }
   // -----------------------------------------------------------------------
   // Connection
@@ -1526,6 +2254,8 @@ class MachineClient {
         status: "running",
         pid: process.pid,
         startedAt: Date.now(),
+        startTime: this.startTime,
+        startedWithCliVersion: this.agentVersion,
         tailscale: this.lastTailscaleInfo ?? state?.tailscale
       }));
       this.startKeepAlive();
@@ -1565,12 +2295,12 @@ class MachineClient {
         }
       }
     });
-    if (this.onEphemeral) {
-      this.socket.on("ephemeral", (data) => {
-        logger.debug("[MACHINE] Received ephemeral event:", data.type);
-        this.onEphemeral?.(data);
-      });
-    }
+    this.socket.on("ephemeral", (data) => {
+      const event = data;
+      logger.debug("[MACHINE] Received ephemeral event:", event.type);
+      this.onEphemeral?.(event);
+      this.handleAutomationEvent(event);
+    });
     this.socket.on("connect_error", (error) => {
       logger.debug(`[MACHINE] Connection error: ${error.message}`);
     });
@@ -1647,6 +2377,75 @@ class MachineClient {
     }, { maxRetries: 3, label: "updateDaemonState" });
   }
   // -----------------------------------------------------------------------
+  // Socket event emitters
+  // -----------------------------------------------------------------------
+  /** Emit a session lifecycle event. */
+  emitSessionEvent(sessionId, eventType, summary, detail) {
+    this.socket?.emit("session-event", { sessionId, eventType, summary, detail });
+  }
+  /** Report webhook processing status. */
+  emitWebhookStatus(data) {
+    this.socket?.emit("webhook-status", data);
+  }
+  /** Report supervisor run status. */
+  emitSupervisorRunStatus(data) {
+    this.socket?.emit("supervisor-run-status", data);
+  }
+  /** Submit a knowledge entry from a session. */
+  emitSubmitKnowledge(sid, entry) {
+    this.socket?.emit("submit-knowledge", { sid, entry });
+  }
+  /** Fetch knowledge for a session. */
+  emitFetchKnowledge(sid, mode, contextHints, callback) {
+    this.socket?.emit("fetch-knowledge", { sid, mode, contextHints }, callback);
+  }
+  /** Stream task log chunk. */
+  emitTaskLog(sid, taskId, outputFile, chunk, offset) {
+    this.socket?.emit("task-log", { sid, taskId, outputFile, chunk, offset });
+  }
+  // -----------------------------------------------------------------------
+  // Automation triggers
+  // -----------------------------------------------------------------------
+  /**
+   * Enable automation handling — agent will process webhook, supervisor,
+   * and task triggers from the server by spawning Happy CLI sessions.
+   */
+  enableAutomation(serverUrl, authToken) {
+    this.automationEnabled = true;
+    this.automationServerUrl = serverUrl;
+    this.automationAuthToken = authToken;
+    logger.debug("[MACHINE] Automation enabled");
+  }
+  /** Internal dispatch for ephemeral events that need automation handling. */
+  handleAutomationEvent(event) {
+    if (!this.automationEnabled) return;
+    switch (event.type) {
+      case "webhook-trigger":
+        void handleWebhookTrigger(
+          event,
+          this,
+          this.automationServerUrl,
+          this.automationAuthToken
+        );
+        break;
+      case "supervisor-trigger":
+        void handleSupervisorTrigger(
+          event,
+          this,
+          this.automationServerUrl,
+          this.automationAuthToken
+        );
+        break;
+      case "task-trigger":
+        void handleTaskTrigger(
+          event,
+          this.automationServerUrl,
+          this.automationAuthToken
+        );
+        break;
+    }
+  }
+  // -----------------------------------------------------------------------
   // Lifecycle
   // -----------------------------------------------------------------------
   /** Seed initial Tailscale info detected before connect. */
@@ -1721,6 +2520,131 @@ function tailscaleChanged(prev, next) {
   return prev.status !== next.status || prev.ipv4 !== next.ipv4 || prev.ipv6 !== next.ipv6 || prev.hostname !== next.hostname || JSON.stringify(prev.serves) !== JSON.stringify(next.serves);
 }
 
+function pidFilePath(homeDir) {
+  return node_path.join(homeDir, "agent-daemon.pid");
+}
+function writePidFile(homeDir, pid) {
+  node_fs.mkdirSync(homeDir, { recursive: true });
+  node_fs.writeFileSync(pidFilePath(homeDir), String(pid), "utf-8");
+}
+function readPidFile(homeDir) {
+  try {
+    const raw = node_fs.readFileSync(pidFilePath(homeDir), "utf-8").trim();
+    const pid = parseInt(raw, 10);
+    return isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+function removePidFile(homeDir) {
+  try {
+    node_fs.unlinkSync(pidFilePath(homeDir));
+  } catch {
+  }
+}
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function startDaemon(options) {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const existingPid = readPidFile(config.homeDir);
+  if (existingPid && isProcessRunning(existingPid)) {
+    console.log(`Daemon already running (PID ${existingPid})`);
+    process.exitCode = 1;
+    return;
+  }
+  if (existingPid) {
+    removePidFile(config.homeDir);
+  }
+  const workDir = options.directory ?? process.cwd();
+  console.log(`Starting agent daemon in ${workDir}...`);
+  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);
+  console.log(`Machine: ${machine.id} (${machine.metadata.host})`);
+  const tailscaleInfo = await detectTailscale();
+  const serves = tailscaleInfo.status === "connected" ? await detectTailscaleServe() : [];
+  const fullTailscale = { ...tailscaleInfo, serves };
+  if (tailscaleInfo.status === "connected") {
+    console.log(`Tailscale: ${tailscaleInfo.hostname} (${tailscaleInfo.ipv4})`);
+  }
+  const client = new MachineClient({
+    token: creds.token,
+    machine,
+    serverUrl: config.serverUrl,
+    agentVersion: version,
+    workingDirectory: workDir
+  });
+  client.setTailscaleInfo(fullTailscale);
+  client.enableAutomation(config.serverUrl, creds.token);
+  client.connect();
+  writePidFile(config.homeDir, process.pid);
+  console.log(`Daemon started (PID ${process.pid})`);
+  let shuttingDown = false;
+  const shutdown = (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    logger.debug(`[DAEMON] Received ${signal}, shutting down...`);
+    console.log(`
+Received ${signal}, shutting down...`);
+    client.shutdown();
+    removePidFile(config.homeDir);
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  await new Promise(() => {
+  });
+}
+function stopDaemon() {
+  const config = loadConfig();
+  const pid = readPidFile(config.homeDir);
+  if (!pid) {
+    console.log("No daemon PID file found.");
+    return;
+  }
+  if (!isProcessRunning(pid)) {
+    console.log(`Daemon PID ${pid} is not running (stale PID file). Cleaning up.`);
+    removePidFile(config.homeDir);
+    return;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+    console.log(`Sent SIGTERM to daemon (PID ${pid})`);
+    removePidFile(config.homeDir);
+  } catch (error) {
+    console.error(`Failed to stop daemon: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  }
+}
+function daemonStatus() {
+  const config = loadConfig();
+  const pid = readPidFile(config.homeDir);
+  if (!pid) {
+    console.log("Daemon is not running (no PID file).");
+    return;
+  }
+  if (isProcessRunning(pid)) {
+    console.log(`Daemon is running (PID ${pid})`);
+    console.log(`PID file: ${pidFilePath(config.homeDir)}`);
+  } else {
+    console.log(`Daemon PID ${pid} is not running (stale PID file).`);
+    console.log(`Run \`happy-agent daemon stop\` to clean up.`);
+  }
+}
+
 function formatTime(ts) {
   if (!ts) return "-";
   const date = new Date(ts);
@@ -2156,6 +3080,19 @@ program.command("machine").description("Manage machine identity").addCommand(
     }
   })
 );
+program.command("daemon").description("Run as a persistent background daemon").addCommand(
+  new commander.Command("start").description("Start the agent daemon (connects to server, handles triggers)").option("--directory <dir>", "Working directory for spawned sessions").option("--foreground", "Run in foreground (do not detach)").action(async (opts) => {
+    await startDaemon(opts);
+  })
+).addCommand(
+  new commander.Command("stop").description("Stop the running daemon").action(() => {
+    stopDaemon();
+  })
+).addCommand(
+  new commander.Command("status").description("Check daemon status").action(() => {
+    daemonStatus();
+  })
+);
 program.parseAsync(process.argv).catch((err) => {
   console.error(err instanceof Error ? err.message : String(err));
   process.exitCode = 1;
@@ -2169,6 +3106,7 @@ exports.authLogout = authLogout;
 exports.authStatus = authStatus;
 exports.createRpcHandlerManager = createRpcHandlerManager;
 exports.createSession = createSession;
+exports.daemonStatus = daemonStatus;
 exports.deleteSession = deleteSession;
 exports.fetchMessagesAfterSeq = fetchMessagesAfterSeq;
 exports.getOrCreateMachine = getOrCreateMachine;
@@ -2181,3 +3119,5 @@ exports.readCredentials = readCredentials;
 exports.requireCredentials = requireCredentials;
 exports.resolveSessionEncryption = resolveSessionEncryption;
 exports.sendMessagesBatch = sendMessagesBatch;
+exports.startDaemon = startDaemon;
+exports.stopDaemon = stopDaemon;