@bazaar.ai/mcp-human-agents 0.1.0

package/src/tools/dismiss-human.ts

@@ -0,0 +1,103 @@
+import type { PlatformClient } from "../platform-client/client.js";
+import { cleanupContractor } from "../provisioning/cleanup.js";
+import { mergeContractorChanges } from "../git/merge.js";
+import { getFilesChanged } from "../git/diff.js";
+import { removeWorktree } from "../git/worktree.js";
+import { closeTunnel } from "../tunnel/index.js";
+import { GigStore } from "../state/index.js";
+import { logger } from "../utils/logger.js";
+import type { DismissHumanInput } from "./schemas/dismiss-human.schema.js";
+
+export interface DismissHumanDeps {
+  platformClient: PlatformClient;
+  gigStore: GigStore;
+}
+
+export interface DismissHumanResult {
+  filesChanged: string[];
+  merged: boolean;
+  durationMinutes: number;
+}
+
+/**
+ * dismiss_human — clean up a contractor's access and report completion.
+ *
+ * 1. Update gig status to "dismissing"
+ * 2. Optionally merge contractor's changes
+ * 3. Get list of files changed
+ * 4. Run aggressive cleanup (tmux, processes, SSH, lock account)
+ * 5. Remove worktree if "clean" mode was used
+ * 6. Report completion to platform
+ * 7. Remove gig from store
+ */
+export async function dismissHuman(
+  input: DismissHumanInput,
+  deps: DismissHumanDeps,
+): Promise<DismissHumanResult> {
+  const gig = deps.gigStore.get(input.gigId);
+  gig.status = "dismissing";
+
+  logger.info("Dismissing human contractor", {
+    gigId: input.gigId,
+    contractorName: gig.contractorName,
+    merge: input.merge,
+  });
+
+  // Calculate duration
+  const startedAt = new Date(gig.startedAt);
+  const durationMinutes = Math.round(
+    (Date.now() - startedAt.getTime()) / 60_000,
+  );
+
+  // Merge if requested
+  let filesChanged: string[] = [];
+  if (input.merge && gig.worktreePath) {
+    await mergeContractorChanges(gig.worktreePath);
+    filesChanged = await getFilesChanged();
+  } else if (input.merge) {
+    // Shared worktree — changes are already in place
+    filesChanged = await getFilesChanged();
+  }
+
+  // Close reverse tunnel if active
+  if (gig.tunnelActive) {
+    closeTunnel(input.gigId);
+  }
+
+  // Aggressive cleanup
+  await cleanupContractor({
+    username: gig.linuxUser,
+    tmuxSession: gig.tmuxSession,
+  });
+
+  // Remove worktree if "clean" mode
+  if (gig.worktreePath) {
+    await removeWorktree(gig.worktreePath);
+  }
+
+  // Report to platform
+  await deps.platformClient.completeGig({
+    gigId: input.gigId,
+    durationMinutes,
+    filesChanged,
+    merged: input.merge,
+    rating: input.rating,
+    resolutionNotes: input.resolutionNotes,
+  });
+
+  // Remove from store
+  deps.gigStore.remove(input.gigId);
+
+  logger.info("Human contractor dismissed", {
+    gigId: input.gigId,
+    durationMinutes,
+    filesChanged: filesChanged.length,
+    merged: input.merge,
+  });
+
+  return {
+    filesChanged,
+    merged: input.merge,
+    durationMinutes,
+  };
+}

package/src/tools/index.ts

@@ -0,0 +1,9 @@
+export { summonHuman, type SummonHumanDeps, type SummonHumanResult } from "./summon-human.js";
+export { dismissHuman, type DismissHumanDeps, type DismissHumanResult } from "./dismiss-human.js";
+export { listHumans, type ListHumansResult } from "./list-humans.js";
+export { messageHuman, type MessageHumanResult } from "./message-human.js";
+
+export { SummonHumanInputSchema } from "./schemas/summon-human.schema.js";
+export { DismissHumanInputSchema } from "./schemas/dismiss-human.schema.js";
+export { ListHumansInputSchema } from "./schemas/list-humans.schema.js";
+export { MessageHumanInputSchema } from "./schemas/message-human.schema.js";

package/src/tools/list-humans.ts

@@ -0,0 +1,54 @@
+import { GigStore } from "../state/index.js";
+import {
+  hasClientsAttached,
+  getLastActivity,
+} from "../provisioning/tmux-session.js";
+
+export interface ActiveContractorInfo {
+  gigId: string;
+  name: string;
+  status: "waiting" | "connected" | "idle";
+  skills: string[];
+  connectedSince?: string;
+  lastActivity?: string;
+  rate: number;
+}
+
+export interface ListHumansResult {
+  contractors: ActiveContractorInfo[];
+}
+
+/**
+ * list_humans — show currently active contractors on this VM.
+ */
+export async function listHumans(gigStore: GigStore): Promise<ListHumansResult> {
+  const gigs = gigStore.list();
+
+  const contractors: ActiveContractorInfo[] = await Promise.all(
+    gigs.map(async (gig) => {
+      const connected = await hasClientsAttached(gig.tmuxSession);
+      const lastActivity = await getLastActivity(gig.tmuxSession);
+
+      let status: "waiting" | "connected" | "idle";
+      if (!connected && gig.status === "active") {
+        status = "waiting";
+      } else if (connected) {
+        status = "connected";
+      } else {
+        status = "idle";
+      }
+
+      return {
+        gigId: gig.gigId,
+        name: gig.contractorName,
+        status,
+        skills: gig.skills,
+        connectedSince: gig.startedAt,
+        lastActivity: lastActivity?.toISOString(),
+        rate: gig.rate,
+      };
+    }),
+  );
+
+  return { contractors };
+}

package/src/tools/message-human.ts

@@ -0,0 +1,28 @@
+import { GigStore } from "../state/index.js";
+import { displayMessage } from "../provisioning/tmux-session.js";
+import { logger } from "../utils/logger.js";
+import type { MessageHumanInput } from "./schemas/message-human.schema.js";
+
+export interface MessageHumanResult {
+  delivered: boolean;
+}
+
+/**
+ * message_human — send a message into the contractor's tmux session.
+ */
+export async function messageHuman(
+  input: MessageHumanInput,
+  gigStore: GigStore,
+): Promise<MessageHumanResult> {
+  const gig = gigStore.get(input.gigId);
+
+  const delivered = await displayMessage(gig.tmuxSession, input.message);
+
+  logger.info("Message sent to contractor", {
+    gigId: input.gigId,
+    contractorName: gig.contractorName,
+    delivered,
+  });
+
+  return { delivered };
+}

package/src/tools/schemas/dismiss-human.schema.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+export const DismissHumanInputSchema = z.object({
+  gigId: z.string().describe("The gig ID to dismiss"),
+  merge: z
+    .boolean()
+    .describe("Whether to merge contractor's changes into working branch"),
+  rating: z
+    .number()
+    .int()
+    .min(1)
+    .max(5)
+    .optional()
+    .describe("Rating 1-5 (optional, user can rate later via platform)"),
+  resolutionNotes: z
+    .string()
+    .optional()
+    .describe("What was fixed (optional)"),
+});
+
+export type DismissHumanInput = z.infer<typeof DismissHumanInputSchema>;

package/src/tools/schemas/list-humans.schema.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+
+// list_humans takes no input
+export const ListHumansInputSchema = z.object({});
+
+export type ListHumansInput = z.infer<typeof ListHumansInputSchema>;

package/src/tools/schemas/message-human.schema.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+export const MessageHumanInputSchema = z.object({
+  gigId: z.string().describe("The gig ID of the contractor to message"),
+  message: z.string().describe("The message to send"),
+});
+
+export type MessageHumanInput = z.infer<typeof MessageHumanInputSchema>;

package/src/tools/schemas/summon-human.schema.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+export const SummonHumanInputSchema = z.object({
+  reason: z.string().describe("Why the AI needs help"),
+  skills: z.array(z.string()).describe("What expertise is needed"),
+  context: z
+    .string()
+    .describe("What was tried, what failed, relevant files"),
+  urgency: z
+    .enum(["low", "medium", "high"])
+    .describe("How urgent is this request"),
+  worktree: z
+    .enum(["shared", "clean"])
+    .describe(
+      "shared = human sees AI's dirty working state, clean = fresh checkout",
+    ),
+});
+
+export type SummonHumanInput = z.infer<typeof SummonHumanInputSchema>;

package/src/tools/summon-human.ts

@@ -0,0 +1,180 @@
+import type { PlatformClient } from "../platform-client/client.js";
+import { pollForAssignment } from "../platform-client/polling.js";
+import {
+  createUser,
+  writeAuthorizedKey,
+  addForceCommand,
+  sessionName,
+  createSession,
+} from "../provisioning/index.js";
+import { getCurrentBranch, getRepoName, getRepoRoot } from "../git/index.js";
+import { createWorktree } from "../git/worktree.js";
+import { generateContext } from "../context/index.js";
+import { GigStore } from "../state/index.js";
+import { getEnv } from "../config/env.js";
+import { getExternalIp } from "../utils/ip.js";
+import { openTunnel, storeTunnel } from "../tunnel/index.js";
+import { logger } from "../utils/logger.js";
+import type { SummonHumanInput } from "./schemas/summon-human.schema.js";
+import type { Urgency } from "../../../shared/src/gig.types.js";
+
+export interface SummonHumanDeps {
+  platformClient: PlatformClient;
+  gigStore: GigStore;
+}
+
+export interface SummonHumanResult {
+  gigId: string;
+  contractorName: string;
+  sshCommand: string;
+  connectionMode: "tunnel" | "direct";
+  status: "waiting_for_connection";
+}
+
+/**
+ * summon_human — the most complex MCP tool.
+ *
+ * Orchestrates the full flow:
+ * 1. Detect repo info
+ * 2. POST gig to platform
+ * 3. Poll for contractor assignment
+ * 4. Create Linux user
+ * 5. Write SSH pubkey
+ * 6. Configure ForceCommand in sshd_config
+ * 7. Create tmux session
+ * 8. Write CONTEXT.md
+ * 9. Notify platform that VM is ready
+ * 10. Store active gig
+ */
+export async function summonHuman(
+  input: SummonHumanInput,
+  deps: SummonHumanDeps,
+): Promise<SummonHumanResult> {
+  const env = getEnv();
+
+  // 1. Detect repo info
+  const repoRoot = await getRepoRoot();
+  const branch = await getCurrentBranch();
+  const repo = await getRepoName();
+  const vmIp =
+    env.VM_EXTERNAL_IP === "auto"
+      ? await getExternalIp()
+      : env.VM_EXTERNAL_IP;
+  const vmPort = env.VM_EXTERNAL_SSH_PORT;
+
+  logger.info("Summoning human contractor", {
+    reason: input.reason,
+    skills: input.skills.join(", "),
+    urgency: input.urgency,
+  });
+
+  // 2. Create gig on platform.
+  // The MCP tool schema accepts lowercase urgency for readability
+  // ("low" / "medium" / "high" reads better in LLM tool descriptions),
+  // but the human-layer API Urgency type is uppercase. Translate here.
+  const { gigId } = await deps.platformClient.createGig({
+    reason: input.reason,
+    skills: input.skills,
+    context: input.context,
+    urgency: input.urgency.toUpperCase() as Urgency,
+    worktreeMode: input.worktree,
+    vmIp,
+    repo,
+    branch,
+    projectId: env.PLATFORM_PROJECT_ID,
+  });
+
+  // 3. Poll for contractor assignment
+  const status = await pollForAssignment(deps.platformClient, gigId);
+  const contractor = status.contractor!;
+
+  logger.info("Contractor assigned, provisioning access", {
+    gigId,
+    contractorName: contractor.name,
+  });
+
+  // 4. Create Linux user
+  await createUser(contractor.name);
+
+  // 5. Write SSH pubkey
+  await writeAuthorizedKey(contractor.name, contractor.pubkey);
+
+  // 6. Determine working directory
+  const tmuxSessionId = sessionName(gigId);
+  let worktreePath = repoRoot;
+
+  if (input.worktree === "clean") {
+    worktreePath = `/tmp/hl-worktree-${gigId}`;
+    await createWorktree(branch, worktreePath);
+  }
+
+  // 7. Create tmux session — owned by the contractor user so their
+  // SSH ForceCommand can attach to it. tmux scopes sessions per uid.
+  await createSession(tmuxSessionId, worktreePath, contractor.name);
+
+  // 8. Configure ForceCommand
+  await addForceCommand(contractor.name, tmuxSessionId);
+
+  // 9. Write CONTEXT.md
+  await generateContext({
+    reason: input.reason,
+    context: input.context,
+    skills: input.skills,
+    urgency: input.urgency,
+    repo,
+    branch,
+    worktreePath,
+  });
+
+  // 10. Set up connectivity: reverse tunnel or direct SSH
+  const useTunnel = env.TUNNEL_ENABLED;
+  let sshCommand: string;
+
+  if (useTunnel) {
+    // Open reverse tunnel — platform routes contractor traffic through it
+    const platformWsUrl = env.PLATFORM_API_URL.replace(/^http/, "ws");
+    const handle = openTunnel(platformWsUrl, env.PLATFORM_API_KEY, gigId);
+    storeTunnel(gigId, handle);
+
+    sshCommand = `(via tunnel to platform)`;
+
+    logger.info("Reverse tunnel opened", { gigId });
+  } else {
+    // Legacy direct-SSH mode: build SSH command with public IP/port
+    sshCommand =
+      vmPort === 22
+        ? `ssh ${contractor.name}@${vmIp}`
+        : `ssh ${contractor.name}@${vmIp} -p ${vmPort}`;
+  }
+
+  await deps.platformClient.markReady(gigId, sshCommand);
+
+  // 11. Store active gig
+  deps.gigStore.add({
+    gigId,
+    contractorName: contractor.name,
+    linuxUser: contractor.name,
+    tmuxSession: tmuxSessionId,
+    worktreePath: input.worktree === "clean" ? worktreePath : undefined,
+    sshCommand,
+    skills: input.skills,
+    rate: contractor.rate,
+    startedAt: new Date().toISOString(),
+    status: "active",
+    tunnelActive: useTunnel,
+  });
+
+  logger.info("Human contractor summoned successfully", {
+    gigId,
+    contractorName: contractor.name,
+    connectionMode: useTunnel ? "tunnel" : "direct",
+  });
+
+  return {
+    gigId,
+    contractorName: contractor.name,
+    sshCommand,
+    connectionMode: useTunnel ? "tunnel" : "direct",
+    status: "waiting_for_connection",
+  };
+}

package/src/tunnel/client.ts

@@ -0,0 +1,116 @@
+import { WebSocket } from "ws";
+import { createConnection, type Socket } from "node:net";
+import { logger } from "../utils/logger.js";
+
+export interface TunnelHandle {
+  close(): void;
+}
+
+/**
+ * Open a reverse tunnel WebSocket to the platform.
+ *
+ * The platform will route contractor web-terminal traffic through this
+ * tunnel. When data arrives, we relay it to localhost:22 (sshd) and
+ * send responses back through the WebSocket.
+ *
+ * The connection is lazy: the TCP socket to localhost:22 is only
+ * created when the first data frame arrives (triggered by the
+ * platform's ssh2 client initiating a handshake).
+ */
+export function openTunnel(
+  platformWsUrl: string,
+  apiKey: string,
+  gigId: string,
+): TunnelHandle {
+  const wsUrl = `${platformWsUrl}/ws/tunnel?gigId=${encodeURIComponent(gigId)}&token=${encodeURIComponent(apiKey)}`;
+
+  let ws: WebSocket | null = null;
+  let tcp: Socket | null = null;
+  let closed = false;
+
+  function connectWs(): void {
+    if (closed) return;
+
+    ws = new WebSocket(wsUrl);
+    ws.binaryType = "nodebuffer";
+
+    ws.on("open", () => {
+      logger.info("Tunnel WebSocket connected", { gigId });
+    });
+
+    ws.on("message", (data: Buffer) => {
+      if (!tcp) {
+        // Lazy-open TCP to local sshd on first data
+        tcp = createConnection({ host: "127.0.0.1", port: 22 }, () => {
+          logger.info("Tunnel TCP connected to local sshd", { gigId });
+          // Send the buffered first frame
+          tcp!.write(data);
+        });
+
+        tcp.on("data", (chunk: Buffer) => {
+          if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(chunk);
+          }
+        });
+
+        tcp.on("close", () => {
+          logger.info("Tunnel TCP closed", { gigId });
+          tcp = null;
+          // Don't close the WebSocket — a new terminal session may
+          // open another TCP connection via this same tunnel.
+        });
+
+        tcp.on("error", (err) => {
+          logger.warn("Tunnel TCP error", {
+            gigId,
+            error: err.message,
+          });
+          tcp?.destroy();
+          tcp = null;
+        });
+      } else {
+        tcp.write(data);
+      }
+    });
+
+    ws.on("close", (code, reason) => {
+      logger.info("Tunnel WebSocket closed", {
+        gigId,
+        code,
+        reason: reason.toString(),
+      });
+      tcp?.destroy();
+      tcp = null;
+
+      // Reconnect with backoff unless explicitly closed
+      if (!closed) {
+        const delay = 3_000 + Math.random() * 2_000;
+        logger.info("Tunnel reconnecting", { gigId, delayMs: Math.round(delay) });
+        setTimeout(connectWs, delay);
+      }
+    });
+
+    ws.on("error", (err) => {
+      logger.warn("Tunnel WebSocket error", {
+        gigId,
+        error: err.message,
+      });
+      // on("close") will fire after this and handle reconnection
+    });
+  }
+
+  connectWs();
+
+  return {
+    close() {
+      closed = true;
+      tcp?.destroy();
+      tcp = null;
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.close(1000, "Tunnel closed by MCP server");
+      }
+      ws = null;
+      logger.info("Tunnel closed", { gigId });
+    },
+  };
+}

package/src/tunnel/index.ts

@@ -0,0 +1,26 @@
+import type { TunnelHandle } from "./client.js";
+
+export { openTunnel, type TunnelHandle } from "./client.js";
+
+/**
+ * In-memory map of active tunnel handles keyed by gigId.
+ * Not serialized — tunnels are re-established on restart via
+ * the MCP server's crash-recovery flow if needed.
+ */
+const activeTunnels = new Map<string, TunnelHandle>();
+
+export function storeTunnel(gigId: string, handle: TunnelHandle): void {
+  activeTunnels.set(gigId, handle);
+}
+
+export function closeTunnel(gigId: string): void {
+  const handle = activeTunnels.get(gigId);
+  if (handle) {
+    handle.close();
+    activeTunnels.delete(gigId);
+  }
+}
+
+export function hasTunnel(gigId: string): boolean {
+  return activeTunnels.has(gigId);
+}

package/src/utils/errors.ts

@@ -0,0 +1,64 @@
+export class HumanLayerError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+  ) {
+    super(message);
+    this.name = "HumanLayerError";
+  }
+}
+
+export class ProvisioningError extends HumanLayerError {
+  constructor(message: string) {
+    super(message, "PROVISIONING_ERROR");
+    this.name = "ProvisioningError";
+  }
+}
+
+export class SshConfigError extends HumanLayerError {
+  constructor(message: string) {
+    super(message, "SSH_CONFIG_ERROR");
+    this.name = "SshConfigError";
+  }
+}
+
+export class PlatformApiError extends HumanLayerError {
+  constructor(
+    message: string,
+    public readonly statusCode?: number,
+  ) {
+    super(message, "PLATFORM_API_ERROR");
+    this.name = "PlatformApiError";
+  }
+}
+
+export class GigNotFoundError extends HumanLayerError {
+  constructor(gigId: string) {
+    super(`Gig not found: ${gigId}`, "GIG_NOT_FOUND");
+    this.name = "GigNotFoundError";
+  }
+}
+
+export class CleanupError extends HumanLayerError {
+  constructor(
+    message: string,
+    public readonly partialFailures: string[],
+  ) {
+    super(message, "CLEANUP_ERROR");
+    this.name = "CleanupError";
+  }
+}
+
+export class TmuxError extends HumanLayerError {
+  constructor(message: string) {
+    super(message, "TMUX_ERROR");
+    this.name = "TmuxError";
+  }
+}
+
+export class GitError extends HumanLayerError {
+  constructor(message: string) {
+    super(message, "GIT_ERROR");
+    this.name = "GitError";
+  }
+}

package/src/utils/exec.ts

@@ -0,0 +1,29 @@
+import { exec as cpExec, type ExecOptions } from "node:child_process";
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+}
+
+export function exec(
+  command: string,
+  options?: ExecOptions,
+): Promise<ExecResult> {
+  return new Promise((resolve, reject) => {
+    cpExec(command, { timeout: 30_000, ...options }, (error, stdout, stderr) => {
+      if (error) {
+        reject(
+          Object.assign(error, {
+            stdout: stdout?.toString() ?? "",
+            stderr: stderr?.toString() ?? "",
+          }),
+        );
+        return;
+      }
+      resolve({
+        stdout: stdout?.toString() ?? "",
+        stderr: stderr?.toString() ?? "",
+      });
+    });
+  });
+}