@bazaar.ai/mcp-human-agents 0.1.0

package/src/git/worktree.ts

@@ -0,0 +1,42 @@
+import { exec } from "../utils/exec.js";
+import { GitError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+
+/**
+ * Create a git worktree for "clean" mode.
+ * Gives the contractor a fresh checkout of the branch
+ * without the AI's dirty working state.
+ */
+export async function createWorktree(
+  branch: string,
+  targetDir: string,
+  cwd?: string,
+): Promise<string> {
+  try {
+    await exec(`git worktree add ${targetDir} ${branch}`, { cwd });
+    logger.info("Git worktree created", { branch, targetDir });
+    return targetDir;
+  } catch (error) {
+    throw new GitError(
+      `Failed to create worktree at ${targetDir}: ${error}`,
+    );
+  }
+}
+
+/**
+ * Remove a git worktree.
+ */
+export async function removeWorktree(
+  targetDir: string,
+  cwd?: string,
+): Promise<void> {
+  try {
+    await exec(`git worktree remove ${targetDir} --force`, { cwd });
+    logger.info("Git worktree removed", { targetDir });
+  } catch (error) {
+    logger.warn("Failed to remove worktree (may not exist)", {
+      targetDir,
+      error: String(error),
+    });
+  }
+}

package/src/http-wrapper.ts

@@ -0,0 +1,94 @@
+/**
+ * Quick HTTP wrapper around the MCP tools for testing.
+ * Exposes summon_human, dismiss_human, list_humans, message_human as REST endpoints.
+ */
+
+import express from "express";
+import { getEnv } from "./config/env.js";
+import { GigStore } from "./state/gig-store.js";
+import { StatePersistence } from "./state/persistence.js";
+import { MockPlatformClient } from "./platform-client/mock-client.js";
+import { HttpPlatformClient } from "./platform-client/client.js";
+import type { PlatformClient } from "./platform-client/client.js";
+import {
+  summonHuman,
+  dismissHuman,
+  listHumans,
+  messageHuman,
+} from "./tools/index.js";
+
+const env = getEnv();
+const gigStore = new GigStore();
+const persistence = new StatePersistence(env.STATE_FILE_PATH);
+
+const platformClient: PlatformClient = env.USE_MOCK_PLATFORM
+  ? new MockPlatformClient()
+  : new HttpPlatformClient(env.PLATFORM_API_URL, env.PLATFORM_API_KEY);
+
+const deps = { platformClient, gigStore };
+
+const app = express();
+app.use(express.json());
+
+app.get("/health", (_req, res) => {
+  res.json({ status: "ok", service: "human-agents-http", gigs: gigStore.list().length });
+});
+
+app.post("/summon", async (req, res) => {
+  try {
+    const result = await summonHuman(req.body, deps);
+    await persistence.save(gigStore);
+    res.json(result);
+  } catch (err: any) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+app.post("/dismiss", async (req, res) => {
+  try {
+    const result = await dismissHuman(req.body, deps);
+    await persistence.save(gigStore);
+    res.json(result);
+  } catch (err: any) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+app.get("/list", async (_req, res) => {
+  try {
+    const result = await listHumans(gigStore);
+    res.json(result);
+  } catch (err: any) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+app.post("/message", async (req, res) => {
+  try {
+    const result = await messageHuman(req.body, gigStore);
+    res.json(result);
+  } catch (err: any) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+const PORT = parseInt(process.env.HTTP_PORT ?? "9999", 10);
+
+async function start() {
+  await persistence.load(gigStore);
+  app.listen(PORT, () => {
+    console.log(`Human-agents HTTP wrapper on port ${PORT}`);
+    console.log(`  Mock platform: ${env.USE_MOCK_PLATFORM}`);
+    console.log(`  VM IP: ${env.VM_EXTERNAL_IP}`);
+    console.log(`\nEndpoints:`);
+    console.log(`  POST /summon   — summon a contractor`);
+    console.log(`  POST /dismiss  — dismiss a contractor`);
+    console.log(`  GET  /list     — list active contractors`);
+    console.log(`  POST /message  — message a contractor`);
+  });
+}
+
+start().catch((err) => {
+  console.error("Failed to start:", err);
+  process.exit(1);
+});

package/src/index.ts

@@ -0,0 +1,32 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+import { logger } from "./utils/logger.js";
+
+async function main(): Promise<void> {
+  logger.info("Starting human-agents MCP server");
+
+  const server = await createServer();
+  const transport = new StdioServerTransport();
+
+  await server.connect(transport);
+
+  logger.info("MCP server running on stdio transport");
+
+  // Handle graceful shutdown
+  process.on("SIGINT", async () => {
+    logger.info("Received SIGINT, shutting down");
+    await server.close();
+    process.exit(0);
+  });
+
+  process.on("SIGTERM", async () => {
+    logger.info("Received SIGTERM, shutting down");
+    await server.close();
+    process.exit(0);
+  });
+}
+
+main().catch((error) => {
+  logger.error("Fatal error", { error: String(error) });
+  process.exit(1);
+});

package/src/platform-client/client.ts

@@ -0,0 +1,93 @@
+import axios, { type AxiosInstance } from "axios";
+import { PlatformApiError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+import type {
+  CreateGigRequest,
+  CreateGigResponse,
+  GigStatusResponse,
+  CompleteGigRequest,
+  CompleteGigResponse,
+} from "./types.js";
+
+export interface PlatformClient {
+  createGig(request: CreateGigRequest): Promise<CreateGigResponse>;
+  getGigStatus(gigId: string): Promise<GigStatusResponse>;
+  markReady(gigId: string, sshCommand: string): Promise<void>;
+  completeGig(request: CompleteGigRequest): Promise<CompleteGigResponse>;
+}
+
+export class HttpPlatformClient implements PlatformClient {
+  private http: AxiosInstance;
+
+  constructor(baseUrl: string, apiKey: string) {
+    this.http = axios.create({
+      baseURL: baseUrl,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      timeout: 10_000,
+    });
+  }
+
+  async createGig(request: CreateGigRequest): Promise<CreateGigResponse> {
+    try {
+      const { data } = await this.http.post<CreateGigResponse>(
+        "/gigs",
+        request,
+      );
+      logger.info("Gig created on platform", { gigId: data.gigId });
+      return data;
+    } catch (error) {
+      throw this.wrapError("Failed to create gig", error);
+    }
+  }
+
+  async getGigStatus(gigId: string): Promise<GigStatusResponse> {
+    try {
+      const { data } = await this.http.get<GigStatusResponse>(
+        `/gigs/${gigId}/status`,
+      );
+      return data;
+    } catch (error) {
+      throw this.wrapError(`Failed to get gig status: ${gigId}`, error);
+    }
+  }
+
+  async markReady(gigId: string, sshCommand: string): Promise<void> {
+    try {
+      await this.http.post(`/gigs/${gigId}/ready`, { sshCommand });
+      logger.info("Gig marked as ready", { gigId });
+    } catch (error) {
+      throw this.wrapError(`Failed to mark gig ready: ${gigId}`, error);
+    }
+  }
+
+  async completeGig(
+    request: CompleteGigRequest,
+  ): Promise<CompleteGigResponse> {
+    try {
+      const { data } = await this.http.post<CompleteGigResponse>(
+        `/gigs/${request.gigId}/complete`,
+        request,
+      );
+      logger.info("Gig completed on platform", { gigId: request.gigId });
+      return data;
+    } catch (error) {
+      throw this.wrapError(
+        `Failed to complete gig: ${request.gigId}`,
+        error,
+      );
+    }
+  }
+
+  private wrapError(message: string, error: unknown): PlatformApiError {
+    if (axios.isAxiosError(error)) {
+      return new PlatformApiError(
+        `${message}: ${error.message}`,
+        error.response?.status,
+      );
+    }
+    return new PlatformApiError(message);
+  }
+}

package/src/platform-client/index.ts

@@ -0,0 +1,4 @@
+export { type PlatformClient, HttpPlatformClient } from "./client.js";
+export { MockPlatformClient } from "./mock-client.js";
+export { pollForAssignment } from "./polling.js";
+export type * from "./types.js";

package/src/platform-client/mock-client.ts

@@ -0,0 +1,92 @@
+import { logger } from "../utils/logger.js";
+import type { PlatformClient } from "./client.js";
+import type {
+  CreateGigRequest,
+  CreateGigResponse,
+  GigStatusResponse,
+  CompleteGigRequest,
+  CompleteGigResponse,
+} from "./types.js";
+
+interface MockGig {
+  id: string;
+  status: "OPEN" | "ASSIGNED" | "IN_PROGRESS" | "COMPLETED";
+  assignedAt?: number;
+}
+
+/**
+ * In-memory mock platform client for Phase 1 standalone testing.
+ * A "mock contractor" auto-accepts gigs after a configurable delay.
+ */
+export class MockPlatformClient implements PlatformClient {
+  private gigs = new Map<string, MockGig>();
+  private nextId = 1;
+
+  constructor(
+    /** Delay in ms before a mock contractor auto-accepts a gig. */
+    private readonly autoAcceptDelayMs = 5_000,
+    /** Mock contractor info. */
+    private readonly mockContractor = {
+      name: "mock-contractor",
+      pubkey:
+        "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleMockKeyForTesting mock@test",
+      rate: 50,
+    },
+  ) {}
+
+  async createGig(request: CreateGigRequest): Promise<CreateGigResponse> {
+    const id = `mock-gig-${this.nextId++}`;
+    const gig: MockGig = { id, status: "OPEN" };
+    this.gigs.set(id, gig);
+
+    // Auto-accept after delay
+    setTimeout(() => {
+      const g = this.gigs.get(id);
+      if (g && g.status === "OPEN") {
+        g.status = "ASSIGNED";
+        g.assignedAt = Date.now();
+        logger.info("[MOCK] Contractor auto-accepted gig", { gigId: id });
+      }
+    }, this.autoAcceptDelayMs);
+
+    logger.info("[MOCK] Gig created", {
+      gigId: id,
+      reason: request.reason,
+    });
+    return { gigId: id, status: "OPEN" };
+  }
+
+  async getGigStatus(gigId: string): Promise<GigStatusResponse> {
+    const gig = this.gigs.get(gigId);
+    if (!gig) {
+      return { gigId, status: "CANCELLED" };
+    }
+    return {
+      gigId,
+      status: gig.status,
+      contractor:
+        gig.status === "ASSIGNED" || gig.status === "IN_PROGRESS"
+          ? this.mockContractor
+          : undefined,
+    };
+  }
+
+  async markReady(gigId: string, sshCommand: string): Promise<void> {
+    const gig = this.gigs.get(gigId);
+    if (gig) {
+      gig.status = "IN_PROGRESS";
+      logger.info("[MOCK] Gig marked ready", { gigId, sshCommand });
+    }
+  }
+
+  async completeGig(
+    request: CompleteGigRequest,
+  ): Promise<CompleteGigResponse> {
+    const gig = this.gigs.get(request.gigId);
+    if (gig) {
+      gig.status = "COMPLETED";
+    }
+    logger.info("[MOCK] Gig completed", { gigId: request.gigId });
+    return { gigId: request.gigId, status: "COMPLETED" };
+  }
+}

package/src/platform-client/polling.ts

@@ -0,0 +1,53 @@
+import type { PlatformClient } from "./client.js";
+import type { GigStatusResponse } from "./types.js";
+import { PlatformApiError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+import { getEnv } from "../config/env.js";
+
+/**
+ * Poll GET /gigs/{id}/status until a contractor is assigned.
+ * Returns the status response with contractor info.
+ * Throws PlatformApiError if polling times out.
+ */
+export async function pollForAssignment(
+  client: PlatformClient,
+  gigId: string,
+): Promise<GigStatusResponse> {
+  const env = getEnv();
+  const intervalMs = env.POLL_INTERVAL_MS;
+  const timeoutMs = env.POLL_TIMEOUT_MS;
+
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    const status = await client.getGigStatus(gigId);
+
+    // Both the real API (Prisma enums) and the mock client return
+    // uppercase values per `human-layer/shared/src/gig.types.ts`.
+    if (
+      (status.status === "ASSIGNED" || status.status === "IN_PROGRESS") &&
+      status.contractor
+    ) {
+      logger.info("Contractor assigned", {
+        gigId,
+        contractorName: status.contractor.name,
+      });
+      return status;
+    }
+
+    if (status.status === "CANCELLED") {
+      throw new PlatformApiError(`Gig was cancelled: ${gigId}`);
+    }
+
+    logger.debug("Polling for contractor assignment...", { gigId });
+    await sleep(intervalMs);
+  }
+
+  throw new PlatformApiError(
+    `Timed out waiting for contractor assignment after ${timeoutMs}ms`,
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/platform-client/types.ts

@@ -0,0 +1,9 @@
+// Re-export shared platform API types
+export type {
+  CreateGigRequest,
+  CreateGigResponse,
+  GigStatusResponse,
+  MarkReadyRequest,
+  CompleteGigRequest,
+  CompleteGigResponse,
+} from "../../../shared/src/platform-api.types.js";

package/src/provisioning/authorized-keys.ts

@@ -0,0 +1,52 @@
+import { writePrivilegedFile, chownPrivileged } from "./privileged.js";
+import { ProvisioningError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+
+/**
+ * Write a public key to a user's authorized_keys file.
+ *
+ * Goes through the privileged helpers because the per-contractor home
+ * directory is owned by root immediately after `useradd`. After
+ * writing the file (as root) we chown it to the contractor so sshd
+ * accepts it.
+ */
+export async function writeAuthorizedKey(
+  username: string,
+  pubkey: string,
+): Promise<void> {
+  const keyPath = `/home/${username}/.ssh/authorized_keys`;
+
+  try {
+    // Validate pubkey format (basic check)
+    if (!pubkey.startsWith("ssh-") && !pubkey.startsWith("ecdsa-")) {
+      throw new Error(`Invalid public key format: ${pubkey.slice(0, 20)}...`);
+    }
+
+    await writePrivilegedFile(keyPath, pubkey.trim() + "\n", 0o600);
+    await chownPrivileged(`${username}:${username}`, keyPath);
+
+    logger.info("Authorized key written", { user: username });
+  } catch (error) {
+    throw new ProvisioningError(
+      `Failed to write authorized key for ${username}: ${error}`,
+    );
+  }
+}
+
+/**
+ * Remove the authorized_keys file for a user.
+ */
+export async function removeAuthorizedKey(username: string): Promise<void> {
+  const keyPath = `/home/${username}/.ssh/authorized_keys`;
+
+  try {
+    await writePrivilegedFile(keyPath, "", 0o600);
+    logger.info("Authorized key removed", { user: username });
+  } catch (error) {
+    // File might not exist if provisioning was partial
+    logger.warn("Failed to remove authorized key (may not exist)", {
+      user: username,
+      error: String(error),
+    });
+  }
+}

package/src/provisioning/cleanup.ts

@@ -0,0 +1,106 @@
+import { killSession } from "./tmux-session.js";
+import { removeAuthorizedKey } from "./authorized-keys.js";
+import { removeForceCommand } from "./ssh-config.js";
+import { killUserProcesses, lockUser } from "./linux-user.js";
+import { CleanupError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+import { getEnv } from "../config/env.js";
+
+export interface CleanupTarget {
+  username: string;
+  tmuxSession: string;
+}
+
+/**
+ * Aggressive cleanup sequence for dismissing a contractor.
+ * Each step is independent and wrapped in try/catch — partial failures
+ * don't prevent the remaining steps from executing.
+ *
+ * Order matters:
+ * 1. Kill tmux session (with warning if connected)
+ * 2. Kill all user processes
+ * 3. Remove SSH pubkey
+ * 4. Remove ForceCommand from sshd_config
+ * 5. Reload sshd (happens inside removeForceCommand)
+ * 6. Lock the account
+ */
+export async function cleanupContractor(
+  target: CleanupTarget,
+): Promise<void> {
+  const { username, tmuxSession } = target;
+  const failures: string[] = [];
+  const env = getEnv();
+
+  logger.info("Starting contractor cleanup", {
+    user: username,
+    session: tmuxSession,
+  });
+
+  // 1. Kill tmux session
+  try {
+    await killSession(tmuxSession, env.CLEANUP_WARNING_SECONDS);
+  } catch (error) {
+    failures.push(`tmux kill: ${error}`);
+    logger.warn("Cleanup: failed to kill tmux session", {
+      user: username,
+      error: String(error),
+    });
+  }
+
+  // 2. Kill all user processes
+  try {
+    await killUserProcesses(username);
+  } catch (error) {
+    failures.push(`kill processes: ${error}`);
+    logger.warn("Cleanup: failed to kill user processes", {
+      user: username,
+      error: String(error),
+    });
+  }
+
+  // 3. Remove SSH pubkey
+  try {
+    await removeAuthorizedKey(username);
+  } catch (error) {
+    failures.push(`remove key: ${error}`);
+    logger.warn("Cleanup: failed to remove authorized key", {
+      user: username,
+      error: String(error),
+    });
+  }
+
+  // 4. Remove ForceCommand (also reloads sshd)
+  try {
+    await removeForceCommand(username);
+  } catch (error) {
+    failures.push(`remove ForceCommand: ${error}`);
+    logger.warn("Cleanup: failed to remove ForceCommand", {
+      user: username,
+      error: String(error),
+    });
+  }
+
+  // 5. Lock account
+  try {
+    await lockUser(username);
+  } catch (error) {
+    failures.push(`lock user: ${error}`);
+    logger.warn("Cleanup: failed to lock user", {
+      user: username,
+      error: String(error),
+    });
+  }
+
+  if (failures.length > 0) {
+    logger.warn("Cleanup completed with partial failures", {
+      user: username,
+      failureCount: failures.length,
+    });
+    throw new CleanupError(
+      `Cleanup of ${username} had ${failures.length} failures`,
+      failures,
+    );
+  }
+
+  logger.info("Cleanup completed successfully", { user: username });
+}

package/src/provisioning/index.ts

@@ -0,0 +1,13 @@
+export { createUser, lockUser, killUserProcesses } from "./linux-user.js";
+export { writeAuthorizedKey, removeAuthorizedKey } from "./authorized-keys.js";
+export { addForceCommand, removeForceCommand } from "./ssh-config.js";
+export {
+  sessionName,
+  createSession,
+  hasClientsAttached,
+  sessionExists,
+  displayMessage,
+  killSession,
+  getLastActivity,
+} from "./tmux-session.js";
+export { cleanupContractor, type CleanupTarget } from "./cleanup.js";

package/src/provisioning/linux-user.ts

@@ -0,0 +1,66 @@
+import { runPrivileged } from "./privileged.js";
+import { ProvisioningError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+
+/**
+ * Create a new Linux user for a contractor.
+ * Creates home directory and .ssh directory.
+ */
+export async function createUser(username: string): Promise<void> {
+  try {
+    const u = shellEscape(username);
+    await runPrivileged(`useradd -m -s /bin/bash ${u}`);
+    await runPrivileged(
+      `mkdir -p /home/${u}/.ssh && ` +
+        `chmod 700 /home/${u}/.ssh && ` +
+        `chown ${u}:${u} /home/${u}/.ssh`,
+    );
+    logger.info("Linux user created", { user: username });
+  } catch (error) {
+    throw new ProvisioningError(
+      `Failed to create user ${username}: ${error}`,
+    );
+  }
+}
+
+/**
+ * Lock a user account so they can no longer log in.
+ */
+export async function lockUser(username: string): Promise<void> {
+  try {
+    await runPrivileged(`usermod -L ${shellEscape(username)}`);
+    logger.info("Linux user locked", { user: username });
+  } catch (error) {
+    throw new ProvisioningError(
+      `Failed to lock user ${username}: ${error}`,
+    );
+  }
+}
+
+/**
+ * Kill all processes owned by a user.
+ * Does not throw if user has no processes.
+ */
+export async function killUserProcesses(username: string): Promise<void> {
+  try {
+    await runPrivileged(`pkill -u ${shellEscape(username)}`);
+    logger.info("Killed processes for user", { user: username });
+  } catch {
+    // pkill returns non-zero if no processes found — that's fine
+    logger.debug("No processes to kill for user", { user: username });
+  }
+}
+
+
+/**
+ * Basic shell escaping to prevent injection.
+ * Only allows alphanumeric, hyphen, underscore.
+ */
+function shellEscape(value: string): string {
+  if (!/^[a-zA-Z0-9_-]+$/.test(value)) {
+    throw new ProvisioningError(
+      `Invalid value for shell command: ${value}`,
+    );
+  }
+  return value;
+}