@bazaar.ai/mcp-human-agents 0.1.0

package/src/provisioning/privileged.ts

@@ -0,0 +1,128 @@
+import { writeFile as fsWriteFile, copyFile as fsCopyFile, readFile as fsReadFile } from "node:fs/promises";
+import { exec } from "../utils/exec.js";
+import { getEnv } from "../config/env.js";
+
+/**
+ * Privileged operation helpers.
+ *
+ * Two modes, controlled by `PROVISIONING_USE_SUDO`:
+ *
+ * - `false` (default): the MCP server is running as root (e.g. `sudo
+ *   claude` or a systemd service running as root). All commands and
+ *   file operations execute directly through Node fs / child_process.
+ *
+ * - `true`: the MCP server is running as an unprivileged user that
+ *   has NOPASSWD sudo for the specific commands listed in
+ *   `human-layer/mcp-server/README.md`. All commands are prefixed
+ *   with `sudo -n`, and file operations go through `sudo tee` /
+ *   `sudo cp` so writes work even when the target file is owned by
+ *   root.
+ *
+ * Centralising this in one module means the provisioning code stays
+ * readable and the sudo decision lives in exactly one place.
+ */
+
+function useSudo(): boolean {
+  return getEnv().PROVISIONING_USE_SUDO;
+}
+
+/**
+ * Run a privileged shell command. With sudo enabled, the command
+ * is wrapped in `sudo -n bash -c '...'` so multi-step pipelines
+ * (`mkdir && chmod && chown`) still execute as root in one go.
+ */
+export async function runPrivileged(command: string): Promise<void> {
+  if (useSudo()) {
+    await exec(`sudo -n bash -c ${shQuote(command)}`);
+  } else {
+    await exec(command);
+  }
+}
+
+/**
+ * Run a shell command as a specific (non-root) user. Used for things
+ * like `tmux new-session` where the resulting object must be owned by
+ * the contractor, not root, so that the contractor's SSH login can
+ * attach to it.
+ *
+ * `sudo -u user` works whether the caller is root (no sudoers needed)
+ * or an unprivileged user with NOPASSWD configured for that target.
+ */
+export async function runAsUser(
+  user: string,
+  command: string,
+): Promise<{ stdout: string; stderr: string }> {
+  if (!/^[a-zA-Z0-9_-]+$/.test(user)) {
+    throw new Error(`Invalid user name: ${user}`);
+  }
+  // We always go through sudo here. When running as root, no
+  // password / NOPASSWD is needed. When running as a regular user,
+  // they need NOPASSWD for `sudo -u <target>` (covered by the
+  // sudoers template in human-layer/mcp-server/README.md).
+  return exec(`sudo -n -u ${user} bash -c ${shQuote(command)}`);
+}
+
+/**
+ * Read a file. Reads always go through Node fs — `/etc/ssh/sshd_config`
+ * is world-readable by default, so this rarely needs sudo. If a future
+ * deployment locks it down, we can revisit.
+ */
+export async function readPrivilegedFile(path: string): Promise<string> {
+  return fsReadFile(path, "utf-8");
+}
+
+/**
+ * Write a file as root, regardless of which mode we're in.
+ * In sudo mode, content is piped through `sudo tee` and chmod runs
+ * separately.
+ */
+export async function writePrivilegedFile(
+  path: string,
+  content: string,
+  mode?: number,
+): Promise<void> {
+  if (useSudo()) {
+    // `tee` writes the file as root; we pipe the content via stdin
+    // by base64-encoding it to dodge any quoting hazards.
+    const b64 = Buffer.from(content, "utf-8").toString("base64");
+    await exec(
+      `bash -c ${shQuote(`echo ${b64} | base64 -d | sudo -n tee ${shQuote(path)} > /dev/null`)}`,
+    );
+    if (typeof mode === "number") {
+      await exec(`sudo -n chmod ${mode.toString(8)} ${shQuote(path)}`);
+    }
+  } else {
+    await fsWriteFile(path, content, mode != null ? { encoding: "utf-8", mode } : { encoding: "utf-8" });
+  }
+}
+
+/**
+ * Copy a file as root. Used by the sshd_config backup/restore flow.
+ */
+export async function copyPrivilegedFile(src: string, dst: string): Promise<void> {
+  if (useSudo()) {
+    await exec(`sudo -n cp ${shQuote(src)} ${shQuote(dst)}`);
+  } else {
+    await fsCopyFile(src, dst);
+  }
+}
+
+/**
+ * `chown user:group path` as root.
+ */
+export async function chownPrivileged(owner: string, path: string): Promise<void> {
+  // shellEscape-style guard to avoid injection through `owner`
+  if (!/^[a-zA-Z0-9_.:-]+$/.test(owner)) {
+    throw new Error(`Invalid owner spec: ${owner}`);
+  }
+  if (useSudo()) {
+    await exec(`sudo -n chown ${owner} ${shQuote(path)}`);
+  } else {
+    await exec(`chown ${owner} ${shQuote(path)}`);
+  }
+}
+
+/** Quote a value for safe inclusion in a single-quoted bash string. */
+function shQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/src/provisioning/ssh-config.ts

@@ -0,0 +1,197 @@
+import {
+  readPrivilegedFile,
+  writePrivilegedFile,
+  copyPrivilegedFile,
+  runPrivileged,
+} from "./privileged.js";
+import { SshConfigError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+import {
+  SSHD_CONFIG_PATH,
+  SSHD_MARKER_PREFIX,
+  SSHD_MARKER_SUFFIX,
+} from "../config/defaults.js";
+
+/**
+ * Add a ForceCommand block to sshd_config for a contractor.
+ *
+ * Uses marker comments for deterministic insertion/removal:
+ *   # BEGIN human-layer:{username}
+ *   Match User {username}
+ *     ForceCommand tmux attach -t {session} || tmux new -s {session}
+ *     AllowTcpForwarding no
+ *     X11Forwarding no
+ *   # END human-layer:{username}
+ *
+ * CRITICAL: This is the highest-risk module in the system.
+ * Incorrect sshd_config means locked-out VMs.
+ * Always backup, validate with sshd -t, then reload.
+ */
+export async function addForceCommand(
+  username: string,
+  tmuxSession: string,
+  configPath = SSHD_CONFIG_PATH,
+): Promise<void> {
+  const beginMarker = `${SSHD_MARKER_PREFIX}${username}`;
+  const endMarker = `${SSHD_MARKER_SUFFIX}${username}`;
+
+  const block = [
+    beginMarker,
+    `Match User ${username}`,
+    `  ForceCommand tmux attach -t ${tmuxSession} || tmux new -s ${tmuxSession}`,
+    "  AllowTcpForwarding no",
+    "  X11Forwarding no",
+    endMarker,
+  ].join("\n");
+
+  try {
+    // Backup current config
+    await copyPrivilegedFile(configPath, `${configPath}.bak`);
+
+    // Read current config
+    const current = await readPrivilegedFile(configPath);
+
+    // Remove existing block if present (idempotent)
+    const cleaned = removeBlock(current, beginMarker, endMarker);
+
+    // Append new block
+    const updated = cleaned.trimEnd() + "\n\n" + block + "\n";
+
+    // Write updated config
+    await writePrivilegedFile(configPath, updated);
+
+    // Validate with sshd -t
+    await validateSshdConfig(configPath);
+
+    // Reload sshd
+    await reloadSshd();
+
+    logger.info("ForceCommand added to sshd_config", {
+      user: username,
+      session: tmuxSession,
+    });
+  } catch (error) {
+    // Attempt to restore backup
+    try {
+      await copyPrivilegedFile(`${configPath}.bak`, configPath);
+      await reloadSshd();
+      logger.warn("Restored sshd_config from backup after error");
+    } catch (restoreError) {
+      logger.error("CRITICAL: Failed to restore sshd_config backup", {
+        error: String(restoreError),
+      });
+    }
+
+    throw new SshConfigError(
+      `Failed to add ForceCommand for ${username}: ${error}`,
+    );
+  }
+}
+
+/**
+ * Remove the ForceCommand block for a contractor from sshd_config.
+ */
+export async function removeForceCommand(
+  username: string,
+  configPath = SSHD_CONFIG_PATH,
+): Promise<void> {
+  const beginMarker = `${SSHD_MARKER_PREFIX}${username}`;
+  const endMarker = `${SSHD_MARKER_SUFFIX}${username}`;
+
+  try {
+    await copyPrivilegedFile(configPath, `${configPath}.bak`);
+
+    const current = await readPrivilegedFile(configPath);
+    const cleaned = removeBlock(current, beginMarker, endMarker);
+
+    await writePrivilegedFile(configPath, cleaned);
+    await validateSshdConfig(configPath);
+    await reloadSshd();
+
+    logger.info("ForceCommand removed from sshd_config", {
+      user: username,
+    });
+  } catch (error) {
+    try {
+      await copyPrivilegedFile(`${configPath}.bak`, configPath);
+      await reloadSshd();
+    } catch {
+      logger.error("CRITICAL: Failed to restore sshd_config backup");
+    }
+
+    throw new SshConfigError(
+      `Failed to remove ForceCommand for ${username}: ${error}`,
+    );
+  }
+}
+
+/**
+ * Remove a marker-delimited block from config text.
+ */
+function removeBlock(
+  content: string,
+  beginMarker: string,
+  endMarker: string,
+): string {
+  const lines = content.split("\n");
+  const result: string[] = [];
+  let inBlock = false;
+
+  for (const line of lines) {
+    if (line.trim() === beginMarker) {
+      inBlock = true;
+      continue;
+    }
+    if (line.trim() === endMarker) {
+      inBlock = false;
+      continue;
+    }
+    if (!inBlock) {
+      result.push(line);
+    }
+  }
+
+  return result.join("\n");
+}
+
+/**
+ * Validate sshd_config syntax. Throws if invalid.
+ */
+async function validateSshdConfig(
+  configPath = SSHD_CONFIG_PATH,
+): Promise<void> {
+  try {
+    await runPrivileged(`sshd -t -f ${configPath}`);
+  } catch (error) {
+    throw new SshConfigError(`sshd_config validation failed: ${error}`);
+  }
+}
+
+/**
+ * Reload sshd to apply config changes.
+ *
+ * Tries `systemctl reload` first (the systemd path) and falls back to
+ * `service ssh reload` for environments without systemd (some WSL2
+ * distros, minimal containers).
+ */
+async function reloadSshd(): Promise<void> {
+  try {
+    await runPrivileged("systemctl reload sshd");
+    return;
+  } catch {
+    /* fall through */
+  }
+  try {
+    await runPrivileged("systemctl reload ssh");
+    return;
+  } catch {
+    /* fall through */
+  }
+  try {
+    await runPrivileged("service ssh reload");
+    return;
+  } catch (error) {
+    throw new SshConfigError(`Failed to reload sshd: ${error}`);
+  }
+}
+

package/src/provisioning/tmux-session.ts

@@ -0,0 +1,136 @@
+import { exec } from "../utils/exec.js";
+import { runAsUser } from "./privileged.js";
+import { TmuxError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+import { TMUX_SESSION_PREFIX } from "../config/defaults.js";
+
+/**
+ * Generate a tmux session name for a gig.
+ */
+export function sessionName(gigId: string): string {
+  return `${TMUX_SESSION_PREFIX}${gigId}`;
+}
+
+/**
+ * Create a new tmux session **owned by the contractor user** so that
+ * sshd's ForceCommand (`tmux attach -t ...`) running as that user can
+ * see and attach to it.
+ *
+ * Without `runAsUser`, a tmux session created by the MCP server (root)
+ * is owned by root, and the contractor's later attach silently fails
+ * because tmux scopes sessions per-uid via the socket directory.
+ */
+export async function createSession(
+  session: string,
+  workdir: string,
+  user?: string,
+): Promise<void> {
+  const cmd = `tmux new-session -d -s ${session} -c ${workdir}`;
+  try {
+    if (user) {
+      await runAsUser(user, cmd);
+    } else {
+      await exec(cmd);
+    }
+    logger.info("tmux session created", { session, workdir, user });
+  } catch (error) {
+    throw new TmuxError(`Failed to create tmux session ${session}: ${error}`);
+  }
+}
+
+/**
+ * Check if a tmux session has any clients attached.
+ * Used to detect if a contractor is currently connected.
+ */
+export async function hasClientsAttached(session: string): Promise<boolean> {
+  try {
+    const { stdout } = await exec(`tmux list-clients -t ${session}`);
+    return stdout.trim().length > 0;
+  } catch {
+    // Session might not exist or have no clients
+    return false;
+  }
+}
+
+/**
+ * Check if a tmux session exists.
+ */
+export async function sessionExists(session: string): Promise<boolean> {
+  try {
+    await exec(`tmux has-session -t ${session}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Send a display message to a tmux session.
+ * The message is shown as an overlay for the specified duration.
+ */
+export async function displayMessage(
+  session: string,
+  message: string,
+  durationMs = 10_000,
+): Promise<boolean> {
+  try {
+    // Escape single quotes in message
+    const escaped = message.replace(/'/g, "'\\''");
+    await exec(
+      `tmux display-message -t ${session} -d ${durationMs} '${escaped}'`,
+    );
+    return true;
+  } catch {
+    logger.warn("Failed to display message in tmux session", { session });
+    return false;
+  }
+}
+
+/**
+ * Kill a tmux session, optionally showing a warning first.
+ */
+export async function killSession(
+  session: string,
+  warningSeconds = 0,
+): Promise<void> {
+  try {
+    if (warningSeconds > 0 && (await hasClientsAttached(session))) {
+      await displayMessage(
+        session,
+        `⚠ Session ending in ${warningSeconds} seconds`,
+        warningSeconds * 1000,
+      );
+      await sleep(warningSeconds * 1000);
+    }
+
+    await exec(`tmux kill-session -t ${session}`);
+    logger.info("tmux session killed", { session });
+  } catch {
+    // Session might already be gone
+    logger.debug("tmux session already gone", { session });
+  }
+}
+
+/**
+ * Get the last activity time for a session (if detectable).
+ */
+export async function getLastActivity(
+  session: string,
+): Promise<Date | undefined> {
+  try {
+    const { stdout } = await exec(
+      `tmux display-message -t ${session} -p '#{session_activity}'`,
+    );
+    const timestamp = parseInt(stdout.trim(), 10);
+    if (!isNaN(timestamp)) {
+      return new Date(timestamp * 1000);
+    }
+  } catch {
+    // Can't determine activity
+  }
+  return undefined;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/server.ts

@@ -0,0 +1,111 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { getEnv } from "./config/env.js";
+import { GigStore } from "./state/gig-store.js";
+import { StatePersistence } from "./state/persistence.js";
+import { HttpPlatformClient } from "./platform-client/client.js";
+import { MockPlatformClient } from "./platform-client/mock-client.js";
+import type { PlatformClient } from "./platform-client/client.js";
+import { logger } from "./utils/logger.js";
+
+import {
+  summonHuman,
+  dismissHuman,
+  listHumans,
+  messageHuman,
+  SummonHumanInputSchema,
+  DismissHumanInputSchema,
+  ListHumansInputSchema,
+  MessageHumanInputSchema,
+} from "./tools/index.js";
+
+export async function createServer(): Promise<McpServer> {
+  const env = getEnv();
+
+  // Initialize dependencies
+  const gigStore = new GigStore();
+  const persistence = new StatePersistence(env.STATE_FILE_PATH);
+
+  // Restore state from disk (crash recovery)
+  await persistence.load(gigStore);
+
+  // Choose platform client
+  const platformClient: PlatformClient = env.USE_MOCK_PLATFORM
+    ? new MockPlatformClient()
+    : new HttpPlatformClient(env.PLATFORM_API_URL, env.PLATFORM_API_KEY);
+
+  if (env.USE_MOCK_PLATFORM) {
+    logger.info("Using mock platform client");
+  } else {
+    logger.info("Using HTTP platform client", {
+      url: env.PLATFORM_API_URL,
+    });
+  }
+
+  const deps = { platformClient, gigStore };
+
+  // Create MCP server
+  const server = new McpServer({
+    name: "human-agents",
+    version: "0.1.0",
+  });
+
+  // Register tools
+  server.tool(
+    "summon_human",
+    "Summon a human contractor to help with a task. They will SSH into the VM and work in a tmux session.",
+    SummonHumanInputSchema.shape,
+    async ({ reason, skills, context, urgency, worktree }) => {
+      const result = await summonHuman(
+        { reason, skills, context, urgency, worktree },
+        deps,
+      );
+      await persistence.save(gigStore);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  );
+
+  server.tool(
+    "dismiss_human",
+    "Dismiss a human contractor, revoke their access, and optionally merge their changes.",
+    DismissHumanInputSchema.shape,
+    async ({ gigId, merge, rating, resolutionNotes }) => {
+      const result = await dismissHuman(
+        { gigId, merge, rating, resolutionNotes },
+        deps,
+      );
+      await persistence.save(gigStore);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  );
+
+  server.tool(
+    "list_humans",
+    "List all currently active human contractors on this VM.",
+    ListHumansInputSchema.shape,
+    async () => {
+      const result = await listHumans(gigStore);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  );
+
+  server.tool(
+    "message_human",
+    "Send a message to a human contractor's tmux session.",
+    MessageHumanInputSchema.shape,
+    async ({ gigId, message }) => {
+      const result = await messageHuman({ gigId, message }, gigStore);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  );
+
+  logger.info("MCP server created with 4 tools registered");
+  return server;
+}

package/src/state/gig-store.ts

@@ -0,0 +1,56 @@
+import { GigNotFoundError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+import type { ActiveGig } from "./types.js";
+
+/**
+ * In-memory store of active gigs on this VM.
+ * Backed by optional file persistence for crash recovery.
+ */
+export class GigStore {
+  private gigs = new Map<string, ActiveGig>();
+
+  add(gig: ActiveGig): void {
+    this.gigs.set(gig.gigId, gig);
+    logger.info("Gig added to store", {
+      gigId: gig.gigId,
+      contractorName: gig.contractorName,
+    });
+  }
+
+  get(gigId: string): ActiveGig {
+    const gig = this.gigs.get(gigId);
+    if (!gig) throw new GigNotFoundError(gigId);
+    return gig;
+  }
+
+  tryGet(gigId: string): ActiveGig | undefined {
+    return this.gigs.get(gigId);
+  }
+
+  remove(gigId: string): void {
+    this.gigs.delete(gigId);
+    logger.info("Gig removed from store", { gigId });
+  }
+
+  list(): ActiveGig[] {
+    return Array.from(this.gigs.values());
+  }
+
+  has(gigId: string): boolean {
+    return this.gigs.has(gigId);
+  }
+
+  /** Serialize all active gigs for crash recovery. */
+  serialize(): string {
+    return JSON.stringify(Array.from(this.gigs.values()), null, 2);
+  }
+
+  /** Restore gigs from serialized data. */
+  restore(data: string): void {
+    const gigs: ActiveGig[] = JSON.parse(data);
+    for (const gig of gigs) {
+      this.gigs.set(gig.gigId, gig);
+    }
+    logger.info(`Restored ${gigs.length} gigs from persistence`);
+  }
+}

package/src/state/index.ts

@@ -0,0 +1,3 @@
+export { GigStore } from "./gig-store.js";
+export { StatePersistence } from "./persistence.js";
+export type { ActiveGig } from "./types.js";

package/src/state/persistence.ts

@@ -0,0 +1,42 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { logger } from "../utils/logger.js";
+import type { GigStore } from "./gig-store.js";
+
+/**
+ * Persist gig store to disk for crash recovery.
+ * On startup, reads the file and restores any active gigs
+ * that need cleanup.
+ */
+export class StatePersistence {
+  constructor(private readonly filePath: string) {}
+
+  async save(store: GigStore): Promise<void> {
+    try {
+      await mkdir(dirname(this.filePath), { recursive: true });
+      await writeFile(this.filePath, store.serialize(), "utf-8");
+      logger.debug("State persisted to disk", { path: this.filePath });
+    } catch (error) {
+      logger.warn("Failed to persist state", {
+        path: this.filePath,
+        error: String(error),
+      });
+    }
+  }
+
+  async load(store: GigStore): Promise<void> {
+    try {
+      const data = await readFile(this.filePath, "utf-8");
+      store.restore(data);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        logger.debug("No state file found, starting fresh");
+        return;
+      }
+      logger.warn("Failed to load state", {
+        path: this.filePath,
+        error: String(error),
+      });
+    }
+  }
+}

package/src/state/types.ts

@@ -0,0 +1,14 @@
+export interface ActiveGig {
+  gigId: string;
+  contractorName: string;
+  linuxUser: string;
+  tmuxSession: string;
+  worktreePath?: string;
+  sshCommand: string;
+  skills: string[];
+  rate: number;
+  startedAt: string;
+  status: "provisioning" | "active" | "dismissing";
+  /** Whether this gig uses a reverse tunnel instead of direct SSH. */
+  tunnelActive?: boolean;
+}