@agentmeshhq/agent 0.1.12 → 0.1.14

package/src/__tests__/watchdog.test.ts

@@ -0,0 +1,368 @@
+import { execSync, spawnSync } from "node:child_process";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import * as tmux from "../core/tmux.js";
+import {
+  checkAgentProgress,
+  cleanupOrphanContainers,
+  detectPermissionPrompt,
+  findOrphanContainers,
+  getLastActivityTime,
+  isProcessRunning,
+  sendNudge,
+  type WatchdogResult,
+} from "../core/watchdog.js";
+
+// Mock child_process
+vi.mock("node:child_process", () => ({
+  execSync: vi.fn(),
+  spawnSync: vi.fn(),
+}));
+
+// Mock tmux module
+vi.mock("../core/tmux.js", () => ({
+  captureSessionOutput: vi.fn(),
+}));
+
+describe("Watchdog Module", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  describe("detectPermissionPrompt", () => {
+    it("should return null when no permission prompt detected", () => {
+      vi.mocked(tmux.captureSessionOutput).mockReturnValue(
+        "Normal output without any prompts\nJust some code being written",
+      );
+
+      const result = detectPermissionPrompt("test-agent");
+      expect(result).toBeNull();
+    });
+
+    it("should detect 'Permission required' prompt", () => {
+      vi.mocked(tmux.captureSessionOutput).mockReturnValue(
+        "Some output\nPermission required\nAllow once | Allow always | Reject",
+      );
+
+      const result = detectPermissionPrompt("test-agent");
+      expect(result).toBe("Permission prompt detected");
+    });
+
+    it("should detect external directory access prompt", () => {
+      vi.mocked(tmux.captureSessionOutput).mockReturnValue(
+        "Access external directory /tmp/some-path\nAllow once | Allow always | Reject",
+      );
+
+      const result = detectPermissionPrompt("test-agent");
+      expect(result).toBe("External directory: /tmp/some-path");
+    });
+
+    it("should detect triangle permission prompt", () => {
+      vi.mocked(tmux.captureSessionOutput).mockReturnValue(
+        "Some output\n△ Permission required\nWaiting for approval",
+      );
+
+      const result = detectPermissionPrompt("test-agent");
+      expect(result).toBe("Permission prompt detected");
+    });
+
+    it("should return null when capture fails", () => {
+      vi.mocked(tmux.captureSessionOutput).mockReturnValue(null);
+
+      const result = detectPermissionPrompt("test-agent");
+      expect(result).toBeNull();
+    });
+
+    it("should return null when capture throws", () => {
+      vi.mocked(tmux.captureSessionOutput).mockImplementation(() => {
+        throw new Error("Session not found");
+      });
+
+      const result = detectPermissionPrompt("test-agent");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("getLastActivityTime", () => {
+    it("should parse timestamp from local log file", () => {
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 0,
+        stdout: "INFO  2026-02-26T00:14:42 +0ms service=opencode message=test",
+        stderr: "",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = getLastActivityTime("test-agent");
+      expect(result).toBeInstanceOf(Date);
+      expect(result?.toISOString()).toContain("2026-02-26");
+    });
+
+    it("should parse timestamp from container log file", () => {
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 0,
+        stdout: "INFO  2026-02-26T01:30:00 +0ms service=opencode",
+        stderr: "",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = getLastActivityTime("test-agent", "container-123");
+      expect(result).toBeInstanceOf(Date);
+    });
+
+    it("should return null when command fails", () => {
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 1,
+        stdout: "",
+        stderr: "No such file",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = getLastActivityTime("test-agent");
+      expect(result).toBeNull();
+    });
+
+    it("should return null when no timestamp found", () => {
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 0,
+        stdout: "Some output without timestamp",
+        stderr: "",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = getLastActivityTime("test-agent");
+      expect(result).toBeNull();
+    });
+
+    it("should return null on empty output", () => {
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 0,
+        stdout: "",
+        stderr: "",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = getLastActivityTime("test-agent");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("checkAgentProgress", () => {
+    it("should return permission_blocked when permission prompt detected", () => {
+      vi.mocked(tmux.captureSessionOutput).mockReturnValue("Permission required\nAllow once");
+
+      const result = checkAgentProgress("test-agent");
+      expect(result.status).toBe("permission_blocked");
+      expect(result.blockedOn).toBe("Permission prompt detected");
+    });
+
+    it("should return active when recent activity", () => {
+      vi.mocked(tmux.captureSessionOutput).mockReturnValue("Normal output");
+
+      // Mock recent timestamp (1 minute ago)
+      const recentTime = new Date(Date.now() - 60 * 1000);
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 0,
+        stdout: `INFO  ${recentTime.toISOString().slice(0, 19)} +0ms service=opencode`,
+        stderr: "",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = checkAgentProgress("test-agent");
+      expect(result.status).toBe("active");
+    });
+
+    it("should return idle when no activity for 3 minutes", () => {
+      vi.mocked(tmux.captureSessionOutput).mockReturnValue("Normal output");
+
+      // Mock timestamp 3 minutes ago
+      const idleTime = new Date(Date.now() - 3 * 60 * 1000);
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 0,
+        stdout: `INFO  ${idleTime.toISOString().slice(0, 19)} +0ms service=opencode`,
+        stderr: "",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = checkAgentProgress("test-agent");
+      expect(result.status).toBe("idle");
+    });
+
+    it("should return stuck when no activity for 6 minutes", () => {
+      vi.mocked(tmux.captureSessionOutput).mockReturnValue("Normal output");
+
+      // Mock timestamp 6 minutes ago
+      const stuckTime = new Date(Date.now() - 6 * 60 * 1000);
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 0,
+        stdout: `INFO  ${stuckTime.toISOString().slice(0, 19)} +0ms service=opencode`,
+        stderr: "",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = checkAgentProgress("test-agent");
+      expect(result.status).toBe("stuck");
+    });
+
+    it("should return active when activity time cannot be determined", () => {
+      vi.mocked(tmux.captureSessionOutput).mockReturnValue("Normal output");
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 1,
+        stdout: "",
+        stderr: "",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = checkAgentProgress("test-agent");
+      expect(result.status).toBe("active");
+      expect(result.details).toContain("Unable to determine");
+    });
+  });
+
+  describe("isProcessRunning", () => {
+    it("should return true for running process", () => {
+      // Current process is always running
+      const result = isProcessRunning(process.pid);
+      expect(result).toBe(true);
+    });
+
+    it("should return false for non-existent process", () => {
+      // Use a very high PID that's unlikely to exist
+      const result = isProcessRunning(999999999);
+      expect(result).toBe(false);
+    });
+  });
+
+  describe("findOrphanContainers", () => {
+    it("should return list of container IDs", () => {
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 0,
+        stdout: "abc123\ndef456\nghi789",
+        stderr: "",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = findOrphanContainers("test-agent");
+      expect(result).toEqual(["abc123", "def456", "ghi789"]);
+    });
+
+    it("should return empty array when no containers found", () => {
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 0,
+        stdout: "",
+        stderr: "",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = findOrphanContainers("test-agent");
+      expect(result).toEqual([]);
+    });
+
+    it("should return empty array on command failure", () => {
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 1,
+        stdout: "",
+        stderr: "docker not found",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = findOrphanContainers("test-agent");
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("cleanupOrphanContainers", () => {
+    it("should remove found containers and return count", () => {
+      vi.mocked(spawnSync)
+        .mockReturnValueOnce({
+          // findOrphanContainers call
+          status: 0,
+          stdout: "abc123\ndef456",
+          stderr: "",
+          pid: 123,
+          signal: null,
+          output: [],
+        })
+        .mockReturnValue({
+          // docker rm calls
+          status: 0,
+          stdout: "",
+          stderr: "",
+          pid: 123,
+          signal: null,
+          output: [],
+        });
+
+      const result = cleanupOrphanContainers("test-agent");
+      expect(result).toBe(2);
+    });
+
+    it("should return 0 when no orphan containers", () => {
+      vi.mocked(spawnSync).mockReturnValue({
+        status: 0,
+        stdout: "",
+        stderr: "",
+        pid: 123,
+        signal: null,
+        output: [],
+      });
+
+      const result = cleanupOrphanContainers("test-agent");
+      expect(result).toBe(0);
+    });
+  });
+
+  describe("sendNudge", () => {
+    it("should send nudge message to tmux session", () => {
+      vi.mocked(execSync).mockReturnValue(Buffer.from(""));
+
+      const result = sendNudge("test-agent", "Please continue working");
+      expect(result).toBe(true);
+      expect(execSync).toHaveBeenCalledWith(
+        expect.stringContaining("tmux send-keys"),
+        expect.any(Object),
+      );
+    });
+
+    it("should return false when tmux command fails", () => {
+      vi.mocked(execSync).mockImplementation(() => {
+        throw new Error("tmux session not found");
+      });
+
+      const result = sendNudge("test-agent", "Continue");
+      expect(result).toBe(false);
+    });
+
+    it("should escape quotes in message", () => {
+      vi.mocked(execSync).mockReturnValue(Buffer.from(""));
+
+      sendNudge("test-agent", 'Message with "quotes"');
+      expect(execSync).toHaveBeenCalledWith(
+        expect.stringContaining('\\"quotes\\"'),
+        expect.any(Object),
+      );
+    });
+  });
+});

package/src/cli/attach.ts

@@ -1,5 +1,7 @@
-import { attachSession, sessionExists, getSessionName } from "../core/tmux.js";
+import { execSync } from "node:child_process";
 import pc from "picocolors";
+import { getAgentState } from "../config/loader.js";
+import { attachSession, getSessionName, sessionExists } from "../core/tmux.js";
 
 export function attach(name: string): void {
   if (!name) {
@@ -7,6 +9,25 @@ export function attach(name: string): void {
     process.exit(1);
   }
 
+  // Check if this is a sandbox agent
+  const localAgent = getAgentState(name);
+
+  if (localAgent?.sandboxContainer) {
+    // Sandbox agent - attach via docker exec
+    console.log(`Attaching to sandbox container ${localAgent.sandboxContainer}...`);
+    console.log(pc.dim("Detach with: Ctrl+B, D\n"));
+
+    try {
+      execSync(`docker exec -it ${localAgent.sandboxContainer} agentmesh attach ${name}`, {
+        stdio: "inherit",
+      });
+    } catch {
+      // execSync throws on non-zero exit, but that's expected when detaching
+    }
+    return;
+  }
+
+  // Host agent - attach via tmux
   const sessionName = getSessionName(name);
 
   if (!sessionExists(sessionName)) {

package/src/cli/build.ts

@@ -1,4 +1,4 @@
-import { spawnSync, execSync } from "node:child_process";
+import { execSync, spawnSync } from "node:child_process";
 import path from "node:path";
 import pc from "picocolors";
 
@@ -14,7 +14,9 @@ function findProjectRoot(): string {
       dir = path.dirname(dir);
     }
   }
-  throw new Error("Could not find AgentMesh project root. Make sure you're in the agentmesh repository.");
+  throw new Error(
+    "Could not find AgentMesh project root. Make sure you're in the agentmesh repository.",
+  );
 }
 
 export interface BuildOptions {
@@ -128,8 +130,14 @@ async function buildDocker(projectRoot: string, options: BuildOptions): Promise<
   console.log(pc.bold("Built images:"));
   const listResult = spawnSync(
     "docker",
-    ["images", "--filter", "reference=*agentmesh*", "--format", "{{.Repository}}:{{.Tag}}\t{{.Size}}"],
-    { encoding: "utf-8" }
+    [
+      "images",
+      "--filter",
+      "reference=*agentmesh*",
+      "--format",
+      "{{.Repository}}:{{.Tag}}\t{{.Size}}",
+    ],
+    { encoding: "utf-8" },
   );
   if (listResult.stdout) {
     console.log(pc.dim(listResult.stdout));

package/src/cli/context.ts

@@ -1,6 +1,5 @@
 import pc from "picocolors";
 import { getAgentState, loadState } from "../config/loader.js";
-import { extractHandoffContext, formatHandoffContextSummary } from "../context/handoff.js";
 import {
   CONTEXT_DIR,
   deleteContext,

package/src/cli/deploy.ts

@@ -1,4 +1,4 @@
-import { spawnSync, execSync } from "node:child_process";
+import { execSync, spawnSync } from "node:child_process";
 import path from "node:path";
 import pc from "picocolors";
 
@@ -14,7 +14,9 @@ function findProjectRoot(): string {
       dir = path.dirname(dir);
     }
   }
-  throw new Error("Could not find AgentMesh project root. Make sure you're in the agentmesh repository.");
+  throw new Error(
+    "Could not find AgentMesh project root. Make sure you're in the agentmesh repository.",
+  );
 }
 
 export type DeployEnvironment = "dev" | "staging" | "prod";
@@ -51,10 +53,10 @@ export async function deploy(options: DeployOptions): Promise<void> {
   // Step 1: Build
   if (!options.skipBuild) {
     console.log(pc.bold("Step 1: Building..."));
-    
+
     const buildScript = path.join(projectRoot, "scripts", "build.sh");
     const buildArgs = [buildScript, options.environment];
-    
+
     if (options.dryRun) {
       console.log(pc.dim(`Would run: ${buildArgs.join(" ")}`));
     } else {
@@ -76,7 +78,7 @@ export async function deploy(options: DeployOptions): Promise<void> {
   // Step 2: Push to registry
   if (!options.skipPush) {
     console.log(pc.bold("Step 2: Pushing to registry..."));
-    
+
     // Get the image tag from git commit
     let tag: string;
     try {

package/src/cli/index.ts

@@ -10,7 +10,7 @@ import { contextCmd } from "./context.js";
 import { deploy } from "./deploy.js";
 import { init } from "./init.js";
 import { list } from "./list.js";
-import { localUp, localDown, localStatus, localLogs } from "./local.js";
+import { localDown, localLogs, localStatus, localUp } from "./local.js";
 import { logs } from "./logs.js";
 import { migrate } from "./migrate.js";
 import { nudge } from "./nudge.js";
@@ -57,6 +57,13 @@ program
   .option("--auto-setup", "Auto-clone repository for project assignments")
   .option("--serve", "Run opencode serve instead of tmux TUI (for Integration Service)")
   .option("--serve-port <port>", "Port for opencode serve (default: 3001)", "3001")
+  .option("--sandbox", "Run agent in Docker sandbox container with filesystem isolation")
+  .option(
+    "--sandbox-image <image>",
+    "Docker image for sandbox (default: agentmesh/agent-sandbox:latest)",
+  )
+  .option("--sandbox-cpu <limit>", "CPU limit for sandbox (default: 1)")
+  .option("--sandbox-memory <limit>", "Memory limit for sandbox (default: 2g)")
   .action(async (options) => {
     try {
       // Parse serve port as number

package/src/cli/init.ts

@@ -1,7 +1,7 @@
 import * as readline from "node:readline";
-import { loadConfig, saveConfig, createDefaultConfig } from "../config/loader.js";
-import type { Config } from "../config/schema.js";
 import pc from "picocolors";
+import { createDefaultConfig, loadConfig, saveConfig } from "../config/loader.js";
+import type { Config } from "../config/schema.js";
 
 function question(rl: readline.Interface, prompt: string): Promise<string> {
   return new Promise((resolve) => {
@@ -40,7 +40,7 @@ export async function init(): Promise<void> {
   try {
     const apiKey = await question(
       rl,
-      `API Key ${pc.dim("(from agentmeshhq.dev/settings/api-keys)")}: `
+      `API Key ${pc.dim("(from agentmeshhq.dev/settings/api-keys)")}: `,
     );
 
     if (!apiKey) {
@@ -48,25 +48,13 @@ export async function init(): Promise<void> {
       return;
     }
 
-    const workspace = await question(
-      rl,
-      `Workspace ${pc.dim("(default: agentmesh)")}: `
-    );
+    const workspace = await question(rl, `Workspace ${pc.dim("(default: agentmesh)")}: `);
 
-    const command = await question(
-      rl,
-      `Default command ${pc.dim("(default: opencode)")}: `
-    );
+    const command = await question(rl, `Default command ${pc.dim("(default: opencode)")}: `);
 
-    const model = await question(
-      rl,
-      `Default model ${pc.dim("(default: claude-sonnet-4)")}: `
-    );
+    const model = await question(rl, `Default model ${pc.dim("(default: claude-sonnet-4)")}: `);
 
-    const config: Config = createDefaultConfig(
-      apiKey.trim(),
-      workspace.trim() || "agentmesh"
-    );
+    const config: Config = createDefaultConfig(apiKey.trim(), workspace.trim() || "agentmesh");
 
     if (command.trim()) {
       config.defaults.command = command.trim();

package/src/cli/list.ts

@@ -1,7 +1,7 @@
-import { loadState, loadConfig } from "../config/loader.js";
-import { sessionExists, getSessionName, getSessionInfo } from "../core/tmux.js";
-import { checkInbox, fetchAssignments } from "../core/registry.js";
 import pc from "picocolors";
+import { loadConfig, loadState } from "../config/loader.js";
+import { checkInbox, fetchAssignments } from "../core/registry.js";
+import { getSessionInfo, getSessionName, sessionExists } from "../core/tmux.js";
 
 export async function list(): Promise<void> {
   const state = loadState();
@@ -15,7 +15,7 @@ export async function list(): Promise<void> {
 
   console.log(pc.bold("Running Agents:\n"));
   console.log(
-    `${"NAME".padEnd(20)} ${"STATUS".padEnd(10)} ${"SESSION".padEnd(25)} ${"PENDING ID".padEnd(18)} ${"WORKDIR".padEnd(38)} ${"PROJECT"}`
+    `${"NAME".padEnd(20)} ${"STATUS".padEnd(10)} ${"SESSION".padEnd(25)} ${"PENDING ID".padEnd(18)} ${"WORKDIR".padEnd(38)} ${"PROJECT"}`,
   );
   console.log("-".repeat(140));
 
@@ -35,11 +35,7 @@ export async function list(): Promise<void> {
     // Try to check inbox if we have a token
     if (config && agent.token) {
       try {
-        const items = await checkInbox(
-          config.hubUrl,
-          config.workspace,
-          agent.token
-        );
+        const items = await checkInbox(config.hubUrl, config.workspace, agent.token);
         if (items.length > 0) {
           const firstId = items[0]?.id || "-";
           pendingId = pc.yellow(items.length === 1 ? firstId : `${firstId} (+${items.length - 1})`);
@@ -62,7 +58,7 @@ export async function list(): Promise<void> {
     const workdir = agent.workdir || "-";
 
     console.log(
-      `${agent.name.padEnd(20)} ${status.padEnd(19)} ${sessionName.padEnd(25)} ${pendingId.padEnd(18)} ${workdir.padEnd(38)} ${assignedProject}`
+      `${agent.name.padEnd(20)} ${status.padEnd(19)} ${sessionName.padEnd(25)} ${pendingId.padEnd(18)} ${workdir.padEnd(38)} ${assignedProject}`,
     );
 
     if (command) {

package/src/cli/local.ts

@@ -1,4 +1,4 @@
-import { spawn, execSync, spawnSync } from "node:child_process";
+import { execSync, spawn, spawnSync } from "node:child_process";
 import path from "node:path";
 import pc from "picocolors";
 
@@ -24,14 +24,20 @@ function findProjectRoot(): string {
       dir = path.dirname(dir);
     }
   }
-  throw new Error("Could not find AgentMesh project root. Make sure you're in the agentmesh repository.");
+  throw new Error(
+    "Could not find AgentMesh project root. Make sure you're in the agentmesh repository.",
+  );
 }
 
-function getContainerStatus(containerName: string): { running: boolean; healthy: boolean; port?: string } {
+function getContainerStatus(containerName: string): {
+  running: boolean;
+  healthy: boolean;
+  port?: string;
+} {
   try {
     const result = execSync(
       `docker inspect --format='{{.State.Running}}:{{.State.Health.Status}}' ${containerName} 2>/dev/null`,
-      { encoding: "utf-8" }
+      { encoding: "utf-8" },
     ).trim();
     const [running, health] = result.split(":");
     return {
@@ -45,10 +51,9 @@ function getContainerStatus(containerName: string): { running: boolean; healthy:
 
 function getContainerPort(containerName: string, internalPort: number): string | null {
   try {
-    const result = execSync(
-      `docker port ${containerName} ${internalPort} 2>/dev/null | head -1`,
-      { encoding: "utf-8" }
-    ).trim();
+    const result = execSync(`docker port ${containerName} ${internalPort} 2>/dev/null | head -1`, {
+      encoding: "utf-8",
+    }).trim();
     // Format: 0.0.0.0:5432 -> 5432
     const match = result.match(/:(\d+)$/);
     return match ? match[1] : null;
@@ -119,7 +124,7 @@ export async function localStatus(): Promise<void> {
 
   console.log(pc.bold("AgentMesh Local Stack Status"));
   console.log();
-  console.log(pc.dim("Service".padEnd(15) + "Status".padEnd(12) + "Health".padEnd(10) + "Port"));
+  console.log(pc.dim(`${"Service".padEnd(15) + "Status".padEnd(12) + "Health".padEnd(10)}Port`));
   console.log(pc.dim("-".repeat(50)));
 
   let anyRunning = false;
@@ -137,7 +142,7 @@ export async function localStatus(): Promise<void> {
     const portText = port ? pc.cyan(port) : pc.dim("-");
 
     console.log(
-      `${service.name.padEnd(15)}${statusText.padEnd(20)}${healthText.padEnd(18)}${portText}`
+      `${service.name.padEnd(15)}${statusText.padEnd(20)}${healthText.padEnd(18)}${portText}`,
     );
 
     if (status.running) anyRunning = true;
@@ -153,13 +158,17 @@ export async function localStatus(): Promise<void> {
     console.log();
     console.log(pc.bold("Commands:"));
     console.log(`  Stop:      ${pc.cyan("agentmesh local down")}`);
-    console.log(`  Logs:      ${pc.cyan("docker compose -f docker/docker-compose.local.yml logs -f")}`);
+    console.log(
+      `  Logs:      ${pc.cyan("docker compose -f docker/docker-compose.local.yml logs -f")}`,
+    );
   } else {
     console.log(pc.dim("No services running. Start with: agentmesh local up"));
   }
 }
 
-export async function localLogs(options: { follow?: boolean; service?: string } = {}): Promise<void> {
+export async function localLogs(
+  options: { follow?: boolean; service?: string } = {},
+): Promise<void> {
   const projectRoot = findProjectRoot();
   const composePath = path.join(projectRoot, COMPOSE_FILE);