Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

14.4 KB
Raw Blame
// packages/cli/src/test-helpers/contract-mcp.ts
/**
 * Drives a real claudish MCP server over stdio (newline-delimited JSON-RPC, the MCP stdio
 * transport) for the *.contract.test.ts files. The test process stands in for Claude Code:
 * it is the server's parent, so a correct `hostPid` equals `process.pid` (design §8.1 9b).
 *
 * The protocol is public. What is NOT in the contract, and is therefore isolated in the
 * "tool adapters" section at the bottom, is the exact argument and result field names of the
 * claudish tools. Each adapter is marked INFERRED; fix a mismatch there, once.
 */
import { randomBytes } from "node:crypto";
import { chmodSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { findMagmuxBinaryOrNull } from "../launcher/magmux-binary.js";
import {
  type OrphanReport,
  killLeftovers,
  waitNoOrphans,
} from "../pane/test-helpers/hermetic-env.js";
import type { TempLayout } from "./contract-records.js";

export const SRC_DIR = join(import.meta.dir, "..");
export const PACKAGE_DIR = join(SRC_DIR, "..");
export const SERVER_ENTRY = join(SRC_DIR, "index.ts");
/**
 * The child every contract suite runs: the pane fake (marker mode with FAKE_MODEL), the
 * server's default CLAUDISH_BIN.
 */
export const PANE_FAKE_CHILD = join(SRC_DIR, "pane", "test-helpers", "fake-interactive-child.ts");
/** The `_meta` key Claude Code sends the calling tool-use id under. claudish does not read it. */
export const CLAUDE_CODE_TOOL_USE_META_KEY = "claudecode/toolUseId";
export const FAKE_MODEL = "contract-fake-model";

/** Suites that start panes skip with this message when magmux is absent (testing.md). */
export const MAGMUX_AVAILABLE = findMagmuxBinaryOrNull() !== null;
export const NO_MAGMUX_MESSAGE = "magmux not installed — not checked";

/**
 * A pane root per layout (`/tmp/cpt-<8 hex>`), passed to the server as
 * CLAUDISH_PANE_ROOT: its sweep, its pane limit and the
 * no-orphan check stay inside the test (§20.4).
 */
const paneRoots = new Map<string, string>();
export function paneRootOf(layout: TempLayout): string {
  let root = paneRoots.get(layout.root);
  if (!root) {
    root = `/tmp/cpt-${randomBytes(4).toString("hex")}`;
    paneRoots.set(layout.root, root);
  }
  return root;
}

/** Wait until nothing of the layout's panes remains, then remove the pane root. */
export async function paneOrphans(layout: TempLayout, ms = 10_000): Promise<OrphanReport> {
  const sockRoot = paneRootOf(layout);
  const report = await waitNoOrphans({ sockRoot }, ms);
  killLeftovers({ sockRoot });
  rmSync(sockRoot, { recursive: true, force: true });
  paneRoots.delete(layout.root);
  return report;
}

/**
 * A server environment built from scratch, so nothing leaks in from the shell that runs the
 * tests (for example a CLAUDE_CODE_SESSION_ID set because the tests run inside Claude Code).
 * `undefined` in `extra` deletes a key.
 */
export function serverEnv(
  layout: TempLayout,
  extra: Record<string, string | undefined> = {}
): Record<string, string> {
  chmodSync(PANE_FAKE_CHILD, 0o755);
  const env: Record<string, string> = {
    PATH: process.env.PATH ?? "",
    HOME: layout.home,
    TMPDIR: tmpdir(),
    CLAUDISH_SESSIONS_DIR: layout.sessionsDir,
    CLAUDISH_BIN: PANE_FAKE_CHILD,
    CLAUDE_CONFIG_DIR: layout.configDir,
    NO_COLOR: "1",
    // The hermetic keys of makePaneTestEnv: a pane child built from this env reads no
    // real config, keychain or 1Password, and its pane root is the test's own.
    ZDOTDIR: layout.home,
    SHELL: "/bin/zsh",
    USER: process.env.USER ?? "test",
    LANG: "en_US.UTF-8",
    CLAUDISH_DISABLE_KEYCHAIN: "1",
    CLAUDISH_DISABLE_OP: "1",
    CLAUDISH_DISABLE_CATALOG_WARM: "1",
    CLAUDISH_NO_PREDEFINED_ENDPOINTS: "1",
    CLAUDISH_PANE_ROOT: paneRootOf(layout),
  };
  for (const [key, value] of Object.entries(extra)) {
    if (value === undefined) delete env[key];
    else env[key] = value;
  }
  return env;
}

export interface ToolResult {
  isError: boolean;
  text: string;
  json: Record<string, unknown> | undefined;
  raw: unknown;
}

interface Pending {
  resolve: (msg: Record<string, unknown>) => void;
  reject: (err: Error) => void;
}

export interface ToolInfo {
  name: string;
  inputSchema?: { properties?: Record<string, unknown>; required?: string[] };
}

export class McpServer {
  readonly proc: ReturnType<typeof Bun.spawn>;
  readonly pid: number;
  stderrText = "";
  readonly notifications: Record<string, unknown>[] = [];
  private nextId = 1;
  private readonly pending = new Map<number, Pending>();
  private tools: ToolInfo[] | undefined;
  private exited = false;

  private constructor(command: string[], env: Record<string, string>, cwd: string) {
    this.proc = Bun.spawn(command, { cwd, env, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
    this.pid = this.proc.pid;
    void this.pumpStdout();
    void this.pumpStderr();
    void this.proc.exited.then(() => {
      this.exited = true;
      for (const p of this.pending.values()) {
        p.reject(new Error(`MCP server exited; stderr tail:\n${this.stderrText.slice(-3000)}`));
      }
      this.pending.clear();
    });
  }

  /** Start `bun <src>/index.ts --mcp` (the compiled-binary branch, §8.1 9b) unless `command` is given. */
  static async start(opts: {
    env: Record<string, string>;
    cwd: string;
    command?: string[];
  }): Promise<McpServer> {
    const server = new McpServer(
      opts.command ?? [process.execPath, "--no-env-file", SERVER_ENTRY, "--mcp"],
      opts.env,
      opts.cwd
    );
    await server.request("initialize", {
      protocolVersion: "2025-06-18",
      capabilities: {},
      clientInfo: { name: "claudish-contract-tests", version: "0.0.0" },
    });
    server.notify("notifications/initialized", {});
    return server;
  }

  private async pumpStdout(): Promise<void> {
    const stdout = this.proc.stdout as ReadableStream<Uint8Array>;
    const reader = stdout.getReader();
    const decoder = new TextDecoder();
    let buffer = "";
    for (;;) {
      const { value, done } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });
      for (let at = buffer.indexOf("\n"); at >= 0; at = buffer.indexOf("\n")) {
        const line = buffer.slice(0, at).trim();
        buffer = buffer.slice(at + 1);
        if (line) this.onMessage(line);
      }
    }
  }

  private async pumpStderr(): Promise<void> {
    const stderr = this.proc.stderr as ReadableStream<Uint8Array>;
    const reader = stderr.getReader();
    const decoder = new TextDecoder();
    for (;;) {
      const { value, done } = await reader.read();
      if (done) break;
      this.stderrText = (this.stderrText + decoder.decode(value, { stream: true })).slice(-50_000);
    }
  }

  private onMessage(line: string): void {
    let msg: Record<string, unknown>;
    try {
      msg = JSON.parse(line) as Record<string, unknown>;
    } catch {
      return; // not protocol traffic
    }
    const id = msg.id;
    if (typeof id === "number" && ("result" in msg || "error" in msg) && this.pending.has(id)) {
      const p = this.pending.get(id) as Pending;
      this.pending.delete(id);
      p.resolve(msg);
      return;
    }
    if ("method" in msg && id !== undefined) {
      // A server-to-client request (ping, roots/list, ...): answer with an empty result.
      this.write({ jsonrpc: "2.0", id, result: {} });
      return;
    }
    this.notifications.push(msg);
  }

  private write(msg: unknown): void {
    const sink = this.proc.stdin as { write(s: string): unknown; flush?(): unknown };
    sink.write(`${JSON.stringify(msg)}\n`);
    sink.flush?.();
  }

  notify(method: string, params: unknown): void {
    this.write({ jsonrpc: "2.0", method, params });
  }

  request(method: string, params: unknown, timeoutMs = 20_000): Promise<Record<string, unknown>> {
    if (this.exited)
      return Promise.reject(
        new Error(`MCP server already exited; stderr:\n${this.stderrText.slice(-3000)}`)
      );
    const id = this.nextId++;
    return new Promise((resolve, reject) => {
      const timer = setTimeout(() => {
        this.pending.delete(id);
        reject(
          new Error(
            `MCP ${method} timed out after ${timeoutMs} ms; stderr tail:\n${this.stderrText.slice(-3000)}`
          )
        );
      }, timeoutMs);
      this.pending.set(id, {
        resolve: (msg) => {
          clearTimeout(timer);
          resolve(msg);
        },
        reject: (err) => {
          clearTimeout(timer);
          reject(err);
        },
      });
      this.write({ jsonrpc: "2.0", id, method, params });
    });
  }

  async listTools(): Promise<ToolInfo[]> {
    if (!this.tools) {
      const msg = await this.request("tools/list", {});
      this.tools = ((msg.result as { tools?: ToolInfo[] } | undefined)?.tools ?? []) as ToolInfo[];
    }
    return this.tools;
  }

  async callTool(
    name: string,
    args: Record<string, unknown>,
    meta?: Record<string, unknown>
  ): Promise<ToolResult> {
    const params: Record<string, unknown> = { name, arguments: args };
    if (meta) params._meta = meta;
    const msg = await this.request("tools/call", params);
    if (msg.error) {
      const text = String(
        (msg.error as { message?: unknown }).message ?? JSON.stringify(msg.error)
      );
      return { isError: true, text, json: undefined, raw: msg };
    }
    const result = (msg.result ?? {}) as {
      content?: Array<{ type?: string; text?: string }>;
      isError?: boolean;
    };
    const text = (result.content ?? [])
      .map((c) => (typeof c.text === "string" ? c.text : ""))
      .join("\n");
    let json: Record<string, unknown> | undefined;
    try {
      const parsed: unknown = JSON.parse(text);
      json = parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : undefined;
    } catch {
      json = undefined;
    }
    return { isError: Boolean(result.isError), text, json, raw: msg };
  }

  /**
   * Close the server's stdin, which shuts it down (records ended, panes reaped, exit 0).
   * SIGKILL only if it has not exited within `graceMs`; the pane watchers clean up then.
   */
  async close(graceMs = 15_000): Promise<void> {
    if (!this.exited) {
      try {
        (this.proc.stdin as { end?(): unknown }).end?.();
      } catch {
        // already closed
      }
      const ended = await Promise.race([
        this.proc.exited.then(() => true),
        Bun.sleep(graceMs).then(() => false),
      ]);
      if (!ended) {
        this.proc.kill("SIGKILL");
        await this.proc.exited;
      }
    }
  }
}

// ---------------------------------------------------------------------------------------------
// Tool adapters. INFERRED: argument and result field names of the claudish tools are not in the
// contract. Tool NAMES (create_session, send_input, get_session, get_output, get_diagnostics,
// cancel_session, list_sessions, team) and `timeout_seconds`, `session_id`, `monitor_record`
// come from the design text. Where a name could vary, the adapter reads the tool's own
// inputSchema from tools/list instead of guessing.
// ---------------------------------------------------------------------------------------------

async function pickArgKey(server: McpServer, tool: string, preferred: string[]): Promise<string> {
  const info = (await server.listTools()).find((t) => t.name === tool);
  const props = Object.keys(info?.inputSchema?.properties ?? {});
  return preferred.find((k) => props.includes(k)) ?? (preferred[0] as string);
}

/** Find a string field anywhere in a JSON value, depth-first, by key. */
export function findField(value: unknown, key: string, depth = 0): unknown {
  if (!value || typeof value !== "object" || depth > 6) return undefined;
  const obj = value as Record<string, unknown>;
  if (key in obj) return obj[key];
  for (const child of Object.values(obj)) {
    const hit = findField(child, key, depth + 1);
    if (hit !== undefined) return hit;
  }
  return undefined;
}

export interface CreateArgs {
  model?: string;
  prompt?: string;
  timeout_seconds?: number;
}

export async function createSession(
  server: McpServer,
  args: CreateArgs,
  toolUseId?: string
): Promise<{ sessionId: string | undefined; result: ToolResult }> {
  const callArgs: Record<string, unknown> = { model: args.model ?? FAKE_MODEL };
  if (args.prompt !== undefined) callArgs.prompt = args.prompt;
  if (args.timeout_seconds !== undefined) callArgs.timeout_seconds = args.timeout_seconds;
  const meta = toolUseId === undefined ? undefined : { [CLAUDE_CODE_TOOL_USE_META_KEY]: toolUseId };
  const result = await server.callTool("create_session", callArgs, meta);
  const fromJson = findField(result.json, "session_id") ?? findField(result.json, "sessionId");
  const fromText = /"?session_?[iI]d"?\s*[:=]\s*"?([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(
    result.text
  )?.[1];
  const sessionId = typeof fromJson === "string" ? fromJson : fromText;
  return { sessionId, result };
}

export async function sendInput(
  server: McpServer,
  sessionId: string,
  text: string
): Promise<ToolResult> {
  const key = await pickArgKey(server, "send_input", [
    "input",
    "message",
    "text",
    "content",
    "prompt",
  ]);
  return server.callTool("send_input", { session_id: sessionId, [key]: text });
}

export function sessionTool(
  server: McpServer,
  tool: string,
  sessionId: string
): Promise<ToolResult> {
  return server.callTool(tool, { session_id: sessionId });
}

/**
 * The session's status as `get_diagnostics` reports it, or undefined. The server exposes no
 * `get_session` tool (tools/list); `get_diagnostics` is the documented per-id tool, and its
 * result carries the channel `event` (10.4.0's `status` key, RB7) for a live session and for
 * one read back from disk.
 */
export async function sessionStatus(
  server: McpServer,
  sessionId: string
): Promise<string | undefined> {
  const r = await sessionTool(server, "get_diagnostics", sessionId);
  const event = findField(r.json, "event");
  if (typeof event === "string") return event;
  return /"event"\s*:\s*"([a-z_]+)"/.exec(r.text)?.[1];
}

export async function teamCall(
  server: McpServer,
  mode: string,
  args: { path: string; models?: string[]; input?: string }
): Promise<ToolResult> {
  const pathKey = await pickArgKey(server, "team", ["path", "session_path", "sessionPath"]);
  const call: Record<string, unknown> = { mode, [pathKey]: args.path };
  if (args.models) call.models = args.models;
  if (args.input !== undefined) {
    const inputKey = await pickArgKey(server, "team", ["input", "prompt", "task"]);
    call[inputKey] = args.input;
  }
  return server.callTool("team", call);
}