Skip to content

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

14.5 KB
Raw Blame
// packages/cli/src/mcp-session/session-records.contract.test.ts
/**
 * The record half that the 10.4.0 suites assume and pane sessions must now produce
 * (architecture §12.3, §20.1): `meta.json` keeps every 10.4.0 key with its 10.4.0 type,
 * `events.jsonl` has exactly one `assistant` line per main-chain message id (the magus
 * monitor's reply rule), a question or a permission dialog opens and closes one wait, a
 * re-wake keeps its turn, a queued send opens no wait between turns, and a cancelled team
 * slot's `status.json` row says why.
 *
 * A real claudish MCP server over stdio; every session is the pane fake in a real headless
 * magmux under the test's own CLAUDISH_PANE_ROOT. After each test no pane process or file
 * may remain.
 */
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { FAILURE_REASONS } from "../pane/index.js";
import {
  MAGMUX_AVAILABLE,
  McpServer,
  NO_MAGMUX_MESSAGE,
  createSession,
  paneOrphans,
  sendInput,
  serverEnv,
  sessionTool,
  teamCall,
} from "../test-helpers/contract-mcp.js";
import {
  type TempLayout,
  makeTempLayout,
  readJson,
  readWaitLines,
  waitFor,
  waitPairingViolations,
} from "../test-helpers/contract-records.js";
import { toMetaRecord } from "./session-manager.js";
import type { SessionInfo } from "./types.js";

const T_TEST = 40_000;
const BOOT_MS = 15_000;

let layout: TempLayout;
let server: McpServer;

if (!MAGMUX_AVAILABLE) console.warn(NO_MAGMUX_MESSAGE);

const dirOf = (id: string) => join(layout.sessionsDir, id);

async function created(args: Parameters<typeof createSession>[1]): Promise<string> {
  const { sessionId, result } = await createSession(server, args);
  expect(result.isError).toBe(false);
  expect(typeof sessionId).toBe("string");
  return sessionId as string;
}

async function terminalMeta(id: string, timeoutMs = BOOT_MS): Promise<Record<string, unknown>> {
  return waitFor(
    () => {
      const meta = readJson(join(dirOf(id), "meta.json"));
      return meta && ["completed", "failed", "timeout", "cancelled"].includes(String(meta.status))
        ? meta
        : undefined;
    },
    { what: `a terminal meta.json for ${id}`, timeoutMs }
  );
}

async function rowOf(id: string): Promise<Record<string, unknown> | undefined> {
  const r = await server.callTool("list_sessions", { include_completed: true });
  const rows = (r.json?.sessions ?? []) as Array<Record<string, unknown>>;
  return rows.find((row) => row.session_id === id);
}

async function waitRow(
  id: string,
  pred: (row: Record<string, unknown>) => boolean,
  what: string
): Promise<Record<string, unknown>> {
  return waitFor(
    async () => {
      const row = await rowOf(id);
      return row && pred(row) ? row : undefined;
    },
    { what, timeoutMs: BOOT_MS, intervalMs: 50 }
  );
}

const isInt = (x: unknown) => Number.isInteger(x);
const isStr = (x: unknown) => typeof x === "string" && x.length > 0;
const isIso = (x: unknown) => isStr(x) && !Number.isNaN(Date.parse(String(x)));
const isNum = (x: unknown) => typeof x === "number";
const nullOr = (ok: (y: unknown) => boolean) => (x: unknown) => x === null || ok(x);
const any = () => true;

/** The 10.4.0 `meta.json` keys and their types, as the magus monitor reads them. */
const META_104: Record<string, (x: unknown) => boolean> = {
  sessionId: isStr,
  model: isStr,
  spawnModel: nullOr(isStr),
  status: (x) => ["completed", "failed", "cancelled", "timeout"].includes(String(x)),
  pid: nullOr(isInt),
  startedAt: isIso,
  completedAt: isIso,
  exitCode: nullOr(isInt),
  turnsCompleted: isInt,
  tokensUsed: isNum,
  elapsedSeconds: isNum,
  idleSeconds: any,
  costUsd: nullOr(isNum),
  toolCallCount: isInt,
  terminalReason: nullOr((x) => (FAILURE_REASONS as readonly unknown[]).includes(x)),
  claudeSessionId: isStr,
  transcriptPath: isStr,
};

function meta104Violations(meta: Record<string, unknown>): string[] {
  return Object.entries(META_104)
    .filter(([key, ok]) => !(key in meta) || !ok(meta[key]))
    .map(([key]) => `${key}=${JSON.stringify(meta[key])}`);
}

/** A copy of the monitor's reply rule: the distinct `message.id` of `type:"assistant"` lines. */
function monitorReplies(eventsText: string): Set<string> {
  const ids = new Set<string>();
  for (const line of eventsText.split("\n")) {
    if (!line.trim()) continue;
    try {
      const r = JSON.parse(line) as { type?: unknown; message?: { id?: unknown } };
      if (r.type === "assistant" && typeof r.message?.id === "string") ids.add(r.message.id);
    } catch {
      /* the monitor skips a line it cannot parse */
    }
  }
  return ids;
}

describe("EMPTY is a failure to the monitor (§20.1)", () => {
  test("toMetaRecord writes status failed and the FailureReason for an EMPTY session", () => {
    const info: SessionInfo = {
      sessionId: "e0000001",
      model: "m",
      spawnModel: null,
      provider: null,
      state: "EMPTY",
      shape: "one-shot",
      pane: "p",
      recent: null,
      panePid: 4242,
      startedAt: "2026-10-06T00:00:00.000Z",
      completedAt: "2026-10-06T00:00:05.000Z",
      exitCode: null,
      turnsCompleted: 1,
      tokensIn: 10,
      tokensOut: 2,
      costUsd: null,
      toolCalls: 0,
      lastActivityAt: null,
      elapsedSeconds: 5,
      idleSeconds: null,
      activity: null,
      reason: "empty_output",
      detail: "no answer",
      pendingInputs: 0,
      claudeSessionId: "3a4b5c6d-0000-4000-8000-000000000001",
      transcriptPath: "/x/y.jsonl",
      captureSource: "transcript",
      turnSource: "transcript",
      timeoutSeconds: 600,
    };
    const meta = toMetaRecord(info, "/cwd");
    expect(meta104Violations(meta)).toEqual([]);
    expect(meta).toMatchObject({
      status: "failed",
      terminalReason: "empty_output",
      state: "EMPTY",
      pid: 4242,
      tokensUsed: 12,
      toolCallCount: 0,
    });
    expect("toolCalls" in meta || "reason" in meta || "panePid" in meta).toBe(false);
  });
});

describe.skipIf(!MAGMUX_AVAILABLE)("live records", () => {
  beforeEach(async () => {
    layout = makeTempLayout("records");
    server = await McpServer.start({ env: serverEnv(layout), cwd: layout.cwd });
  });
  afterEach(async () => {
    await server.close();
    const report = await paneOrphans(layout);
    layout.cleanup();
    expect(report).toEqual({ processes: [], files: [] });
  }, 40_000);

  describe("meta.json keeps the 10.4.0 keys with their 10.4.0 types in every terminal state", () => {
    test(
      "completed",
      async () => {
        const meta = await terminalMeta(await created({ prompt: "say hello" }));
        expect(meta104Violations(meta)).toEqual([]);
        expect(meta).toMatchObject({
          status: "completed",
          terminalReason: null,
          turnsCompleted: 1,
        });
      },
      T_TEST
    );

    test(
      "failed: an API-error turn",
      async () => {
        const id = await created({ model: "fake-api_error", prompt: "say hello" });
        const meta = await terminalMeta(id);
        expect(meta104Violations(meta)).toEqual([]);
        expect(meta).toMatchObject({ status: "failed", terminalReason: "api_error" });
      },
      T_TEST
    );

    test(
      "failed: the child exited mid-turn, with its own exit code",
      async () => {
        const id = await created({ model: "fake-exit_mid_turn", prompt: "say hello" });
        const meta = await terminalMeta(id);
        expect(meta104Violations(meta)).toEqual([]);
        expect(meta).toMatchObject({
          status: "failed",
          terminalReason: "child_exited",
          exitCode: 3,
        });
      },
      T_TEST
    );

    test(
      "cancelled (claudish ended the pane: exitCode null)",
      async () => {
        const id = await created({ prompt: "never answer @@HANG@@" });
        await waitRow(id, (r) => r.state === "RUNNING", "running");
        await sessionTool(server, "cancel_session", id);
        const meta = await terminalMeta(id);
        expect(meta104Violations(meta)).toEqual([]);
        expect(meta).toMatchObject({
          status: "cancelled",
          terminalReason: "cancelled",
          exitCode: null,
        });
      },
      T_TEST
    );

    test(
      "timeout",
      async () => {
        const id = await created({ prompt: "never answer @@HANG@@", timeout_seconds: 4 });
        const meta = await terminalMeta(id, 20_000);
        expect(meta104Violations(meta)).toEqual([]);
        expect(meta).toMatchObject({ status: "timeout", terminalReason: "timeout" });
      },
      T_TEST
    );
  });

  test(
    "events.jsonl has exactly one assistant line per distinct main-chain message id of the transcript",
    async () => {
      const id = await created({ prompt: "use a tool @@TOOL@@" });
      await terminalMeta(id);
      const diag = await sessionTool(server, "get_diagnostics", id);
      const transcriptPath = String(diag.json?.transcriptPath);

      const transcriptIds = new Set<string>();
      for (const line of readFileSync(transcriptPath, "utf8").split("\n")) {
        if (!line.trim()) continue;
        const r = JSON.parse(line) as {
          type?: string;
          isSidechain?: boolean;
          message?: { id?: string };
        };
        if (r.type === "assistant" && !r.isSidechain && r.message?.id)
          transcriptIds.add(r.message.id);
      }
      const events = readFileSync(join(dirOf(id), "events.jsonl"), "utf8");
      const assistantLines = events
        .split("\n")
        .filter((l) => l.trim())
        .map((l) => JSON.parse(l) as { type?: string })
        .filter((r) => r.type === "assistant");

      expect(transcriptIds.size).toBeGreaterThanOrEqual(2); // the tool_use message and the answer
      expect([...monitorReplies(events)].sort()).toEqual([...transcriptIds].sort());
      expect(assistantLines).toHaveLength(transcriptIds.size);
    },
    T_TEST
  );

  test(
    "RB3 a question in a session opens one wait; send_input declines it and closes it to running",
    async () => {
      const id = await created({ model: "fake-ask_user_send", prompt: "ask me something" });
      const blocked = await waitRow(id, (r) => r.state === "AWAITING_INPUT", "the question");
      expect(blocked.activity).toBe("AskUserQuestion");
      const open = readWaitLines(dirOf(id)) ?? [];
      expect(open).toEqual([{ wait: "open", since: expect.any(String), turns: 0 }]);

      expect((await sendInput(server, id, "never mind, answer this")).json).toMatchObject({
        success: true,
      });
      const lines = await waitFor(
        () => {
          const l = readWaitLines(dirOf(id));
          return l && l.length >= 2 ? l : undefined;
        },
        { what: "the closed line", timeoutMs: BOOT_MS }
      );

      expect(lines[1]).toEqual({
        wait: "closed",
        since: lines[0].since,
        at: expect.any(String),
        to: "running",
      });
      expect(waitPairingViolations(lines, true)).toEqual([]);
      await sessionTool(server, "cancel_session", id);
    },
    T_TEST
  );

  test(
    "RB3 a permission dialog opens one wait (awaiting_permission); cancel closes it to cancelled",
    async () => {
      const id = await created({ model: "fake-permission", prompt: "edit something" });
      await waitRow(id, (r) => r.state === "AWAITING_PERMISSION", "the permission dialog");
      expect(readWaitLines(dirOf(id))).toEqual([
        { wait: "open", since: expect.any(String), turns: 0 },
      ]);

      await sessionTool(server, "cancel_session", id);
      await terminalMeta(id);
      const lines = readWaitLines(dirOf(id)) ?? [];

      expect(lines.map((l) => [l.wait, l.to])).toEqual([
        ["open", undefined],
        ["closed", "cancelled"],
      ]);
      expect(waitPairingViolations(lines, false)).toEqual([]);
    },
    T_TEST
  );

  test(
    "D23 a re-wake after the answer closes no wait early and adds no turn",
    async () => {
      const id = await created({});
      await waitFor(() => readWaitLines(dirOf(id))?.length === 1, {
        what: "boot ready",
        timeoutMs: BOOT_MS,
      });
      await sendInput(server, id, "answer, then wake again @@LATE@@");

      const row = await waitRow(
        id,
        (r) => r.state === "AWAITING_INPUT" && r.turns_completed === 1,
        "the re-woken turn to settle"
      );
      const lines = readWaitLines(dirOf(id)) ?? [];
      const output = await sessionTool(server, "get_output", id);

      expect(row.turns_completed).toBe(1);
      expect(lines.map((l) => [l.wait, l.turns ?? l.to])).toEqual([
        ["open", 0],
        ["closed", "running"],
        ["open", 1],
      ]);
      expect(String(output.json?.output)).toContain("LATE second message");
      await sessionTool(server, "cancel_session", id);
    },
    T_TEST
  );

  test(
    "a turn that settles with a send queued writes no wait line between the turns",
    async () => {
      const id = await created({});
      await waitFor(() => readWaitLines(dirOf(id))?.length === 1, {
        what: "boot ready",
        timeoutMs: BOOT_MS,
      });
      await sendInput(server, id, "answer, then linger @@LINGER@@");
      await waitRow(id, (r) => r.state === "RUNNING", "turn 1 running");
      expect((await sendInput(server, id, "second question")).json).toMatchObject({
        success: true,
      });

      await waitRow(
        id,
        (r) => r.state === "AWAITING_INPUT" && r.turns_completed === 2,
        "turn 2 to settle"
      );
      const lines = readWaitLines(dirOf(id)) ?? [];

      expect(lines.map((l) => [l.wait, l.turns ?? l.to])).toEqual([
        ["open", 0],
        ["closed", "running"],
        ["open", 2],
      ]);
      await sessionTool(server, "cancel_session", id);
    },
    T_TEST
  );

  test(
    "a cancelled team slot's status.json row carries error.reason cancelled",
    async () => {
      const teamDir = join(layout.cwd, "team-run");
      const run = await teamCall(server, "run", {
        path: teamDir,
        models: ["contract-fake-a"],
        input: "never answer @@HANG@@",
      });
      expect(run.isError).toBe(false);

      const cancel = await server.callTool("team", { mode: "cancel", path: teamDir });
      expect(cancel.isError).toBe(false);
      const row = await waitFor(
        () => {
          const status = readJson(join(teamDir, "status.json"));
          const models = (status?.models ?? {}) as Record<string, Record<string, unknown>>;
          const slot = Object.values(models)[0];
          return slot?.state === "CANCELLED" ? slot : undefined;
        },
        { what: "the CANCELLED row", timeoutMs: BOOT_MS }
      );

      expect((row.error as Record<string, unknown> | undefined)?.reason).toBe("cancelled");
    },
    T_TEST
  );
});