Files
claude-config/bin/claude_code/entries.py
T

273 lines
12 KiB
Python

"""Entries of Claude Code's transcripts and of its stream-json and json output."""
import dataclasses
import json
import typing
def json_object(raw: str | bytes) -> dict | None:
"""A line of JSON, such as a transcript line, a stream-json line or claude's json reply, where it is an object; None otherwise."""
try:
found = json.loads(raw)
except ValueError:
return None
return found if isinstance(found, dict) else None
@dataclasses.dataclass(frozen=True, kw_only=True)
class Entry:
"""A transcript entry, with the fields every entry may carry, each "" where it has none. Kinds no consumer tells apart, such as a compaction's boundary, parse as Entry itself. Each subclass names a kind consumers tell apart."""
uuid: str = ""
parent_uuid: str = ""
timestamp: str = ""
cwd: str = ""
git_branch: str = ""
@dataclasses.dataclass(frozen=True, kw_only=True)
class UserText(Entry):
"""The text of a "user" entry, its text blocks joined, or of a prompt the human queued while claude worked. HumanTurn, LoopPrompt and InjectedText say who wrote it."""
text: str
class HumanTurn(UserText):
"""What the human wrote, at the prompt or while claude worked."""
class LoopPrompt(UserText):
"""What loop-claude told the worker in a -p prompt."""
class InjectedText(UserText):
"""Text Claude Code wrote into the prompt, such as a slash command, a task notification or a compaction's summary."""
class Text(typing.NamedTuple):
text: str
class ToolCall(typing.NamedTuple):
id: str
name: str
input: dict
class ToolResult(typing.NamedTuple):
tool_use_id: str
text: str
failed: bool
@dataclasses.dataclass(frozen=True, kw_only=True)
class AssistantTurn(Entry):
"""An assistant entry's text and tool-call blocks, with its message's id, model and usage. Claude Code writes one entry per block of a message, so one message's usage repeats across several entries."""
parts: tuple[Text | ToolCall, ...] = ()
message_id: str = ""
model: str = ""
usage: dict = dataclasses.field(default_factory=dict)
@dataclasses.dataclass(frozen=True, kw_only=True)
class ToolResults(Entry):
"""The tool results Claude Code returns in a "user" entry, or logs again with the API request that sent them."""
results: tuple[ToolResult, ...]
@dataclasses.dataclass(frozen=True, kw_only=True)
class CostState(Entry):
"""The cost in dollars Claude Code records for each model the session has called so far, the subagents' and the compactions' calls too."""
costs: dict[str, float]
def parse_entry(raw: str | bytes) -> Entry | None:
"""A transcript line as its kind; None where it is not a JSON object."""
found = json_object(raw)
return None if found is None else entry_from(found)
def entry_from(found: dict) -> Entry:
"""A transcript entry, or a stream-json event, as its kind."""
carried = Carried(uuid=field(found, "uuid"), parent_uuid=field(found, "parentUuid"), timestamp=field(found, "timestamp"), cwd=field(found, "cwd"), git_branch=field(found, "gitBranch"))
match found.get("type"):
case "assistant":
return assistant_turn(found, carried)
case "user":
return user_entry(found, carried)
case "cost-state":
return cost_state(found, carried)
# Claude Code logs each API request's last message again, and some of its tool results appear nowhere else: {"type": "api-request-blob", "hash": "…", "message": {"role": "user", "content": [{"type": "tool_result", …}, {"type": "text", …}]}}
case "api-request-blob":
return ToolResults(**carried, results=results_in(found))
if (queued := queued_human_text(found)) is not None:
return HumanTurn(**carried, text=queued)
return Entry(**carried)
class Carried(typing.TypedDict):
"""The fields of Entry, read from any kind of entry."""
uuid: str
parent_uuid: str
timestamp: str
cwd: str
git_branch: str
# Alike in the transcript and in stream-json: {"type": "assistant", "message": {"id": "msg_01…", "model": "claude-opus-5-5", "content": [{"type": "text", "text": "ok"}], "usage": {...}}}
def assistant_turn(found: dict, carried: Carried) -> AssistantTurn:
message = found["message"] if isinstance(found.get("message"), dict) else {}
usage = message.get("usage")
parts = tuple(part for block in blocks(found) if (part := part_from(block)))
return AssistantTurn(**carried, parts=parts, message_id=field(message, "id"), model=field(message, "model"), usage=usage if isinstance(usage, dict) else {})
def user_entry(found: dict, carried: Carried) -> UserText | ToolResults:
if results := results_in(found):
return ToolResults(**carried, results=results)
said = content(found)
text = said if isinstance(said, str) else "".join(part_text(block) or "" for block in blocks(found))
# {"type": "user", "promptSource": "sdk", "message": {"content": "Continue the task; the previous run ended before the chunk was finished."}}
if found.get("promptSource") == "sdk" and isinstance(said, str):
return LoopPrompt(**carried, text=text)
return HumanTurn(**carried, text=text) if written_by_human(found) else InjectedText(**carried, text=text)
def results_in(found: dict) -> tuple[ToolResult, ...]:
return tuple(result for block in blocks(found) if (result := tool_result(block)))
# {"type": "cost-state", "totalCostUSD": 40.1, "modelUsage": {"claude-opus-5-5": {"costUSD": 40.1, "outputTokens": 334504, ...}}, ...}
def cost_state(found: dict, carried: Carried) -> CostState:
by_model = found["modelUsage"] if isinstance(found.get("modelUsage"), dict) else {}
return CostState(**carried, costs={model: cost for model, usage in by_model.items() if isinstance(usage, dict) and isinstance(cost := usage.get("costUSD"), (int, float))})
def tool_calls(entries: typing.Iterable[Entry]) -> list[tuple[AssistantTurn, ToolCall]]:
"""Each tool call, with the turn that made it."""
return [(entry, part) for entry in entries if isinstance(entry, AssistantTurn) for part in entry.parts if isinstance(part, ToolCall)]
def messages(entries: typing.Iterable[Entry]) -> list[list[AssistantTurn]]:
"""The assistant turns grouped by message, in the order each message first appears. A message's usage repeats in each of its entries, so read it from the first of a group: none of 1,681 multi-entry messages in the archive of 2026-10-28 differed."""
grouped: dict[str, list[AssistantTurn]] = {}
for entry in entries:
if isinstance(entry, AssistantTurn):
grouped.setdefault(entry.message_id or entry.uuid, []).append(entry)
return list(grouped.values())
def field(found: dict, key: str) -> str:
return value if isinstance(value := found.get(key), str) else ""
def content(entry: dict) -> object:
message = entry.get("message")
return message.get("content") if isinstance(message, dict) else None
def blocks(entry: dict) -> list:
found = content(entry)
return found if isinstance(found, list) else []
def written_by_human(entry: dict) -> bool:
"""Whether the human wrote a "user" entry; Claude Code writes the rest."""
if tagged_as_injected(entry):
return False
text = content(entry)
return string_by_human(entry, text) if isinstance(text, str) else blocks_by_human(blocks(entry))
# {"type": "user", "isMeta": true, "message": {"content": "<local-command-caveat>Caveat: ..."}}
# {"type": "user", "promptSource": "sdk", "message": {"content": "Continue the task; ..."}}
# {"type": "user", "promptSource": "system", "message": {"content": "<task-notification>..."}}
# {"type": "user", "isCompactSummary": true, "message": {"content": "This session is being continued from a previous conversation that ran out of context. ..."}}
def tagged_as_injected(entry: dict) -> bool:
return bool(entry.get("isMeta")) or bool(entry.get("isCompactSummary")) or entry.get("promptSource") in ("sdk", "system")
# {"type": "user", "promptSource": "typed", "message": {"content": "merge it"}}
# {"type": "user", "message": {"content": "<command-name>/model</command-name>\n..."}}
def string_by_human(entry: dict, text: str) -> bool:
# Without promptSource, nothing else says who wrote the entry, so a leading < counts as Claude Code's.
return entry.get("promptSource") == "typed" or not text.startswith("<")
# {"type": "user", "message": {"content": [{"type": "text", "text": "merge it"}]}}
# {"type": "user", "message": {"content": [{"type": "text", "text": "[Request interrupted by user]"}]}}
def blocks_by_human(found: list) -> bool:
texts = [part_text(block) for block in found]
return bool(texts) and all(text is not None and not text.startswith("[Request interrupted") for text in texts)
# What the human types while claude works, written only as this entry:
# {"type": "attachment", "attachment": {"type": "queued_command", "commandMode": "prompt", "origin": {"kind": "human"}, "prompt": "B"}}
def queued_human_text(entry: dict) -> str | None:
attachment = entry.get("attachment") if entry.get("type") == "attachment" else None
if not isinstance(attachment, dict) or attachment.get("type") != "queued_command" or not isinstance(origin := attachment.get("origin"), dict) or origin.get("kind") != "human":
return None
return prompt if isinstance(prompt := attachment.get("prompt"), str) else None
# {"type": "tool_use", "id": "toolu_01…", "name": "Bash", "input": {"command": "echo hi"}}
def part_from(block: object) -> Text | ToolCall | None:
if (text := part_text(block)) is not None:
return Text(text)
if isinstance(block, dict) and block.get("type") == "tool_use" and isinstance(name := block.get("name"), str) and isinstance(arguments := block.get("input"), dict):
return ToolCall(field(block, "id"), name, arguments)
return None
# {"type": "text", "text": "ok"}
def part_text(part: object) -> str | None:
return part["text"] if isinstance(part, dict) and part.get("type") == "text" and isinstance(part.get("text"), str) else None
# {"type": "tool_result", "tool_use_id": "toolu_01…", "content": "hi"}, its content also as [{"type": "text", "text": "hi"}], and with "is_error": true where the call failed
def tool_result(part: object) -> ToolResult | None:
if not isinstance(part, dict) or part.get("type") != "tool_result":
return None
return ToolResult(str(part.get("tool_use_id")), result_text(part.get("content")), bool(part.get("is_error")))
def result_text(content: object) -> str:
if isinstance(content, str):
return content
# Claude Code may split one text across blocks, even inside a line, so the blocks join without anything between them.
return "".join(part_text(part) or "" for part in content) if isinstance(content, list) else ""
# stream-json's last line: {"type": "result", "subtype": "success", ...}
def ends_stream(event: dict) -> bool:
return event.get("type") == "result"
# {"type": "result", "api_error_status": 429, "result": "You've hit your session limit · resets 7:40pm (Europe/Stockholm)", ...}
def hit_limit(event: dict) -> bool:
return ends_stream(event) and event.get("api_error_status") == 429
# {"type": "result", "structured_output": {"evidence": "...", ...}, ...}
def structured_output(result: dict) -> object:
return result.get("structured_output")
def limit_said(event: dict) -> str:
said = " ".join(result.split()) if isinstance(result := event.get("result"), str) else ""
return said or "claude gave no message"
# {"type": "rate_limit_event", "rate_limit_info": {"status": "rejected", "resetsAt": 1790790000, ...}}
def rejected_until(event: dict) -> int | None:
"""When a usage limit that rejected the request resets, in seconds since the epoch."""
info = event.get("rate_limit_info") if event.get("type") == "rate_limit_event" else None
if not isinstance(info, dict) or info.get("status") != "rejected":
return None
resets_at = info.get("resetsAt")
return resets_at if isinstance(resets_at, int) and not isinstance(resets_at, bool) else None
# A count Claude Code left out or wrote as another type doesn't add anything, so one odd entry leaves the rest of a figure standing.
def usage_count(usage: dict, field: str) -> int:
"""One token count of a message's usage: {"input_tokens": 2, "cache_creation_input_tokens": 14541, "output_tokens": 8, ...}"""
value = usage.get(field)
return value if isinstance(value, int) else 0