commandmate 0.29.1 → 0.30.0

package/dist/server/src/lib/hooks/sources/claude/transcript.js

@@ -0,0 +1,518 @@
+"use strict";
+/**
+ * Turning Claude Code's transcript JSONL back into the reply the agent wrote
+ * (Issue #2121).
+ *
+ * The counterpart of `../opencode/transcript`, for the tool that has no server
+ * to subscribe to. Claude writes every record of a session to
+ * `~/.claude/projects/<slug>/<session-id>.jsonl` as it goes, and that file holds
+ * the Markdown source of the reply — unwrapped, ungutterd, and with the
+ * operator's own prompt on a record of its own rather than echoed into the
+ * agent's.
+ *
+ * ## Why this exists rather than a better cleaner
+ *
+ * The same argument as #2041, plus one measurement that is specific to Claude.
+ * The Issue put the poller's saved `assistant` row at **13,253 characters**
+ * against the transcript's **3,669**, and the extra 9,584 were *the operator's
+ * own prompt*: the pane echoes it, `cleanClaudeResponse` has no way to tell the
+ * echo from the reply, and so History recorded the human's words as the agent's.
+ * That is not a rendering defect this module improves on — it is a defect this
+ * module structurally cannot have, because the prompt and the reply arrive on
+ * records with different `type`s and only `type: "assistant"` is read.
+ *
+ * ## What was measured
+ *
+ * Against Claude Code's live transcripts on 2026-08-31, and the 512 project
+ * directories under `~/.claude/projects` on this machine:
+ *
+ *  1. **The directory name is a pure function of `cwd`** — every non
+ *     alphanumeric byte becomes `-`. Checked against all 512 directories that
+ *     contained a record with a `cwd`: 512 agreed, 0 disagreed. See
+ *     {@link claudeProjectSlug}.
+ *  2. **One assistant record carries one content block**, and a turn is made of
+ *     many of them. A single unfinished prompt already held 55 assistant records
+ *     across 23 `requestId`s; the Issue measured 98 for a finished one. The turn
+ *     is therefore keyed on the *prompt* record, never on a `requestId`.
+ *  3. **`type: "user"` is mostly not the user.** Of 19 user records in the
+ *     sampled session, 18 were `tool_result` payloads. Tool results, `isMeta`
+ *     placeholders (`[Image: original 1440x2170…]`), and the slash-command
+ *     bookkeeping records (`<command-name>`, `<local-command-stdout>`) all have
+ *     `type: "user"` and none of them is a prompt. See {@link isClaudePromptRecord}.
+ *  4. **`thinking` blocks can be empty.** The block arrives with a `signature`
+ *     and `thinking: ""` when the text is not retained, so an empty one is
+ *     skipped rather than rendered as a blank quote.
+ *
+ * ## Pure on purpose
+ *
+ * No filesystem, no database, no `globalThis` — `./history` owns all three. The
+ * consequence is that "the saved body equals the transcript's text" is a
+ * property a test can assert against a fixture rather than a claim, which is
+ * the same reason `../opencode/transcript` is written this way.
+ *
+ * @module lib/hooks/sources/claude/transcript
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAUDE_HUMAN_PROMPT_SOURCES = exports.CLAUDE_HUMAN_ORIGIN_KIND = exports.CLAUDE_THINKING_LABEL = exports.MAX_CLAUDE_TOOL_DETAIL_LENGTH = exports.MAX_CLAUDE_TURN_BLOCKS = exports.CLAUDE_TURN_TRUNCATION_MARKER = exports.MAX_CLAUDE_TURN_BODY_LENGTH = exports.CLAUDE_PROJECTS_DIR_SEGMENTS = void 0;
+exports.claudeProjectSlug = claudeProjectSlug;
+exports.readClaudeContentBlock = readClaudeContentBlock;
+exports.readClaudeTranscriptRecord = readClaudeTranscriptRecord;
+exports.parseClaudeTranscript = parseClaudeTranscript;
+exports.isClaudePromptRecord = isClaudePromptRecord;
+exports.isClaudeOperatorPromptRecord = isClaudeOperatorPromptRecord;
+exports.createClaudeTurn = createClaudeTurn;
+exports.buildClaudeTurns = buildClaudeTurns;
+exports.renderClaudeTurn = renderClaudeTurn;
+const event_mapper_1 = require("../event-mapper");
+const turn_body_1 = require("../turn-body");
+/**
+ * `~/.claude/projects/<slug>` — the directory Claude keeps one project's
+ * sessions in, relative to the home directory.
+ */
+exports.CLAUDE_PROJECTS_DIR_SEGMENTS = ['.claude', 'projects'];
+/**
+ * The directory name Claude derives from a working directory.
+ *
+ * Every byte that is not `[A-Za-z0-9]` becomes `-`, including the separators,
+ * the dots of a hidden directory and the underscores of `github_kewton`. Case is
+ * preserved. Verified exhaustively rather than assumed: on 2026-08-31 the rule
+ * was applied to the `cwd` recorded inside a transcript in each of the 512
+ * project directories on this machine that had one, and reproduced the
+ * directory name in 512 cases out of 512.
+ *
+ * A path that is not this instance's `cwd` produces a directory that does not
+ * exist, which `./history` reads as "no transcript" and falls back to the
+ * scraper for. There is no failure mode where a wrong slug reaches a *different*
+ * session's file: two different `cwd`s cannot collide unless they differ only in
+ * non-alphanumeric bytes, and two worktrees whose paths differ only in `_` vs
+ * `-` are the same directory to nobody but this function.
+ *
+ * @param cwd - Absolute working directory, as the agent reports it
+ */
+function claudeProjectSlug(cwd) {
+    return cwd.replace(/[^a-zA-Z0-9]/g, '-');
+}
+/** Longest body written for one turn. Same bound and reason as opencode's. */
+exports.MAX_CLAUDE_TURN_BODY_LENGTH = 200_000;
+/** Appended when {@link MAX_CLAUDE_TURN_BODY_LENGTH} truncates a turn. */
+exports.CLAUDE_TURN_TRUNCATION_MARKER = '\n\n_(truncated)_';
+/**
+ * Cap on content blocks kept for one turn.
+ *
+ * Generous because a Claude turn is genuinely large — the measured session ran
+ * 32 `tool_use` blocks in one reply — and because the overflow is reported
+ * rather than hidden.
+ */
+exports.MAX_CLAUDE_TURN_BLOCKS = 2048;
+/** Longest tool detail put on a summary line. */
+exports.MAX_CLAUDE_TOOL_DETAIL_LENGTH = 200;
+/** The label a thinking block is folded behind. Same word opencode uses. */
+exports.CLAUDE_THINKING_LABEL = 'Thinking';
+/**
+ * Prefixes that mark a `type: "user"` record as bookkeeping rather than a prompt.
+ *
+ * All four were observed on real transcripts. `<local-command-caveat>` and the
+ * `<command-…>` trio are how a slash command is recorded; `<local-command-stdout>`
+ * is its output. Treating any of them as a prompt would open a turn that the
+ * operator never typed, and the reply to the *next* real prompt would be filed
+ * under it.
+ */
+const CLAUDE_SYNTHETIC_PROMPT_PREFIXES = [
+    '<local-command-caveat>',
+    '<local-command-stdout>',
+    '<command-name>',
+    '<command-message>',
+];
+/**
+ * Read one `message.content` element.
+ *
+ * @returns The block, or null when it is not an object with a `type`
+ */
+function readClaudeContentBlock(value) {
+    if (!(0, event_mapper_1.isPlainObject)(value))
+        return null;
+    const type = (0, event_mapper_1.readStringField)(value, 'type');
+    if (!type)
+        return null;
+    if (type === 'tool_use') {
+        return {
+            type,
+            text: null,
+            toolName: (0, event_mapper_1.readStringField)(value, 'name'),
+            toolDetail: readToolDetail(value.input),
+        };
+    }
+    // `text` on a text block, `thinking` on a thinking block. Read by name rather
+    // than by trying both on every block so that a future block type carrying an
+    // unrelated `text` field is not silently rendered as prose.
+    const text = type === 'text'
+        ? ((0, event_mapper_1.readStringField)(value, 'text') ?? '')
+        : type === 'thinking'
+            ? ((0, event_mapper_1.readStringField)(value, 'thinking') ?? '')
+            : null;
+    return { type, text, toolName: null, toolDetail: null };
+}
+/**
+ * The fields of a `tool_use` input worth putting on the summary line, in
+ * preference order.
+ *
+ * The command for `Bash`, the path for the file tools, the pattern for the
+ * search tools, and `description` last as the tool's own words about itself.
+ * Anything else renders as the bare tool name, which is what the operator saw
+ * on the TUI's tool row anyway.
+ */
+const CLAUDE_TOOL_DETAIL_FIELDS = [
+    'command',
+    'file_path',
+    'notebook_path',
+    'path',
+    'pattern',
+    'query',
+    'url',
+    'description',
+];
+/** The first present detail field of a `tool_use` input, collapsed to a line. */
+function readToolDetail(input) {
+    if (!(0, event_mapper_1.isPlainObject)(input))
+        return null;
+    for (const field of CLAUDE_TOOL_DETAIL_FIELDS) {
+        const value = (0, event_mapper_1.readStringField)(input, field);
+        if (value)
+            return boundToolDetail(collapseToLine(value));
+    }
+    return null;
+}
+/** A tool detail on one line. A heredoc `command` puts newlines in it. */
+function collapseToLine(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+function boundToolDetail(value) {
+    return value.length <= exports.MAX_CLAUDE_TOOL_DETAIL_LENGTH
+        ? value
+        : `${value.slice(0, exports.MAX_CLAUDE_TOOL_DETAIL_LENGTH - 1)}…`;
+}
+/**
+ * Read one parsed transcript line.
+ *
+ * @returns The record, or null when the value is not an object with a `type`
+ */
+function readClaudeTranscriptRecord(value) {
+    if (!(0, event_mapper_1.isPlainObject)(value))
+        return null;
+    const type = (0, event_mapper_1.readStringField)(value, 'type');
+    if (!type)
+        return null;
+    const message = (0, event_mapper_1.isPlainObject)(value.message) ? value.message : null;
+    const rawContent = message?.content;
+    const blocks = [];
+    let text = '';
+    if (typeof rawContent === 'string') {
+        // A prompt the operator typed arrives as a bare string, not as an array.
+        text = rawContent;
+    }
+    else if (Array.isArray(rawContent)) {
+        for (const entry of rawContent) {
+            const block = readClaudeContentBlock(entry);
+            if (!block)
+                continue;
+            blocks.push(block);
+            if (block.text)
+                text += block.text;
+        }
+    }
+    const timestamp = (0, event_mapper_1.readStringField)(value, 'timestamp');
+    const parsed = timestamp ? Date.parse(timestamp) : NaN;
+    const origin = (0, event_mapper_1.isPlainObject)(value.origin) ? value.origin : null;
+    return {
+        type,
+        uuid: (0, event_mapper_1.readStringField)(value, 'uuid'),
+        sessionId: (0, event_mapper_1.readStringField)(value, 'sessionId') ?? (0, event_mapper_1.readStringField)(value, 'session_id'),
+        cwd: (0, event_mapper_1.readStringField)(value, 'cwd'),
+        isSidechain: value.isSidechain === true,
+        isMeta: value.isMeta === true,
+        originKind: origin ? (0, event_mapper_1.readStringField)(origin, 'kind') : null,
+        promptSource: (0, event_mapper_1.readStringField)(value, 'promptSource'),
+        isCompactSummary: value.isCompactSummary === true,
+        isInterruption: (0, event_mapper_1.readStringField)(value, 'interruptedMessageId') !== null,
+        timestampMs: Number.isFinite(parsed) ? parsed : null,
+        blocks,
+        text,
+    };
+}
+/**
+ * Parse a slice of a transcript file, one line at a time.
+ *
+ * A line that does not parse is counted and dropped; the rest of the slice is
+ * still read. That is the entire answer to "the file is being appended to while
+ * we read it": the only line a concurrent write can damage is the last one, and
+ * the cost of losing it is that this turn is written on the next poll instead of
+ * this one.
+ *
+ * @param text - The bytes read, decoded as UTF-8
+ */
+function parseClaudeTranscript(text) {
+    const records = [];
+    let malformedLines = 0;
+    for (const line of text.split('\n')) {
+        if (line.trim().length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            malformedLines += 1;
+            continue;
+        }
+        const record = readClaudeTranscriptRecord(parsed);
+        if (record)
+            records.push(record);
+        else
+            malformedLines += 1;
+    }
+    return { records, malformedLines };
+}
+/**
+ * Whether this record is the operator's own prompt.
+ *
+ * Four things disqualify a `type: "user"` record, and all four were observed:
+ *
+ *  - it carries a `tool_result` block — 18 of the 19 user records in the sampled
+ *    session were these;
+ *  - `isMeta` is true — the image placeholders and the local-command caveat;
+ *  - its text opens with one of {@link CLAUDE_SYNTHETIC_PROMPT_PREFIXES} — the
+ *    slash-command bookkeeping;
+ *  - it has no text at all, or no `uuid` to name the turn with.
+ *
+ * Everything else is treated as a prompt, including `[Request interrupted by
+ * user]`. That is deliberate: an interruption really does end the turn, and the
+ * records after it really do belong to whatever came next.
+ */
+function isClaudePromptRecord(record) {
+    if (record.type !== 'user')
+        return false;
+    if (record.isMeta)
+        return false;
+    if (!record.uuid)
+        return false;
+    if (record.blocks.some((block) => block.type === 'tool_result'))
+        return false;
+    const text = record.text.trim();
+    if (text.length === 0)
+        return false;
+    return !CLAUDE_SYNTHETIC_PROMPT_PREFIXES.some((prefix) => text.startsWith(prefix));
+}
+/**
+ * `origin.kind` for a record the person at the keyboard produced (Issue #2196).
+ */
+exports.CLAUDE_HUMAN_ORIGIN_KIND = 'human';
+/**
+ * `promptSource` values that mean "the operator's own input" (Issue #2196).
+ *
+ * `typed` is the composer. `queued` is the composer too — text entered while the
+ * agent was still answering the previous prompt, which Claude holds and submits
+ * when the turn ends. The two that are excluded are excluded on measurement:
+ * `system` (always paired with `origin.kind = "task-notification"`) and `sdk`
+ * (a headless `claude -p` run, which has no chat pane to appear in).
+ */
+exports.CLAUDE_HUMAN_PROMPT_SOURCES = ['typed', 'queued'];
+/**
+ * Whether this record is text a human typed at the terminal (Issue #2196).
+ *
+ * Strictly narrower than {@link isClaudePromptRecord}, and the two are not
+ * interchangeable. That one answers "does a turn start here", which every
+ * prompt-shaped record does — a task notification really is answered, and the
+ * reply really does belong to it. This one answers "should this text appear in
+ * History as the operator's message", which is a different question with a
+ * different cost of being wrong: a wrong `true` puts machinery
+ * (`<task-notification>…`, a compaction summary, a skill's whole SKILL.md) in
+ * the chat pane as if the operator had said it.
+ *
+ * ## Positive evidence, not a deny list
+ *
+ * The rule is `origin.kind === "human"` **or** a `promptSource` on
+ * {@link CLAUDE_HUMAN_PROMPT_SOURCES} — a record that claims neither produces no
+ * row. That direction was chosen on a census rather than on taste: across all
+ * 744 transcripts under `~/.claude/projects` on 2026-09-01, of the 4,943
+ * `type: "user"` records that survive {@link isClaudePromptRecord}, **4,909
+ * carried one of the two markers and 34 did not — and all 34 were `/compact` or
+ * `[Request interrupted by user for tool use]`, not one of them a prompt.** The
+ * markers are present on every version in the sample (2.1.215 … 2.1.252).
+ *
+ * So the deny-list framing had nothing left to deny that the markers do not
+ * already exclude, and it fails the wrong way: a record shape a later Claude
+ * invents would default to *being shown*. This defaults to being skipped, which
+ * is the pre-#2196 behaviour — an orphaned assistant pair, which is untidy, and
+ * not a fabricated user message, which is wrong.
+ *
+ * `isCompactSummary` and `isInterruption` are then checked explicitly even
+ * though nothing observed carries a human marker *and* either flag. They are not
+ * redundant by construction: compaction and interruption are both things the
+ * operator initiates, so a later version stamping `origin.kind = "human"` on
+ * them would be defensible from Claude's side and wrong from this one's.
+ */
+function isClaudeOperatorPromptRecord(record) {
+    if (!isClaudePromptRecord(record))
+        return false;
+    if (record.isCompactSummary)
+        return false;
+    if (record.isInterruption)
+        return false;
+    if (record.originKind !== null)
+        return record.originKind === exports.CLAUDE_HUMAN_ORIGIN_KIND;
+    return record.promptSource !== null && exports.CLAUDE_HUMAN_PROMPT_SOURCES.includes(record.promptSource);
+}
+/** A brand-new accumulator for one turn. */
+function createClaudeTurn(record, sessionId) {
+    return {
+        sessionId: record.sessionId ?? sessionId,
+        promptUuid: record.uuid,
+        startedAt: record.timestampMs ?? 0,
+        promptText: record.text,
+        promptIsOperatorInput: isClaudeOperatorPromptRecord(record),
+        blocks: [],
+        assistantRecords: 0,
+        overflowed: false,
+    };
+}
+/**
+ * Group a transcript's records into turns.
+ *
+ * File order, and a prompt record opens a turn. Deliberately **not** the
+ * `parentUuid` chain, which does not link a reply to its prompt: in the sampled
+ * session the first assistant record's `parentUuid` named a record that is not
+ * the prompt at all (the bookkeeping lines Claude writes between the two are
+ * part of the chain). Order is what actually holds.
+ *
+ * `isSidechain` records are skipped. They are a sub-agent's conversation, held
+ * in the same file as the session that spawned it, and folding a sub-agent's
+ * narration into the reply the operator is reading would reintroduce exactly the
+ * "work-in-progress muttering runs into the answer" problem the Issue asks this
+ * module to solve. The Issue lists sidechains as unmeasured — the sampled
+ * session had none — so they are excluded and counted rather than guessed at.
+ *
+ * @param records - In file order
+ * @param sessionId - Fallback for records that carry no `sessionId`
+ */
+function buildClaudeTurns(records, sessionId) {
+    const turns = [];
+    let current = null;
+    let orphanedAssistantRecords = 0;
+    let sidechainRecords = 0;
+    for (const record of records) {
+        if (record.isSidechain) {
+            sidechainRecords += 1;
+            continue;
+        }
+        if (isClaudePromptRecord(record)) {
+            current = createClaudeTurn(record, sessionId);
+            turns.push(current);
+            continue;
+        }
+        if (record.type !== 'assistant')
+            continue;
+        if (!current) {
+            orphanedAssistantRecords += 1;
+            continue;
+        }
+        current.assistantRecords += 1;
+        for (const block of record.blocks) {
+            if (current.blocks.length >= exports.MAX_CLAUDE_TURN_BLOCKS) {
+                current.overflowed = true;
+                break;
+            }
+            current.blocks.push(block);
+        }
+    }
+    return { turns, orphanedAssistantRecords, sidechainRecords };
+}
+/**
+ * Block types that carry nothing a reader wants.
+ *
+ * A deny set rather than an allow set, for the reason `../opencode/transcript`
+ * gives: a block type a later Claude adds should surface in the unknown tally
+ * instead of being silently equivalent to a tool result. `tool_result` is on it
+ * because those blocks live on `user` records, which never reach a turn's body.
+ */
+const CLAUDE_SILENT_BLOCK_TYPES = new Set(['tool_result']);
+/** One tool call as a single Markdown line. */
+function renderToolBlock(block) {
+    const name = block.toolName ?? 'tool';
+    return block.toolDetail ? `- \`${name}\` — ${block.toolDetail}` : `- \`${name}\``;
+}
+/**
+ * Thinking, folded.
+ *
+ * A blockquote and not `<details>`, for the reason `../opencode/transcript`
+ * documents: `<details>` would require running raw HTML through the card's
+ * sanitiser, and that costs every unfenced `<T>` in ordinary prose.
+ */
+function renderThinkingBlock(text) {
+    const quoted = text
+        .trim()
+        .split('\n')
+        .map((line) => (line.length > 0 ? `> ${line}` : '>'))
+        .join('\n');
+    return `> **${exports.CLAUDE_THINKING_LABEL}**\n>\n${quoted}`;
+}
+/**
+ * Render one turn to Markdown.
+ *
+ * Every block is kept — #2121 asked for a decision between "show every block as
+ * a process" and "show only the final block" and this is the first, because the
+ * order is the only record of what happened when and this row is the record.
+ * What makes it readable rather than a run-on paragraph is that the blocks are
+ * *separated*: prose blocks are paragraphs, thinking is a quote, and tool calls
+ * are list items folded into one labelled section at the end.
+ *
+ * The layout itself belongs to `../turn-body` (#2234), which is what stops this
+ * turn's body opening with a run of `- \`Bash\` — …` lines; see
+ * {@link separateTurnBody} for why the interleaving between prose and tool calls
+ * is the one thing given up.
+ */
+function renderClaudeTurn(turn) {
+    const rendered = [];
+    const unknown = new Set();
+    let textBlocks = 0;
+    let toolBlocks = 0;
+    for (const block of turn.blocks) {
+        if (block.type === 'text') {
+            const text = block.text?.trim() ?? '';
+            if (text.length === 0)
+                continue;
+            rendered.push({ kind: 'prose', text });
+            textBlocks += 1;
+            continue;
+        }
+        if (block.type === 'thinking') {
+            // Measured empty on the sampled session: the block arrives with its
+            // `signature` and no text when the thinking is not retained.
+            const text = block.text?.trim() ?? '';
+            if (text.length === 0)
+                continue;
+            rendered.push({ kind: 'aside', text: renderThinkingBlock(text) });
+            continue;
+        }
+        if (block.type === 'tool_use') {
+            rendered.push({ kind: 'tool', text: renderToolBlock(block) });
+            toolBlocks += 1;
+            continue;
+        }
+        if (!CLAUDE_SILENT_BLOCK_TYPES.has(block.type))
+            unknown.add(block.type);
+    }
+    let body = (0, turn_body_1.separateTurnBody)(rendered).body;
+    if (body.length > exports.MAX_CLAUDE_TURN_BODY_LENGTH) {
+        body =
+            body.slice(0, exports.MAX_CLAUDE_TURN_BODY_LENGTH - exports.CLAUDE_TURN_TRUNCATION_MARKER.length) +
+                exports.CLAUDE_TURN_TRUNCATION_MARKER;
+    }
+    return {
+        sessionId: turn.sessionId,
+        promptUuid: turn.promptUuid,
+        body,
+        textBlocks,
+        toolBlocks,
+        unknownBlockTypes: [...unknown],
+    };
+}