@bazaar.ai/mcp-human-agents 0.1.0

package/src/cli/setup.ts

@@ -0,0 +1,317 @@
+import { createInterface } from "node:readline/promises";
+import { execSync, type ExecSyncOptions } from "node:child_process";
+import { stdin, stdout, stderr } from "node:process";
+
+// TEMPORARY: ngrok tunnel for early testing. Replace with production URL
+// (e.g. https://api.bazaar.ai) before public launch.
+const PLATFORM_API_URL_DEFAULT = "https://ingrid-hypocycloidal-kaliyah.ngrok-free.dev";
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function log(msg: string): void {
+  stderr.write(`${msg}\n`);
+}
+
+function success(msg: string): void {
+  stderr.write(`\x1b[32m✓\x1b[0m ${msg}\n`);
+}
+
+function warn(msg: string): void {
+  stderr.write(`\x1b[33m!\x1b[0m ${msg}\n`);
+}
+
+function fail(msg: string): void {
+  stderr.write(`\x1b[31m✗\x1b[0m ${msg}\n`);
+}
+
+function run(cmd: string, opts?: ExecSyncOptions): string {
+  const result = execSync(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], ...opts });
+  return String(result).trim();
+}
+
+function canRun(cmd: string): boolean {
+  try {
+    run(cmd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Setup Steps ──────────────────────────────────────────────────────
+
+async function checkClaude(): Promise<boolean> {
+  if (canRun("claude --version")) {
+    success("Claude Code CLI found");
+    return true;
+  }
+  fail("Claude Code CLI not found. Install it first: https://docs.anthropic.com/en/docs/claude-code");
+  return false;
+}
+
+function checkPrereqs(): { missing: string[] } {
+  const required = [
+    { cmd: "sshd -v 2>&1 || true", name: "openssh-server" },
+    { cmd: "which tmux", name: "tmux" },
+    { cmd: "which git", name: "git" },
+  ];
+
+  const missing: string[] = [];
+  for (const { cmd, name } of required) {
+    if (canRun(cmd)) {
+      success(`${name} found`);
+    } else {
+      warn(`${name} not found`);
+      missing.push(name);
+    }
+  }
+  return { missing };
+}
+
+async function promptApiKey(rl: ReturnType<typeof createInterface>): Promise<string> {
+  // Check CLI args first
+  const keyArg = process.argv.find((a) => a.startsWith("--api-key="));
+  if (keyArg) {
+    const key = keyArg.split("=")[1];
+    if (key && key.startsWith("bzr_live_")) {
+      return key;
+    }
+  }
+
+  log("");
+  log("You need a Bazaar API key. Get one from the dashboard:");
+  log("  → Go to API Keys in the sidebar, then click Create Key");
+  log("");
+
+  while (true) {
+    const key = await rl.question("Paste your API key (bzr_live_...): ");
+    const trimmed = key.trim();
+    if (trimmed.startsWith("bzr_live_") && trimmed.length > 20) {
+      return trimmed;
+    }
+    warn("API key should start with 'bzr_live_' — try again");
+  }
+}
+
+async function promptPlatformUrl(rl: ReturnType<typeof createInterface>): Promise<string> {
+  // Check CLI args
+  const urlArg = process.argv.find((a) => a.startsWith("--platform-url="));
+  if (urlArg) {
+    return urlArg.split("=").slice(1).join("=");
+  }
+
+  log("");
+  const url = await rl.question(
+    `Platform API URL [${PLATFORM_API_URL_DEFAULT}]: `,
+  );
+  return url.trim() || PLATFORM_API_URL_DEFAULT;
+}
+
+async function validateApiKey(
+  apiKey: string,
+  platformUrl: string,
+): Promise<boolean> {
+  try {
+    const res = await fetch(`${platformUrl}/api/users/me`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (res.ok) {
+      const data = (await res.json()) as Record<string, string>;
+      success(`Authenticated as ${data.email || data.name || "user"}`);
+      return true;
+    }
+    fail(`API key validation failed: ${res.status}`);
+    return false;
+  } catch (err) {
+    fail(`Cannot reach platform at ${platformUrl}: ${err}`);
+    return false;
+  }
+}
+
+async function configureSudoers(
+  rl: ReturnType<typeof createInterface>,
+): Promise<void> {
+  const user = run("whoami");
+  if (user === "root") {
+    success("Running as root — no sudoers configuration needed");
+    return;
+  }
+
+  log("");
+  log("The MCP server needs sudo access for contractor provisioning");
+  log("(user creation, SSH config, tmux). This writes a NOPASSWD sudoers");
+  log(`rule scoped to specific commands for user '${user}'.`);
+  log("");
+
+  const answer = await rl.question("Configure sudoers now? [Y/n]: ");
+  if (answer.trim().toLowerCase() === "n") {
+    warn("Skipped sudoers — you'll need to configure this manually or run as root");
+    return;
+  }
+
+  const sudoersContent = `# Bazaar MCP server — contractor provisioning
+${user} ALL=(root)        NOPASSWD: /usr/sbin/useradd, /usr/sbin/userdel, /usr/sbin/usermod, /usr/bin/pkill
+${user} ALL=(root)        NOPASSWD: /usr/sbin/sshd, /bin/systemctl reload sshd, /bin/systemctl reload ssh, /usr/sbin/service ssh reload
+${user} ALL=(root)        NOPASSWD: /usr/bin/tee, /bin/chmod, /bin/chown, /bin/cp, /bin/mkdir
+${user} ALL=(ALL:ALL)     NOPASSWD: /usr/bin/tmux
+`;
+
+  try {
+    execSync(
+      `echo '${sudoersContent.replace(/'/g, "'\\''")}' | sudo tee /etc/sudoers.d/bazaar-mcp > /dev/null && sudo chmod 0440 /etc/sudoers.d/bazaar-mcp`,
+      { stdio: "pipe" },
+    );
+    // Validate
+    run("sudo visudo -c");
+    success("Sudoers rule installed at /etc/sudoers.d/bazaar-mcp");
+  } catch (err) {
+    warn(`Failed to configure sudoers: ${err}`);
+    warn("You may need to run this manually — see the README");
+  }
+}
+
+function createStateDir(): void {
+  try {
+    run("sudo mkdir -p /var/lib/human-agents && sudo chmod 777 /var/lib/human-agents");
+    success("State directory created at /var/lib/human-agents");
+  } catch {
+    warn("Could not create /var/lib/human-agents — state will use fallback");
+  }
+}
+
+function registerMcpServer(
+  apiKey: string,
+  platformUrl: string,
+): boolean {
+  const isRoot = run("whoami") === "root";
+
+  // Build the env vars for claude mcp add
+  const envFlags = [
+    `-e PLATFORM_API_URL=${platformUrl}`,
+    `-e PLATFORM_API_KEY=${apiKey}`,
+    `-e USE_MOCK_PLATFORM=false`,
+    `-e TUNNEL_ENABLED=true`,
+    isRoot ? "" : `-e PROVISIONING_USE_SUDO=true`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  // Use npx to run the package (works whether installed locally or globally)
+  const cmd = `claude mcp add bazaar ${envFlags} -- npx -y @bazaar.ai/mcp-human-agents`;
+
+  try {
+    run(cmd, { stdio: "pipe" });
+    success("MCP server registered with Claude Code");
+    return true;
+  } catch (err) {
+    // If `claude mcp add` isn't available, show the manual command
+    warn("Could not auto-register. Run this manually:");
+    log("");
+    log(`  ${cmd}`);
+    log("");
+    return false;
+  }
+}
+
+// ── Main ─────────────────────────────────────────────────────────────
+
+export async function runSetup(): Promise<void> {
+  const rl = createInterface({ input: stdin, output: stderr });
+
+  try {
+    log("");
+    log("╔══════════════════════════════════════════╗");
+    log("║       Bazaar MCP Server Setup            ║");
+    log("╚══════════════════════════════════════════╝");
+    log("");
+
+    // 1. Check Claude CLI
+    const hasClaude = await checkClaude();
+
+    // 2. Check system prereqs
+    log("");
+    log("Checking system prerequisites...");
+    const { missing } = checkPrereqs();
+
+    if (missing.length > 0) {
+      log("");
+      const answer = await rl.question(
+        `Install missing packages (${missing.join(", ")})? [Y/n]: `,
+      );
+      if (answer.trim().toLowerCase() !== "n") {
+        try {
+          run(`sudo apt-get update -qq && sudo apt-get install -y ${missing.join(" ")}`, {
+            stdio: "inherit",
+          });
+          success("Packages installed");
+        } catch {
+          warn("Failed to install packages — please install manually");
+        }
+      }
+    }
+
+    // 3. Get API key
+    const apiKey = await promptApiKey(rl);
+
+    // 4. Get platform URL
+    const platformUrl = await promptPlatformUrl(rl);
+
+    // 5. Validate API key
+    log("");
+    log("Validating API key...");
+    const valid = await validateApiKey(apiKey, platformUrl);
+    if (!valid) {
+      warn("Continuing anyway — you can fix the API key later");
+    }
+
+    // 6. Configure sudoers
+    await configureSudoers(rl);
+
+    // 7. Create state directory
+    createStateDir();
+
+    // 8. Start sshd if not running
+    try {
+      run("pgrep sshd > /dev/null || sudo service ssh start");
+      success("sshd is running");
+    } catch {
+      warn("Could not start sshd — contractor SSH access may not work");
+    }
+
+    // 9. Register MCP server
+    log("");
+    log("Registering MCP server with Claude Code...");
+    if (hasClaude) {
+      registerMcpServer(apiKey, platformUrl);
+    } else {
+      warn("Claude CLI not found — showing manual command:");
+      log("");
+      const isRoot = run("whoami") === "root";
+      const envFlags = [
+        `-e PLATFORM_API_URL=${platformUrl}`,
+        `-e PLATFORM_API_KEY=${apiKey}`,
+        `-e USE_MOCK_PLATFORM=false`,
+        `-e TUNNEL_ENABLED=true`,
+        isRoot ? "" : `-e PROVISIONING_USE_SUDO=true`,
+      ]
+        .filter(Boolean)
+        .join(" ");
+      log(`  claude mcp add bazaar ${envFlags} -- npx -y @bazaar.ai/mcp-human-agents`);
+      log("");
+    }
+
+    // Done
+    log("");
+    log("╔══════════════════════════════════════════╗");
+    log("║            Setup Complete!               ║");
+    log("╚══════════════════════════════════════════╝");
+    log("");
+    log("Next steps:");
+    log("  1. Restart Claude Code to load the new MCP server");
+    log('  2. Ask Claude to "summon a human contractor"');
+    log("  3. The contractor connects via the web terminal on the dashboard");
+    log("");
+  } finally {
+    rl.close();
+  }
+}

package/src/config/defaults.ts

@@ -0,0 +1,21 @@
+/** Default timeout for shell commands (ms). */
+export const EXEC_TIMEOUT_MS = 30_000;
+
+/** How often to poll the platform for contractor assignment (ms). */
+export const DEFAULT_POLL_INTERVAL_MS = 3_000;
+
+/** Max time to wait for a contractor to be assigned (ms). */
+export const DEFAULT_POLL_TIMEOUT_MS = 300_000;
+
+/** Seconds to warn a contractor before killing their tmux session. */
+export const DEFAULT_CLEANUP_WARNING_SECONDS = 30;
+
+/** Marker comments for sshd_config blocks managed by human-layer. */
+export const SSHD_MARKER_PREFIX = "# BEGIN human-layer:";
+export const SSHD_MARKER_SUFFIX = "# END human-layer:";
+
+/** Path to sshd_config. */
+export const SSHD_CONFIG_PATH = "/etc/ssh/sshd_config";
+
+/** tmux session name prefix. */
+export const TMUX_SESSION_PREFIX = "hl-";

package/src/config/env.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+
+// TEMPORARY: The default platform URL points to an ngrok tunnel bound to the
+// founder's account.  This is fine for early testing but must be replaced with
+// a proper cloud deployment (e.g. https://api.bazaar.ai) before public launch.
+const DEFAULT_PLATFORM_URL = "https://ingrid-hypocycloidal-kaliyah.ngrok-free.dev";
+
+const EnvSchema = z.object({
+  PLATFORM_API_URL: z.string().url().default(DEFAULT_PLATFORM_URL),
+  PLATFORM_API_KEY: z.string().default(""),
+  /**
+   * Hostname or IP the contractor will SSH into. Only needed when
+   * TUNNEL_ENABLED=false (legacy direct-SSH mode). When the dev box is
+   * exposed via `ngrok tcp`, set this to the ngrok host (e.g.
+   * `0.tcp.ngrok.io`). Default `"auto"` triggers cloud metadata + local
+   * network detection.
+   */
+  VM_EXTERNAL_IP: z.string().default("auto"),
+  /**
+   * Public SSH port. Only needed when TUNNEL_ENABLED=false.
+   */
+  VM_EXTERNAL_SSH_PORT: z.coerce.number().int().positive().default(22),
+  /**
+   * Optional explicit project ID to attach gigs to. If unset, the API
+   * will auto-create a default project for the user behind the API key.
+   */
+  PLATFORM_PROJECT_ID: z.string().optional(),
+  POLL_INTERVAL_MS: z.coerce.number().int().positive().default(3_000),
+  POLL_TIMEOUT_MS: z.coerce.number().int().positive().default(300_000),
+  CLEANUP_WARNING_SECONDS: z.coerce.number().int().positive().default(30),
+  USE_MOCK_PLATFORM: z
+    .string()
+    .transform((v) => v === "true")
+    .default("false"),
+  STATE_FILE_PATH: z
+    .string()
+    .default("/var/lib/human-agents/state.json"),
+  /**
+   * When true, the provisioning code prepends `sudo -n` to privileged
+   * commands. Set this to `true` when the MCP server is NOT running as
+   * root and instead has NOPASSWD sudo for the relevant commands.
+   * See `human-layer/mcp-server/README.md` for the sudoers template.
+   */
+  PROVISIONING_USE_SUDO: z
+    .string()
+    .transform((v) => v === "true")
+    .default("false"),
+  /**
+   * When true, the MCP server opens a reverse WebSocket tunnel to the
+   * platform so contractors can connect without ngrok or public IPs.
+   * When false, falls back to legacy direct-SSH mode using
+   * VM_EXTERNAL_IP / VM_EXTERNAL_SSH_PORT.
+   */
+  TUNNEL_ENABLED: z
+    .string()
+    .transform((v) => v === "true")
+    .default("true"),
+});
+
+export type Env = z.infer<typeof EnvSchema>;
+
+let cachedEnv: Env | null = null;
+
+export function getEnv(): Env {
+  if (!cachedEnv) {
+    cachedEnv = EnvSchema.parse(process.env);
+  }
+  return cachedEnv;
+}
+
+/** For testing: override the cached env. */
+export function setEnv(env: Env): void {
+  cachedEnv = env;
+}

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export { getEnv, setEnv, type Env } from "./env.js";
+export * from "./defaults.js";

package/src/context/generator.ts

@@ -0,0 +1,71 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { logger } from "../utils/logger.js";
+
+export interface ContextInput {
+  reason: string;
+  context: string;
+  skills: string[];
+  urgency: "low" | "medium" | "high";
+  repo: string;
+  branch: string;
+  worktreePath: string;
+}
+
+/**
+ * Generate and write CONTEXT.md to the worktree.
+ * This file is the contractor's briefing — everything they need
+ * to understand the problem and start working.
+ */
+export async function generateContext(input: ContextInput): Promise<string> {
+  const filePath = join(input.worktreePath, "CONTEXT.md");
+
+  const urgencyLabel = {
+    low: "Low — take your time",
+    medium: "Medium — needed soon",
+    high: "High — urgent fix needed",
+  }[input.urgency];
+
+  const content = `# Contractor Context
+
+> This file was auto-generated by the Human Layer MCP server.
+> Read this before starting work.
+
+## What Needs Help
+
+${input.reason}
+
+## Urgency
+
+${urgencyLabel}
+
+## Skills Requested
+
+${input.skills.map((s) => `- ${s}`).join("\n")}
+
+## Context
+
+${input.context}
+
+## Repository
+
+- **Repo:** ${input.repo}
+- **Branch:** ${input.branch}
+- **Working directory:** ${input.worktreePath}
+
+## What Success Looks Like
+
+Resolve the issue described above. Commit your changes to this branch.
+If you have questions or need clarification, check the tmux message area
+or leave comments in the code.
+
+## When You're Done
+
+The AI agent or user will dismiss the session. Your changes will be
+reviewed and optionally merged. Make sure to commit before leaving.
+`;
+
+  await writeFile(filePath, content, "utf-8");
+  logger.info("CONTEXT.md written", { path: filePath });
+  return filePath;
+}

package/src/context/index.ts

@@ -0,0 +1,6 @@
+export { generateContext, type ContextInput } from "./generator.js";
+export {
+  stuckAgentSection,
+  domainGapSection,
+  verificationSection,
+} from "./templates.js";

package/src/context/templates.ts

@@ -0,0 +1,41 @@
+/**
+ * Additional context sections that can be appended to CONTEXT.md
+ * based on the scenario.
+ */
+
+export function stuckAgentSection(
+  attempts: number,
+  lastError: string,
+): string {
+  return `
+## AI Agent Status
+
+The AI agent has been stuck on this problem for **${attempts} attempts**.
+Last error encountered:
+
+\`\`\`
+${lastError}
+\`\`\`
+
+The agent was unable to resolve this on its own and has requested
+human assistance.
+`;
+}
+
+export function domainGapSection(domain: string): string {
+  return `
+## Domain Knowledge Needed
+
+This task requires expertise in **${domain}** that the AI agent does
+not have. Your domain knowledge is the key value-add here.
+`;
+}
+
+export function verificationSection(environment: string): string {
+  return `
+## Verification Needed
+
+The AI agent needs someone to verify behavior in a real **${environment}**
+environment that it cannot access directly.
+`;
+}

package/src/git/branch.ts

@@ -0,0 +1,46 @@
+import { exec } from "../utils/exec.js";
+import { GitError } from "../utils/errors.js";
+
+/**
+ * Get the current branch name.
+ */
+export async function getCurrentBranch(cwd?: string): Promise<string> {
+  try {
+    const { stdout } = await exec("git rev-parse --abbrev-ref HEAD", {
+      cwd,
+    });
+    return stdout.trim();
+  } catch (error) {
+    throw new GitError(`Failed to get current branch: ${error}`);
+  }
+}
+
+/**
+ * Get the current repo name (from remote or directory).
+ */
+export async function getRepoName(cwd?: string): Promise<string> {
+  try {
+    const { stdout } = await exec(
+      "git remote get-url origin 2>/dev/null || basename $(git rev-parse --show-toplevel)",
+      { cwd },
+    );
+    const url = stdout.trim();
+    // Extract repo name from URL
+    const match = url.match(/\/([^/]+?)(?:\.git)?$/);
+    return match ? match[1] : url;
+  } catch (error) {
+    throw new GitError(`Failed to get repo name: ${error}`);
+  }
+}
+
+/**
+ * Get the top-level directory of the git repo.
+ */
+export async function getRepoRoot(cwd?: string): Promise<string> {
+  try {
+    const { stdout } = await exec("git rev-parse --show-toplevel", { cwd });
+    return stdout.trim();
+  } catch (error) {
+    throw new GitError(`Failed to get repo root: ${error}`);
+  }
+}

package/src/git/diff.ts

@@ -0,0 +1,34 @@
+import { exec } from "../utils/exec.js";
+import { logger } from "../utils/logger.js";
+
+/**
+ * Get the list of files changed by the contractor.
+ * Uses git diff to compare the state before and after.
+ */
+export async function getFilesChanged(cwd?: string): Promise<string[]> {
+  try {
+    const { stdout } = await exec("git diff --name-only HEAD~1", { cwd });
+    const files = stdout
+      .trim()
+      .split("\n")
+      .filter((f) => f.length > 0);
+    logger.debug("Files changed", { count: files.length });
+    return files;
+  } catch {
+    // If HEAD~1 doesn't exist or no changes
+    logger.debug("Could not determine files changed");
+    return [];
+  }
+}
+
+/**
+ * Get a summary of changes (for completion report).
+ */
+export async function getDiffSummary(cwd?: string): Promise<string> {
+  try {
+    const { stdout } = await exec("git diff --stat HEAD~1", { cwd });
+    return stdout.trim();
+  } catch {
+    return "No changes detected";
+  }
+}

package/src/git/index.ts

@@ -0,0 +1,4 @@
+export { getCurrentBranch, getRepoName, getRepoRoot } from "./branch.js";
+export { createWorktree, removeWorktree } from "./worktree.js";
+export { mergeContractorChanges } from "./merge.js";
+export { getFilesChanged, getDiffSummary } from "./diff.js";

package/src/git/merge.ts

@@ -0,0 +1,36 @@
+import { exec } from "../utils/exec.js";
+import { GitError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+
+/**
+ * Merge contractor's changes from a worktree branch back
+ * into the working branch.
+ */
+export async function mergeContractorChanges(
+  worktreePath: string,
+  cwd?: string,
+): Promise<void> {
+  try {
+    // Get the branch name from the worktree
+    const { stdout: branch } = await exec(
+      "git rev-parse --abbrev-ref HEAD",
+      { cwd: worktreePath },
+    );
+
+    // First, commit any uncommitted changes in the worktree
+    try {
+      await exec(
+        'git add -A && git commit -m "Contractor changes (auto-commit)"',
+        { cwd: worktreePath },
+      );
+    } catch {
+      // No changes to commit — that's fine
+    }
+
+    // Merge into the main working directory
+    await exec(`git merge ${branch.trim()}`, { cwd });
+    logger.info("Contractor changes merged", { from: branch.trim() });
+  } catch (error) {
+    throw new GitError(`Failed to merge contractor changes: ${error}`);
+  }
+}