Skip to content

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

8.1 KB
Raw Blame
/**
 * The human witness (hook-system architecture §3.2, §7.5, §19 H2): a prompt a human
 * typed into the interactive launcher's session, matched by PROVENANCE. Every record is
 * a real capture (phase-2 transcripts, Claude Code 2.1.290 / 2.1.291).
 *
 * The negative cases are the ones that bit: the captured background notifications are
 * non-meta, main-chain user records with plain-text content, so a shape-only witness
 * matched them and a re-wake read as a new human turn.
 */

import { afterEach, describe, expect, test } from "bun:test";
import { appendFileSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { type Rec, transcriptRecords } from "./test-helpers/transcript-fixtures.js";
import {
  TranscriptFollower,
  type Witness,
  applyRecord,
  initialFollowerState,
  isHumanPrompt,
  lastHumanPromptOffset,
  openTurnState,
  turnView,
} from "./transcript-follower.js";

const TOOLS = transcriptRecords("tools-session");
const LOCAL = transcriptRecords("local-commands");
/** 1-based fixture line numbers, as the architecture cites them. */
const line = (n: number): Rec => TOOLS[n - 1] as Rec;

const HUMAN: Witness = { kind: "human" };

const dirs: string[] = [];
afterEach(() => {
  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
});

function tmpTranscript(records: Rec[]): string {
  const dir = mkdtempSync(join(tmpdir(), "human-witness-"));
  dirs.push(dir);
  const path = join(dir, "s.jsonl");
  writeFileSync(path, records.map((r) => `${JSON.stringify(r)}\n`).join(""));
  return path;
}

/** One human-witness turn at offset 0, fed `records` in order. */
function feed(records: Rec[]) {
  const state = initialFollowerState((p) => p);
  openTurnState(state, { index: 1, offset: 0, witness: HUMAN });
  let offset = 1;
  for (const r of records) {
    applyRecord(state, r, offset);
    offset += 100;
  }
  return turnView(state.turns[0] as never);
}

describe("isHumanPrompt — provenance, not shape", () => {
  test("a typed prompt (origin.kind human) matches", () => {
    const r = line(5);
    expect(r.origin?.kind).toBe("human");
    expect(isHumanPrompt(r)).toBe(true);
  });

  test("the captured task notifications at tools-session.jsonl:54 and :74 never match", () => {
    for (const n of [54, 74]) {
      const r = line(n);
      // the shape a text-only rule would accept: main chain, not meta, plain content
      expect(r.type).toBe("user");
      expect(r.isSidechain).toBe(false);
      expect(r.isMeta).toBeUndefined();
      expect(typeof r.message.content).toBe("string");
      expect(isHumanPrompt(r)).toBe(false);
    }
  });

  test("a notification WITHOUT its origin field is still refused by its <task-notification> text", () => {
    const r = structuredClone(line(54));
    delete r.origin;
    expect(isHumanPrompt(r)).toBe(false);
  });

  test("an interrupt marker never matches, even dressed as human", () => {
    const interrupts = TOOLS.filter(
      (r) =>
        r.type === "user" &&
        typeof r.message?.content !== "string" &&
        JSON.stringify(r.message?.content).includes("[Request interrupted by user")
    );
    expect(interrupts.length).toBeGreaterThan(0);
    for (const r of interrupts) {
      expect(isHumanPrompt(r)).toBe(false);
      expect(isHumanPrompt({ ...r, origin: { kind: "human" } })).toBe(false);
    }
  });

  test("a compact summary, an isMeta record and a tool_result never match", () => {
    const summary = TOOLS.find((r) => r.isCompactSummary);
    const meta = LOCAL.find((r) => r.type === "user" && r.isMeta);
    const toolResult = TOOLS.find(
      (r) =>
        r.type === "user" &&
        Array.isArray(r.message?.content) &&
        r.message.content.some((b: Rec) => b.type === "tool_result")
    );
    for (const r of [summary, meta, toolResult]) {
      expect(r).toBeDefined();
      expect(isHumanPrompt(r as Rec)).toBe(false);
    }
  });

  test("a local command's records (/model, /compact typed line aside) never match", () => {
    const commands = LOCAL.filter(
      (r) =>
        r.type === "user" &&
        /^\s*<(local-command-caveat|command-name|local-command-stdout)>/.test(
          typeof r.message?.content === "string" ? r.message.content : ""
        )
    );
    expect(commands.length).toBeGreaterThan(0);
    for (const r of commands) expect(isHumanPrompt(r)).toBe(false);
  });

  test("a sidechain (subagent) user record never matches", () => {
    expect(isHumanPrompt({ ...line(5), isSidechain: true })).toBe(false);
  });

  test("a prompt with an origin naming anything but human is refused", () => {
    expect(isHumanPrompt({ ...line(5), origin: { kind: "hook" } })).toBe(false);
  });
});

describe("a human-witness turn", () => {
  test("is accepted by the typed prompt and folds its answer", () => {
    const answer = line(29);
    const v = feed([line(5), answer, line(30)]);
    expect(v.acceptedAt).toBe(line(5).timestamp);
    expect(v.lastAssistant).not.toBeNull();
    expect(v.unwitnessedChatOffset).toBeNull();
  });

  test("a notification and the model's reply to it do NOT open it: they are recorded as unwitnessed chat", () => {
    const notification = line(54);
    const reply = line(29);
    const v = feed([notification, reply]);
    expect(v.acceptedAt).toBeNull();
    expect(v.lastAssistant).toBeNull();
    // the offset of the notification: the first record of the re-wake
    expect(v.unwitnessedChatOffset).toBe(1);
  });

  test("an assistant record alone (a continuation with no prompt) is unwitnessed chat", () => {
    const v = feed([line(29)]);
    expect(v.acceptedAt).toBeNull();
    expect(v.unwitnessedChatOffset).toBe(1);
  });

  test("state records before the prompt are not chat", () => {
    const v = feed([line(1), line(2), line(5)]);
    expect(v.acceptedAt).not.toBeNull();
    expect(v.unwitnessedChatOffset).toBeNull();
  });
});

describe("TranscriptFollower.rewindTo and lastHumanPromptOffset", () => {
  test("rewindTo re-reads a turn from its own offset", () => {
    const path = tmpTranscript([line(5), line(29), line(30)]);
    const f = new TranscriptFollower(path, join(path, "..", "subagents"));
    f.openTurn({ index: 1, offset: 0, witness: HUMAN });
    f.poll();
    expect(f.view().current?.acceptedAt).not.toBeNull();
    // the next turn opens at the end, and a notification + reply arrive
    f.openTurn({ index: 2, offset: f.size(), witness: HUMAN });
    appendFileSync(path, `${JSON.stringify(line(54))}\n${JSON.stringify(line(29))}\n`);
    f.poll();
    expect(f.view().current?.acceptedAt).toBeNull();
    expect(f.view().current?.unwitnessedChatOffset).not.toBeNull();
    // re-open turn 1: its prompt, its first answer AND the continuation are its records
    f.rewindTo({ index: 1, offset: 0, witness: HUMAN });
    const v = f.view().current;
    expect(v?.index).toBe(1);
    expect(v?.acceptedAt).toBe(line(5).timestamp);
    expect(v?.wakingAfterLast).toBe(false);
    expect(v?.assistantText.length).toBe(2);
  });

  test("lastHumanPromptOffset finds the line of the last typed prompt, skipping notifications", () => {
    const records = [line(1), line(5), line(29), line(54), line(29)];
    const path = tmpTranscript(records);
    const lengths = records.map((r) => Buffer.byteLength(`${JSON.stringify(r)}\n`));
    expect(lastHumanPromptOffset(path)).toBe((lengths[0] as number) + 0);
    const second: Rec = { ...line(5), message: { ...line(5).message, content: "second prompt" } };
    appendFileSync(path, `${JSON.stringify(second)}\n`);
    const total = lengths.reduce((a, b) => a + b, 0);
    expect(lastHumanPromptOffset(path)).toBe(total);
    // a turn opened there is accepted by that prompt alone
    const f = new TranscriptFollower(path, join(path, "..", "subagents"));
    f.rewindTo({ index: 1, offset: total, witness: HUMAN });
    expect(f.view().current?.acceptedAt).toBe(second.timestamp);
  });

  test("lastHumanPromptOffset is null for a transcript with no human prompt, and for none at all", () => {
    expect(lastHumanPromptOffset(tmpTranscript([line(1), line(54)]))).toBeNull();
    expect(lastHumanPromptOffset(join(tmpdir(), "no-such-transcript.jsonl"))).toBeNull();
  });
});