Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

15.7 KB
Raw Blame
import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { beforeEach, describe, expect, it } from "vitest";
import type { ChatTurn } from "../src/agents/types.js";
import {
  agentRecord,
  backfillTail,
  catchUpPrompt,
  headlessEnv,
  resultText,
  withoutNulls,
  writableAnswer,
} from "../src/commands/backfill.js";
import { init } from "../src/commands/init.js";
import { sessionWrite } from "../src/commands/session.js";
import { messageHash } from "../src/messages.js";
import type { Session } from "../src/schema/session.js";
import { projectPaths } from "../src/store/paths.js";
import { loadSession } from "../src/store/stores.js";
import { envFor, fakeIo, T0, tempDir } from "./helpers.js";

let dir: string;
let root: string;

beforeEach(async () => {
  dir = await tempDir();
  root = join(dir, "proj");
  await mkdir(root);
});

/** A transcript for session s1, under the fake Claude home. */
async function transcript(lines: unknown[]): Promise<void> {
  const folder = join(envFor(dir).CLAUDE_CONFIG_DIR ?? "", "projects", "proj");
  await mkdir(folder, { recursive: true });
  await writeFile(join(folder, "s1.jsonl"), `${lines.map((l) => JSON.stringify(l)).join("\n")}\n`);
}

const typed = (text: string, minute: number) => ({
  type: "user",
  timestamp: `2026-10-23T10:0${minute}:00.000Z`,
  message: { role: "user", content: text },
});

/** Puts a fake `claude` first on PATH and returns the env that finds it. */
async function fakeClaude(script: string, path: string): Promise<NodeJS.ProcessEnv> {
  const bin = join(path, "bin");
  await mkdir(bin, { recursive: true });
  const file = join(bin, "claude");
  await writeFile(file, `#!/usr/bin/env node\n${script}\n`);
  await chmod(file, 0o755);
  return { ...envFor(dir), PATH: `${bin}:${process.env.PATH ?? ""}` };
}

/** Reads stdin, keeps the prompt for inspection and prints a result envelope. */
function printing(result: string): string {
  return `
process.stdin.setEncoding("utf8");
let input = "";
process.stdin.on("data", (chunk) => { input += chunk; });
process.stdin.on("end", async () => {
  const fs = await import("node:fs");
  fs.writeFileSync(${JSON.stringify(join(dir, "prompt.txt"))}, input);
  fs.writeFileSync(${JSON.stringify(join(dir, "argv.json"))}, JSON.stringify(process.argv.slice(2)));
  process.stdout.write(JSON.stringify({ type: "result", subtype: "success", result: ${JSON.stringify(result)} }));
});`;
}

const GOOD = JSON.stringify({
  status: { goal: "Ship 4.7", done: [], pending: [], next: "release" },
  nodes: [
    { id: "topic", kind: "phase", parent: null, title: "Catch-up" },
    { id: "m2", kind: "message", parent: "topic", title: "Second", summary: "Recorded it" },
  ],
});

async function initialized(env: NodeJS.ProcessEnv): Promise<void> {
  await init(root, { name: "proj", retention: "keep", language: "auto" }, fakeIo(env));
}

const record = async (): Promise<Session | undefined> => {
  const loaded = await loadSession(root, "s1");
  return loaded.found && loaded.ok ? loaded.data : undefined;
};

describe("catchUpPrompt", () => {
  const turn: ChatTurn = {
    id: "m7",
    at: T0,
    text: "x".repeat(2000),
    replies: [],
    tools: { commands: 0, files: [], other: 0 },
  };

  it("includes the rules, a cut message and an empty record", () => {
    const prompt = catchUpPrompt([turn], undefined, "s1", "Turkish");
    expect(prompt).toContain("The record has no nodes yet.");
    expect(prompt).toContain("titles and text in Turkish");
    expect(prompt).toContain("(no written reply)");
    expect(prompt).toContain("only options someone actually named in the conversation");
    expect(prompt).toContain("A proposal the user has not answered is not a decision.");
    expect(prompt).toContain("…");
    expect(prompt).toContain('{"sessionId": "s1", "nodes": [...]');
  });

  it("asks for a message summary only when the setting says so", () => {
    const off = catchUpPrompt([turn], undefined, "s1", "auto");
    expect(off).not.toContain("summary: one or two sentences");
    const on = catchUpPrompt([turn], undefined, "s1", "auto", true);
    expect(on).toContain("summary: one or two sentences");
  });

  it("lists the existing topics, the replies and the tool counts", () => {
    const prompt = catchUpPrompt(
      [{ ...turn, replies: ["ok"], tools: { commands: 1, files: ["a.ts"], other: 2 } }],
      {
        schema: 1,
        sessionId: "s1",
        agent: "claude-code",
        title: "",
        startedAt: T0,
        updatedAt: T0,
        status: { goal: "", done: [], pending: [], next: "" },
        nodes: [{ id: "topic", parent: null, kind: "phase", title: "Topic" }],
      },
      "s1",
      "auto",
    );
    expect(prompt).toContain("parent=null: Topic");
    expect(prompt).toContain("AGENT: ok");
    expect(prompt).toContain("1 command(s), 1 file(s) edited, 2 other tool call(s)");
    expect(prompt).toContain("the conversation's language");
  });

  it("keeps the side prompt in line with the skill (Story 12.1)", () => {
    const prompt = catchUpPrompt([turn], undefined, "s1", "auto");
    expect(prompt).toContain("never a topic or phase node");
    expect(prompt).toContain("branch summary");
    expect(prompt).toContain("only for technical choices with a reason");
    expect(prompt).toContain("decidedBy");
    // A closing pass once left a session untitled, so the map showed its bare id.
    expect(prompt).toContain("when the record's title is empty, send one");
    // The periodic mixed run writes messages and user decisions only.
    const mixed = catchUpPrompt([turn], undefined, "s1", "auto", false, "mixed");
    expect(mixed).toContain("periodic background run");
    expect(mixed).toContain("Do not send status, branch summaries or agentDecisions");
    expect(mixed).toContain("and the session title when it is empty");
    const side = catchUpPrompt([turn], undefined, "s1", "auto", false, "side");
    expect(side).not.toContain("periodic background run");
    const agent = catchUpPrompt([turn], undefined, "s1", "auto", false, "agent");
    expect(agent).not.toContain("periodic background run");
  });
});

describe("headless output", () => {
  it("reads the result text out of the envelope", () => {
    expect(resultText(JSON.stringify({ result: "x" }))).toBe("x");
    expect(() => resultText("nope")).toThrow(/valid JSON/);
    expect(() => resultText("{}")).toThrow(/no result text/);
  });

  it("accepts an object, with or without a code fence, and rejects the rest", () => {
    expect(agentRecord('{"a":1}')).toEqual({ a: 1 });
    expect(agentRecord('```json\n{"a":1}\n```')).toEqual({ a: 1 });
    expect(() => agentRecord("not json")).toThrow(/JSON record/);
    expect(() => agentRecord("[1]")).toThrow(/JSON object/);
  });

  it("drops the null notes a small model writes, keeping a root's null parent", () => {
    expect(
      withoutNulls({
        status: null,
        nodes: [{ id: "m1", parent: null, why: null, decidedBy: null, title: "t" }, 3],
      }),
    ).toEqual({ nodes: [{ id: "m1", parent: null, title: "t" }, 3] });
    expect(withoutNulls({ nodes: "x" })).toEqual({ nodes: "x" });
  });

  it("turns capture off in the headless run", () => {
    expect(headlessEnv({ PATH: "/bin" })).toMatchObject({
      PATH: "/bin",
      COGIT_DISABLE: "1",
    });
  });
});

describe("backfill --tail", () => {
  it("records the missing messages through session write and rebuilds the map", async () => {
    const env = await fakeClaude(printing(GOOD), dir);
    await initialized(env);
    await transcript([typed("first", 1), typed("second", 2)]);
    await sessionWrite({ dir: root }, fakeIo(env), async () =>
      JSON.stringify({ sessionId: "s1", nodes: [{ id: "m1", kind: "message", title: "First" }] }),
    );

    const io = fakeIo(env);
    await backfillTail(root, "s1", io);
    const saved = await record();
    const first = messageHash("s1", { at: "2026-10-23T10:01:00.000Z", text: "first" });
    const second = messageHash("s1", { at: "2026-10-23T10:02:00.000Z", text: "second" });
    expect(saved?.nodes.map((n) => n.id)).toEqual(expect.arrayContaining([first, "topic", second]));
    // The time comes from the transcript, not from the agent.
    expect(saved?.nodes.find((n) => n.id === second)).toMatchObject({
      at: "2026-10-23T10:02:00.000Z",
      summary: "Recorded it",
    });
    expect(io.lines).toContain("Saved session s1 (3 nodes)");
    // A backfill is a side run: the Stop hook counts its writes separately (12.1).
    expect(saved?.lastRecordedBy).toBe("side");
    // The side model setting names the model the headless run uses.
    expect(JSON.parse(await readFile(join(dir, "argv.json"), "utf8"))).toEqual(
      expect.arrayContaining(["--model", "haiku"]),
    );

    const prompt = await readFile(join(dir, "prompt.txt"), "utf8");
    expect(prompt).toContain("USER: second");
    expect(prompt).toContain('"sessionId": "s1"');
    expect(prompt).toContain(`- ${first} (message) parent=null: First`);
    expect(prompt).toContain("the conversation's language");
  });

  it("keeps the record when the answer's status is null and its summary is an object", async () => {
    const answer = JSON.stringify({
      status: { goal: "g", done: [], pending: [], next: null },
      nodes: [
        {
          id: "m2",
          kind: "message",
          parent: null,
          title: "Second",
          summary: { text: "Recorded it" },
        },
      ],
    });
    const env = await fakeClaude(printing(answer), dir);
    await initialized(env);
    await transcript([typed("first", 1), typed("second", 2)]);
    await sessionWrite({ dir: root }, fakeIo(env), async () =>
      JSON.stringify({ sessionId: "s1", nodes: [{ id: "m1", kind: "message", title: "First" }] }),
    );
    const io = fakeIo(env);
    await backfillTail(root, "s1", io);
    const saved = await record();
    const second = messageHash("s1", { at: "2026-10-23T10:02:00.000Z", text: "second" });
    // The node keeps its text and the null's absence takes the schema default.
    expect(saved?.nodes.find((n) => n.id === second)).toMatchObject({ summary: "Recorded it" });
    expect(saved?.status).toMatchObject({ goal: "g", next: "" });
    expect(io.warnings.some((w) => w.includes("malformed"))).toBe(false);
  });

  it("does nothing when there is no transcript or nothing missing", async () => {
    const env = envFor(dir);
    await initialized(env);
    const io = fakeIo(env);
    await backfillTail(root, "s1", io);
    expect(io.lines).toEqual(["session s1 has nothing left to record"]);

    await transcript([typed("first", 1)]);
    await sessionWrite({ dir: root }, fakeIo(env), async () =>
      JSON.stringify({ sessionId: "s1", nodes: [{ id: "m1", kind: "message", title: "First" }] }),
    );
    const again = fakeIo(env);
    await backfillTail(root, "s1", again);
    expect(again.lines).toEqual(["session s1 has nothing left to record"]);
  });

  it("exits quietly when another catch-up holds the session lock", async () => {
    const env = envFor(dir);
    await initialized(env);
    await transcript([typed("first", 1)]);
    const lock = projectPaths(root).lock("session-s1");
    await mkdir(lock, { recursive: true });
    await writeFile(join(lock, "owner"), String(process.pid));

    const io = fakeIo(env);
    await backfillTail(root, "s1", io);
    expect(io.lines).toEqual(["the side model is already recording s1"]);
    expect(await record()).toBeUndefined();
  });

  it("rejects an answer that is not a JSON record and leaves the record alone", async () => {
    const env = await fakeClaude(printing("not json"), dir);
    await initialized(env);
    await transcript([typed("first", 1)]);
    await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow(/JSON record/);
    expect(await record()).toBeUndefined();
  });

  it("reports a failed headless run with its stderr and keeps the record", async () => {
    const env = await fakeClaude('process.stderr.write("boom"); process.exit(3);', dir);
    await initialized(env);
    await transcript([typed("first", 1)]);
    await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow(
      /claude exited with 3: boom/,
    );
    expect(await record()).toBeUndefined();
  });

  it("stops a headless run that outlives the time limit and says so", async () => {
    const env = {
      ...(await fakeClaude("setTimeout(() => {}, 60_000);", dir)),
      COGIT_CLAUDE_TIMEOUT_MS: "300",
    };
    await initialized(env);
    await transcript([typed("first", 1)]);
    await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow(
      /claude did not answer within 0 s/,
    );
    expect(await record()).toBeUndefined();
  });

  it("reports a missing claude binary", async () => {
    const empty = join(dir, "empty");
    await mkdir(empty);
    const env = { ...envFor(dir), PATH: empty };
    await initialized(env);
    await transcript([typed("first", 1)]);
    await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow(/could not run claude/);
  });

  it("refuses an uninitialized or unreadable project", async () => {
    const env = envFor(dir);
    await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow(/not initialized/);
    await mkdir(join(root, ".cogit"), { recursive: true });
    await writeFile(join(root, ".cogit", "project.json"), "{nope");
    await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow(/invalid JSON/);
  });

  it("propagates a lock that cannot be created", async () => {
    const env = envFor(dir);
    await initialized(env);
    await transcript([typed("first", 1)]);
    await rm(projectPaths(root).locks, { recursive: true, force: true });
    await writeFile(projectPaths(root).locks, "not a directory");
    await expect(backfillTail(root, "s1", fakeIo(env))).rejects.toThrow();
  });
});

describe("writableAnswer", () => {
  it("keeps a node whose only fault is an optional field, without that field", () => {
    const { payload, dropped } = writableAnswer(
      {
        nodes: [
          {
            id: "m1",
            kind: "message",
            title: "Add the CSV parser",
            summary: "Plain JavaScript, no library.",
            work: ["x".repeat(400)],
            alternatives: [{ why: "no option named" }],
          },
          { id: "m2", kind: "message", title: "" },
        ],
      },
      "side",
    );
    expect(payload.nodes).toEqual([
      {
        id: "m1",
        kind: "message",
        title: "Add the CSV parser",
        summary: "Plain JavaScript, no library.",
      },
    ]);
    // Two bad fields of m1, and m2 whose title is missing.
    expect(dropped).toBe(3);
  });

  it("leaves a branch summary to the agent in mixed mode", () => {
    const branch = { title: "T", asked: "A", outcome: "O" };
    const { payload, dropped } = writableAnswer(
      { nodes: [{ id: "m1", kind: "message", title: "Start", branch }] },
      "mixed",
    );
    // The summary stays the agent's; the message itself is still recorded.
    expect(payload.nodes).toEqual([{ id: "m1", kind: "message", title: "Start" }]);
    expect(dropped).toBe(1);
  });

  it("in mixed mode leaves out the agent's fields, not the message", () => {
    const { payload, dropped } = writableAnswer(
      {
        status: { goal: "kept only for a sole owner" },
        nodes: [
          {
            id: "m1",
            kind: "message",
            title: "Start the parser",
            branch: { title: "Parser", asked: "a", outcome: "b" },
            agentDecisions: [{ title: "Plain JS" }],
          },
        ],
      },
      "mixed",
    );
    expect(payload).toEqual({ nodes: [{ id: "m1", kind: "message", title: "Start the parser" }] });
    expect(dropped).toBe(2);
  });

  it("still drops a node it cannot read at all", () => {
    expect(writableAnswer({ nodes: ["not a node", null] }, "side")).toEqual({
      payload: { nodes: [] },
      dropped: 2,
    });
  });
});