273 lines
12 KiB
Python
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
|