Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* Reading a Claude Code transcript: whose words each line holds.
*
* Only what the person typed can teach Trail anything. A transcript's `user`
* lines also carry text the agent read: compaction summaries (the model's
* own retelling, which can repeat what a tool returned), task notices from
* background work, slash-command wrappers, other sessions' hand-backs,
* subagent lines, tool results. About a third of what a naive `type: user`
* test calls a prompt is one of these. The flags Claude Code writes
* (`origin.kind`, `isMeta`, `isCompactSummary`, `isSidechain`) and the
* wrappers it puts around harness text decide; a line from a build too old to
* stamp `origin` is judged by its wrappers alone. `promptSource` does not
* decide: the desktop app and the IDE extension mark typed prompts `sdk`.
* A row from `claude -p` or an SDK (`entrypoint: sdk…`) is a script's prompt,
* never the person's, except in a lab home with the lab switch on (D26, D99),
* where the lab's headless runs stand in for a person.
*
* IDE context (`<ide_opened_file>`, `<ide_selection>`) and reminders ride in
* the same message as a real prompt, so they are stripped and the prompt is
* kept. A pasted block becomes a marker: the person sent it, but didn't write
* it.
*
* This is the one filter every learning path uses: cold start, the trace
* stream, provenance.
*
* `readNewEvents` turns what a transcript gained since the last read into one
* stream: typed words, injected text, tool calls, their results (failed or
* not), assistant text and compactions. Built in memory, never stored.
*/
import { readAppended, type Memo, type ReadOptions } from "./cursor.js";
import { failedText } from "./failure.js";
import { labInteractive } from "../skills/host-facts.js";
/**
* `offset` is the byte offset of the line the event came from (the save gate
* re-reads that line). A call carries the folder (`cwd`) and branch
* (`gitBranch`) the host recorded on its line; a result carries the host's own
* error flag (`isError`) apart from `ok`, which also reads failure text.
* `uuid` is the line's entry id: a transcript that repeats a block of its
* history repeats the ids, so the fold can tell old lines from new (D56d).
*/
export type TraceEvent =
| { kind: "typed"; text: string; at: string; offset?: number; uuid?: string }
| { kind: "injected"; text: string; at: string; offset?: number; uuid?: string }
| { kind: "tool_call"; id: string; name: string; input: unknown; at: string; offset?: number; uuid?: string; cwd?: string; branch?: string }
| { kind: "tool_result"; id: string; ok: boolean; text: string; at: string; offset?: number; uuid?: string; isError?: boolean }
| { kind: "compaction"; at: string; offset?: number; uuid?: string }
| { kind: "assistant"; text: string; at: string; offset?: number; uuid?: string };
interface Entry {
type?: string;
uuid?: unknown;
subtype?: string;
timestamp?: string;
cwd?: unknown;
gitBranch?: unknown;
isApiErrorMessage?: boolean;
isMeta?: boolean;
isSidechain?: boolean;
isCompactSummary?: boolean;
isVisibleInTranscriptOnly?: boolean;
entrypoint?: string;
origin?: { kind?: string } | null;
message?: { content?: unknown } | null;
attachment?: { type?: string; commandMode?: string; isMeta?: boolean; origin?: { kind?: string } | null; prompt?: unknown; content?: unknown } | null;
}
/** What stands for a pasted block in the person's words. */
export const PASTE_MARK = "[pasted text]";
/** Context the harness or IDE wraps around a real prompt: stripped, the prompt kept. */
const WRAPPED = /<(ide_[a-z_]+|system-reminder|user-prompt-submit-hook)\b[^>]*>[\s\S]*?<\/\1>/g;
/** Claude Code writes `<pasted_content id="1">…</pasted_content id="1">`; a cut-off one runs to the end. */
const PASTED = /<pasted_content\b[^>]*>[\s\S]*?(?:<\/pasted_content[^>]*>|$)/g;
/**
* Harness text that stands where a prompt would: a leading tag
* (`<task-notification>`, `<command-name>`, `<local-command-stdout>`,
* `<bash-input>`, `<agent-message>`, …), an interruption, a resumed
* session's preamble, a hand-back from another session.
*/
const NOT_TYPED = [
/^<[a-z][a-z0-9_-]*(?:\s[^>]*)?>/,
/^Caveat:/,
/^Another Claude session sent a message/,
/^\[Request interrupted/,
/^This session is being continued/,
];
/** The text parts of a message's content, joined; images, tool parts and the rest left out. */
export function textOf(content: unknown): string {
if (typeof content === "string") return content;
if (!Array.isArray(content)) return "";
const out: string[] = [];
for (const p of content) {
if (p && typeof p === "object" && (p as { type?: unknown }).type === "text" && typeof (p as { text?: unknown }).text === "string") {
out.push((p as { text: string }).text);
}
}
return out.join("\n");
}
/**
* The person's own words in one message's raw text: wrappers stripped,
* pastes marked, and "" when what's left is harness text or nothing typed.
*/
export function ownText(raw: string): string {
const t = raw.replace(WRAPPED, "").replace(PASTED, PASTE_MARK).trim();
if (!t || NOT_TYPED.some((re) => re.test(t))) return "";
if (!t.split(PASTE_MARK).join("").trim()) return "";
return t;
}
/** The raw text of a line that could be the person's, or null when its flags say it isn't. */
function candidateText(entry: unknown, env: NodeJS.ProcessEnv): string | null {
if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
const e = entry as Entry;
if (e.isMeta || e.isSidechain || e.isCompactSummary || e.isVisibleInTranscriptOnly) return null;
// `claude -p` and the SDKs: a script's prompt, written once and replayed. Only a lab home with the switch (D99) reads it.
if (typeof e.entrypoint === "string" && e.entrypoint.startsWith("sdk") && !labInteractive(env)) return null;
const human = (o: Entry["origin"]) => o === undefined || o === null || (typeof o === "object" && o.kind === "human");
if (e.type === "user") {
if (!human(e.origin)) return null;
const content = e.message?.content;
if (Array.isArray(content) && content.some((p) => p && typeof p === "object" && (p as { type?: unknown }).type === "tool_result")) return null;
return textOf(content);
}
// A message typed while the agent was busy is queued and lands as an attachment.
if (e.type === "attachment") {
const a = e.attachment;
if (!a || a.type !== "queued_command" || a.commandMode !== "prompt" || a.isMeta || !human(a.origin)) return null;
return textOf(a.prompt);
}
return null;
}
/**
* What the person typed in this transcript line, IDE tags and reminders stripped; "" when it isn't theirs.
* `env` decides only whether an sdk row can be typed (a lab home with the switch, D99).
*/
export function typedText(entry: unknown, env: NodeJS.ProcessEnv = process.env): string {
try {
const raw = candidateText(entry, env);
return raw === null ? "" : ownText(raw);
} catch {
return "";
}
}
/** Whether this transcript line is something the person typed. */
export function isTypedByPerson(entry: unknown, env: NodeJS.ProcessEnv = process.env): boolean {
return typedText(entry, env) !== "";
}
/* -------------------------------------------------------------------------- */
/* The event stream */
/* -------------------------------------------------------------------------- */
/** Tools whose results are command output, so their text can say they failed. */
const SHELL_TOOLS = new Set(["Bash", "PowerShell"]);
/** Open tool calls carried between reads, so a late result still knows its tool. */
const MAX_PENDING = 500;
/** Text kept per event: the head, and the tail where outcomes print. */
const MAX_TEXT = 40_000;
const KEEP_HEAD = 8_000;
function clip(t: string): string {
return t.length > MAX_TEXT ? `${t.slice(0, KEEP_HEAD)}\n…\n${t.slice(-(MAX_TEXT - KEEP_HEAD))}` : t;
}
/** The wrapped and pasted blocks taken out of a typed message: text the agent saw, not the person's words. */
function strippedBlocks(raw: string): string {
return [...raw.matchAll(WRAPPED), ...raw.matchAll(PASTED)].map((m) => m[0]).join("\n").trim();
}
function pendingOf(memo: Memo): Record<string, string> {
const p = memo.pending;
if (p && typeof p === "object" && !Array.isArray(p)) return p as Record<string, string>;
return (memo.pending = {}) as Record<string, string>;
}
function hookText(content: unknown): string {
if (typeof content === "string") return content;
return Array.isArray(content) ? content.filter((c): c is string => typeof c === "string").join("\n") : "";
}
/** The events one transcript line holds, appended to `out`. `offset`: where the line starts in the file. */
function eventsOf(e: Entry & { message?: { content?: unknown } | null }, memo: Memo, out: TraceEvent[], offset: number | undefined, env: NodeJS.ProcessEnv): void {
const at = typeof e.timestamp === "string" ? e.timestamp : "";
// Subagent lines are another context's work; their hand-back arrives as a result or a notice.
if (e.isSidechain) return;
const where = { ...(offset === undefined ? {} : { offset }), ...(typeof e.uuid === "string" && e.uuid ? { uuid: e.uuid } : {}) };
const push = (ev: TraceEvent) => {
if (ev.kind !== "injected") memo.boundary = false;
out.push({ ...ev, ...where });
};
const injected = (text: string) => {
const t = text.trim();
if (t) out.push({ kind: "injected", text: clip(t), at, ...where });
};
const cwd = typeof e.cwd === "string" && e.cwd ? { cwd: e.cwd } : {};
const branch = typeof e.gitBranch === "string" && e.gitBranch ? { branch: e.gitBranch } : {};
if (e.type === "system") {
if (e.subtype === "compact_boundary") {
push({ kind: "compaction", at });
memo.boundary = true;
}
return;
}
if (e.type === "assistant") {
if (e.isApiErrorMessage) return;
const content = e.message?.content;
if (typeof content === "string") {
if (content.trim()) push({ kind: "assistant", text: clip(content), at });
return;
}
if (!Array.isArray(content)) return;
const pending = pendingOf(memo);
for (const part of content as Array<Record<string, unknown> | null>) {
if (!part || typeof part !== "object") continue;
if (part.type === "text" && typeof part.text === "string" && part.text.trim()) push({ kind: "assistant", text: clip(part.text), at });
if (part.type === "tool_use") {
const id = String(part.id ?? "");
const name = String(part.name ?? "");
pending[id] = name;
push({ kind: "tool_call", id, name, input: part.input ?? null, at, ...cwd, ...branch });
}
}
const ids = Object.keys(pending);
for (const id of ids.slice(0, Math.max(0, ids.length - MAX_PENDING))) delete pending[id];
return;
}
if (e.type === "user") {
const content = e.message?.content;
if (e.isCompactSummary) {
// Older builds write the summary with no boundary line before it.
if (!memo.boundary) push({ kind: "compaction", at });
memo.boundary = false;
injected(textOf(content));
return;
}
if (Array.isArray(content) && content.some((p) => p && typeof p === "object" && (p as { type?: unknown }).type === "tool_result")) {
const pending = pendingOf(memo);
for (const part of content as Array<Record<string, unknown> | null>) {
if (!part || typeof part !== "object" || part.type !== "tool_result") continue;
const id = String(part.tool_use_id ?? "");
const name: string | undefined = pending[id];
delete pending[id];
const text = typeof part.content === "string" ? part.content : textOf(part.content);
// A call never seen (read before this window) is judged as a command.
const isError = part.is_error === true;
const ok = !(isError || ((name === undefined || SHELL_TOOLS.has(name)) && failedText(text)));
push({ kind: "tool_result", id, ok, text: clip(text), at, isError });
}
return;
}
const typed = typedText(e, env);
if (typed) {
push({ kind: "typed", text: typed, at });
injected(strippedBlocks(textOf(content)));
return;
}
injected(textOf(content));
return;
}
if (e.type === "attachment") {
const a = e.attachment;
if (!a || typeof a !== "object") return;
if (a.type === "queued_command") {
const typed = typedText(e, env);
if (typed) {
push({ kind: "typed", text: typed, at });
injected(strippedBlocks(textOf(a.prompt)));
} else injected(textOf(a.prompt));
} else if (a.type === "hook_additional_context") {
injected(hookText(a.content));
}
}
}
/**
* The events one parsed transcript line holds: the reader `readNewEvents` uses, for a caller that walks a file
* itself (init's replay over a byte range, b5). `memo` carries the open tool calls from line to line: start it
* as `{}` and pass the same object for every line of one read. Never throws on a line that isn't an entry.
*/
export function lineEvents(entry: unknown, memo: Memo, offset?: number, env: NodeJS.ProcessEnv = process.env): TraceEvent[] {
const out: TraceEvent[] = [];
if (!entry || typeof entry !== "object" || Array.isArray(entry)) return out;
eventsOf(entry as Entry, memo, out, offset, env);
return out;
}
export interface EventReadOptions extends ReadOptions {
/**
* Each line read, parsed, before its events: for a reader that needs what
* the events leave out (a reply's uuid, a response's usage). `memo` is the
* one saved with the cursor and started over with it; keep the caller's
* state under one key of its own. A throw is the caller's to avoid: it
* ends the read without saving the cursor.
*/
onEntry?: (entry: Record<string, unknown>, memo: Memo) => void;
/** Whose env decides whether an sdk row is typed (`typedText`); default `process.env`. */
env?: NodeJS.ProcessEnv;
}
/**
* The events a Claude Code transcript gained since the last call with the
* same `cursorPath`. The first call with no cursor reads at most the last
* 8 MB (`opts.firstReadBytes`; `Infinity` for the whole file). Never throws: a
* transcript that can't be read gives no events, and a cursor that can't be
* saved still returns what was read.
*/
export function readNewEvents(transcriptPath: string, cursorPath: string, opts: EventReadOptions = {}): TraceEvent[] {
const out: TraceEvent[] = [];
const onEntry = opts.onEntry;
const env = opts.env ?? process.env;
try {
readAppended(
transcriptPath,
cursorPath,
(line, memo, offset) => {
let e: unknown;
try {
e = JSON.parse(line);
} catch {
return;
}
if (!e || typeof e !== "object" || Array.isArray(e)) return;
if (onEntry) onEntry(e as Record<string, unknown>, memo);
eventsOf(e as Entry, memo, out, offset, env);
},
opts,
);
} catch {
/* fail open */
}
return out;
}