Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
import { appendFile, mkdir, readFile } from "node:fs/promises";
import { dirname } from "node:path";
import { constants, gunzipSync, gzipSync } from "node:zlib";
import type { ChatTurn, ToolUse } from "../agents/types.js";
import { redactDeep } from "../redact.js";
import { projectPaths } from "./paths.js";
/**
* The conversation as the drill-down shows it, kept in the project so it
* survives Claude Code deleting the transcript. One JSON line per turn, each
* append one more gzip member: the file is append-only and never rewritten. A
* turn first stored while the agent was still answering gets a later, fuller
* line for the same uuid.
*/
export interface StoredTurn {
/** The transcript's uuid for the user line; the key that makes appends idempotent. */
uuid: string;
/**
* The message's stable id (Story 8.5), so ids survive the transcript. Absent
* on turns stored before hashes existed; they are hashed from these fields.
*/
hash?: string;
at: string;
text: string;
replies: string[];
tools: ToolUse;
}
function isStoredTurn(value: unknown): value is StoredTurn {
if (value === null || typeof value !== "object") return false;
const turn = value as Partial<StoredTurn>;
return (
typeof turn.uuid === "string" &&
turn.uuid !== "" &&
typeof turn.at === "string" &&
typeof turn.text === "string" &&
Array.isArray(turn.replies) &&
turn.replies.every((reply) => typeof reply === "string") &&
turn.tools !== null &&
typeof turn.tools === "object"
);
}
/** How much of the answer a turn holds, to tell a finished turn from a snapshot of it. */
function answerSize(turn: Pick<StoredTurn, "replies" | "tools">): number {
return (
turn.replies.reduce((sum, reply) => sum + reply.length, 0) + JSON.stringify(turn.tools).length
);
}
/**
* Every turn stored for the session, in the order they were appended. A missing
* file is an empty store; a corrupted member ends the read at what parsed, so a
* damaged tail never hides the turns before it.
*/
export async function readConversationStore(
root: string,
sessionId: string,
): Promise<StoredTurn[]> {
let text: string;
try {
// A process killed mid-append leaves a partial last member; `Z_SYNC_FLUSH`
// still returns every complete record before it instead of an empty store.
text = gunzipSync(await readFile(projectPaths(root).conversation(sessionId)), {
finishFlush: constants.Z_SYNC_FLUSH,
}).toString("utf8");
} catch {
return [];
}
/** Later records for one uuid add a stable id or a fuller answer without rewriting the turn. */
const byUuid = new Map<string, StoredTurn>();
const order: string[] = [];
for (const line of text.split("\n")) {
if (line.trim() === "") continue;
let value: unknown;
try {
value = JSON.parse(line);
} catch {
continue;
}
if (!isStoredTurn(value)) continue;
const prev = byUuid.get(value.uuid);
if (!prev) {
byUuid.set(value.uuid, value);
order.push(value.uuid);
continue;
}
const fuller = answerSize(value) > answerSize(prev) ? value : prev;
const hash = prev.hash ?? value.hash;
byUuid.set(value.uuid, {
...prev,
...(hash === undefined ? {} : { hash }),
replies: fuller.replies,
tools: fuller.tools,
});
}
return order.map((uuid) => byUuid.get(uuid) as StoredTurn);
}
/**
* Appends the turns the store does not hold yet, and the ones whose answer has
* grown since they were stored, redacted, and returns how many were written. A
* build runs while the agent is still answering, so the first copy of a turn is
* often a snapshot with no replies. Turns without a transcript uuid cannot be
* recognised again, so they are left to the transcript; a build that has a
* transcript keeps showing them. Never rewrites an existing line.
*/
export async function appendConversationTurns(
root: string,
sessionId: string,
turns: ChatTurn[],
): Promise<number> {
const stored = new Map(
(await readConversationStore(root, sessionId)).map((turn) => [turn.uuid, turn]),
);
const seen = new Set<string>();
const fresh: StoredTurn[] = [];
for (const turn of turns) {
if (turn.uuid === undefined || seen.has(turn.uuid)) continue;
seen.add(turn.uuid);
const held = stored.get(turn.uuid);
if (held && answerSize(turn) <= answerSize(held)) continue;
fresh.push({
uuid: turn.uuid,
...(turn.hash === undefined ? {} : { hash: turn.hash }),
at: turn.at,
text: turn.text,
replies: turn.replies,
tools: turn.tools,
});
}
if (fresh.length === 0) return 0;
// The store outlives the transcript and may be committed by mistake, so it
// gets the same secret net as the page, not the raw text. Compared again after
// it: a turn with a secret is longer raw than stored, and must not append on
// every build.
const value = redactDeep(fresh).value.filter((turn) => {
const held = stored.get(turn.uuid);
return !held || answerSize(turn) > answerSize(held);
});
if (value.length === 0) return 0;
const chunk = `${value.map((turn) => JSON.stringify(turn)).join("\n")}\n`;
const file = projectPaths(root).conversation(sessionId);
await mkdir(dirname(file), { recursive: true });
await appendFile(file, gzipSync(Buffer.from(chunk, "utf8")));
return value.length;
}
/**
* Adds the stable id to turns stored before Story 8.5, as a later line for the
* same uuid: the file stays append-only and reading prefers the line with a
* hash. Without this, deleting the transcript would change every id and show
* recorded messages as unrecorded.
*/
export async function appendConversationHashes(
root: string,
sessionId: string,
hashes: ReadonlyMap<string, string>,
): Promise<number> {
if (hashes.size === 0) return 0;
const stored = await readConversationStore(root, sessionId);
const fresh = stored
.filter((turn) => turn.hash === undefined && hashes.has(turn.uuid))
.map((turn) => ({ ...turn, hash: hashes.get(turn.uuid) as string }));
if (fresh.length === 0) return 0;
const chunk = `${fresh.map((turn) => JSON.stringify(turn)).join("\n")}\n`;
const file = projectPaths(root).conversation(sessionId);
await mkdir(dirname(file), { recursive: true });
await appendFile(file, gzipSync(Buffer.from(chunk, "utf8")));
return fresh.length;
}