cc-transcript 14.2.0__tar.gz → 14.4.0__tar.gz

{cc_transcript-14.2.0 → cc_transcript-14.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-transcript
-Version: 14.2.0
+Version: 14.4.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers

{cc_transcript-14.2.0 → cc_transcript-14.4.0}/cc_transcript/__init__.py

@@ -53,6 +53,7 @@ EXPORTS: dict[str, str] = {
             "ReadResult",
             "SkillCall",
             "SkillResult",
+            "SpanEditCall",
             "TaskCall",
             "TaskCreateCall",
             "TaskLaunchResult",
@@ -76,7 +77,9 @@ EXPORTS: dict[str, str] = {
             "mcp_parts",
             "parse_tool_call",
             "parse_tool_result",
+            "register_mcp_tool",
             "tool_name_matches",
+            "unregister_mcp_tool",
         ),
         "cc_transcript.command": (
             "Command",
@@ -142,10 +145,25 @@ EXPORTS: dict[str, str] = {
         "cc_transcript.parser": (
             "parse",
             "parse_event",
+            "parse_events",
             "parse_events_from_bytes",
             "parse_print_result",
             "stream",
         ),
+        "cc_transcript.synthetic": (
+            "assistant_line",
+            "meta_fields",
+            "mode_line",
+            "other_line",
+            "synthetic_assistant_event",
+            "synthetic_user_event",
+            "system_line",
+            "text_block",
+            "thinking_block",
+            "tool_result",
+            "tool_use",
+            "user_line",
+        ),
         "cc_transcript.cost": (
             "PRICING",
             "CostBreakdown",

{cc_transcript-14.2.0 → cc_transcript-14.4.0}/cc_transcript/__init__.pyi

@@ -187,6 +187,7 @@ from cc_transcript.notifications import (
 from cc_transcript.parser import (
     parse as parse,
     parse_event as parse_event,
+    parse_events as parse_events,
     parse_events_from_bytes as parse_events_from_bytes,
     parse_print_result as parse_print_result,
     stream as stream,
@@ -207,6 +208,21 @@ from cc_transcript.render import (
     render_turn as render_turn,
 )
 
+from cc_transcript.synthetic import (
+    assistant_line as assistant_line,
+    meta_fields as meta_fields,
+    mode_line as mode_line,
+    other_line as other_line,
+    synthetic_assistant_event as synthetic_assistant_event,
+    synthetic_user_event as synthetic_user_event,
+    system_line as system_line,
+    text_block as text_block,
+    thinking_block as thinking_block,
+    tool_result as tool_result,
+    tool_use as tool_use,
+    user_line as user_line,
+)
+
 from cc_transcript.tools import (
     AskUserQuestionResult as AskUserQuestionResult,
     BashCall as BashCall,
@@ -227,6 +243,7 @@ from cc_transcript.tools import (
     ReadResult as ReadResult,
     SkillCall as SkillCall,
     SkillResult as SkillResult,
+    SpanEditCall as SpanEditCall,
     TOOL_ALIASES as TOOL_ALIASES,
     TaskCall as TaskCall,
     TaskCreateCall as TaskCreateCall,
@@ -251,7 +268,9 @@ from cc_transcript.tools import (
     mcp_parts as mcp_parts,
     parse_tool_call as parse_tool_call,
     parse_tool_result as parse_tool_result,
+    register_mcp_tool as register_mcp_tool,
     tool_name_matches as tool_name_matches,
+    unregister_mcp_tool as unregister_mcp_tool,
 )
 
 from cc_transcript.watch import (
@@ -360,6 +379,7 @@ __all__ = [
     "SessionId",
     "SkillCall",
     "SkillResult",
+    "SpanEditCall",
     "StopHookSummary",
     "SubagentIndex",
     "SubagentSession",
@@ -406,6 +426,7 @@ __all__ = [
     "WriteResult",
     "annotate_spec",
     "apply_spec",
+    "assistant_line",
     "build_spec",
     "canonical_json",
     "capture_window",
@@ -440,15 +461,20 @@ __all__ = [
     "mcp_access",
     "mcp_parts",
     "mcp_summary",
+    "meta_fields",
+    "mode_line",
     "native_user_classifier",
+    "other_line",
     "parse",
     "parse_command_line",
     "parse_event",
+    "parse_events",
     "parse_events_from_bytes",
     "parse_print_result",
     "parse_tool_call",
     "parse_tool_result",
     "record_harvest",
+    "register_mcp_tool",
     "render_session",
     "render_tool_call",
     "render_turn",
@@ -457,9 +483,18 @@ __all__ = [
     "result_index",
     "stream",
     "subagent_paths",
+    "synthetic_assistant_event",
+    "synthetic_user_event",
+    "system_line",
+    "text_block",
+    "thinking_block",
     "thinking_chars",
     "tool_digest",
     "tool_facts",
     "tool_name_matches",
+    "tool_result",
+    "tool_use",
     "tool_uses",
+    "unregister_mcp_tool",
+    "user_line",
 ]

{cc_transcript-14.2.0 → cc_transcript-14.4.0}/cc_transcript/_native.pyi

@@ -72,6 +72,7 @@ __all__ = [
     "ServerToolUse",
     "SkillCall",
     "SkillResult",
+    "SpanEditCall",
     "SpecMatcher",
     "StopHookSummary",
     "SystemEvent",
@@ -133,6 +134,7 @@ __all__ = [
     "parse_bytes",
     "parse_print_result",
     "query_session",
+    "register_mcp_tool",
     "render_compact_lines",
     "render_haystacks",
     "render_stats",
@@ -147,6 +149,7 @@ __all__ = [
     "tool_name_matches",
     "toolcall_parse_view",
     "toolresult_parse_view",
+    "unregister_mcp_tool",
 ]
 
 @typing.final
@@ -1131,6 +1134,11 @@ class OtherCall(ToolCallBase):
     __match_args__: typing.ClassVar[tuple[str, ...]]
     @property
     def name(self) -> builtins.str: ...
+    @property
+    def error(self) -> typing.Optional[builtins.str]:
+        r"""
+        The strict-parse failure this call degraded from; None when the payload was well-formed but the tool has no typed model.
+        """
 
 @typing.final
 class OtherEvent:
@@ -1514,6 +1522,27 @@ class SkillResult(ToolResultBase):
     @property
     def allowed_tools(self) -> tuple[str, ...] | None: ...
 
+@typing.final
+class SpanEditCall(ToolCallBase):
+    r"""
+    An in-place file edit addressed by an opaque locator.
+
+    A registered MCP tool whose spec carries a span-edit lowering. The payload
+    carries no pre-image, so :func:`hunks_of` yields no hunk; ``new`` is ``None``
+    when the call deletes rather than writes. Registrations are process-local.
+
+    Attributes:
+        file_path: The file the edit targets.
+        new: The written content, or ``None`` when the call is a deletion.
+    """
+    __match_args__: typing.ClassVar[tuple[str, ...]]
+    @property
+    def name(self) -> builtins.str: ...
+    @property
+    def file_path(self) -> builtins.str: ...
+    @property
+    def new(self) -> typing.Optional[builtins.str]: ...
+
 @typing.final
 class SpecMatcher:
     def __new__(cls, spec_json: builtins.str) -> SpecMatcher: ...
@@ -2147,6 +2176,8 @@ def hunks_of(call: tools.ToolCall | tools.FallbackCall) -> tuple[Hunk, ...]:
 
     MultiEdit yields one hunk per span in application order — never just the
     first. Write and NotebookEdit are pure additions with an empty old side.
+    :class:`~SpanEditCall` yields none: its payload carries no
+    pre-image, so no honest hunk can be derived.
     """
 
 def ids_canonical_json(value_json: builtins.str) -> builtins.str: ...
@@ -2166,19 +2197,16 @@ def matches_names(actual: builtins.str, names: collections.abc.Container[str]) -
     Whether ``actual`` is one of ``names``, exactly or as an MCP tool suffix.
 
     True when ``actual`` is in ``names``, or when it splits as
-    ``mcp__<server>__<tool>`` on the first two ``__`` and ``<tool>`` — or its
-    native built-in edit-gate equivalent — is in ``names``. That alias closes
-    the edit-gate bypass where cc-context's ``ccx_code_edit`` /
-    ``ccx_code_replace`` write through the MCP under names no ``Edit``/``Write``
-    gate would catch. Display-name aliases from
-    :data:`~tools.TOOL_ALIASES` are not closed over — ``names`` is
-    taken verbatim; pre-expand with :func:`expand_tool_names` for those.
+    ``mcp__<server>__<tool>`` on the first two ``__`` and ``<tool>`` — or the
+    built-in gate its registered spec ``behaves_like`` — is in ``names``. That
+    closure lets a registered MCP tool (e.g. one that gates as ``Edit``) match an
+    ``Edit`` gate even under a name no built-in gate would catch. Display-name
+    aliases from :data:`~tools.TOOL_ALIASES` are not closed over —
+    ``names`` is taken verbatim; pre-expand with :func:`expand_tool_names` for those.
 
     Example:
         >>> matches_names("mcp__github__Grep", {"Grep"})
         True
-        >>> matches_names("mcp__cc-context__ccx_code_edit", {"Edit"})
-        True
         >>> matches_names("Execute", {"Bash"})
         False
     """
@@ -2230,6 +2258,16 @@ def parse_print_result(raw: bytes) -> PrintResult: ...
 
 def query_session(path: builtins.str, max_events: builtins.int) -> dict[str, typing.Any]: ...
 
+def register_mcp_tool(tool: builtins.str, behaves_like: builtins.str, span_edit: collections.abc.Mapping[str, str] | None = None) -> None:
+    r"""
+    Register an MCP tool spec, keyed by its bare segment; last write wins.
+
+    ``behaves_like`` names the built-in gate the tool matches. ``span_edit``, when
+    given, maps the payload key names — ``path``, ``content``, and optionally
+    ``delete`` — the tool's :class:`~SpanEditCall` lowering
+    reads. Registrations are process-local.
+    """
+
 def render_compact_lines(raw: bytes, width: builtins.int, thinking: builtins.bool, uuids: builtins.bool) -> builtins.list[builtins.str]: ...
 
 def render_haystacks(raw: bytes, wheres: typing.Sequence[builtins.str]) -> builtins.list[builtins.str]: ...
@@ -2275,3 +2313,8 @@ def toolresult_parse_view(name: builtins.str, payload_json: builtins.str) -> too
     the typed view hierarchy; the ``cc_transcript.tools`` facade owns the public
     signature.
     """
+
+def unregister_mcp_tool(tool: builtins.str) -> builtins.bool:
+    r"""
+    Unregister an MCP tool by its bare segment; returns whether it was registered.
+    """

{cc_transcript-14.2.0 → cc_transcript-14.4.0}/cc_transcript/mining/spec.py

@@ -65,10 +65,23 @@ ALL_DETECTORS: frozenset[DetectorName] = frozenset(
     }
 )
 
-EDIT_TOOLS: frozenset[str] = expand_tool_names("Edit|Write|MultiEdit|NotebookEdit")
-SUBAGENT_TOOLS: frozenset[str] = expand_tool_names("Agent|Task")
-PLAN_TOOLS: frozenset[str] = expand_tool_names("ExitPlanMode")
-DENIAL_EXCLUDED_TOOLS: frozenset[str] = expand_tool_names("ExitPlanMode|AskUserQuestion")
+# Expanded lazily (module __getattr__ and the spec fields' default_factory), so an
+# MCP tool registered after import but before spec build lands in the name sets.
+_TOOL_SETS: dict[str, str] = {
+    "EDIT_TOOLS": "Edit|Write|MultiEdit|NotebookEdit",
+    "SUBAGENT_TOOLS": "Agent|Task",
+    "PLAN_TOOLS": "ExitPlanMode",
+    "DENIAL_EXCLUDED_TOOLS": "ExitPlanMode|AskUserQuestion",
+}
+
+
+def __getattr__(name: str) -> frozenset[str]:
+    try:
+        return expand_tool_names(_TOOL_SETS[name])
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+
+
 REENTRY_LOOKBACK = 40
 CONFIDENCE_STEP = 0.25
 SHORT_FOLLOWUP_MAX_WORDS = 2
@@ -168,7 +181,7 @@ USER_MESSAGE_SPEC = ConfidenceSpec(
 class ProvenanceSpec:
     """Names the subagent tools whose tool results classify as ``claude`` provenance."""
 
-    subagent_tools: frozenset[str] = SUBAGENT_TOOLS
+    subagent_tools: frozenset[str] = field(default_factory=lambda: expand_tool_names(_TOOL_SETS["SUBAGENT_TOOLS"]))
 
 
 @dataclass(frozen=True, slots=True)
@@ -259,9 +272,11 @@ class MiningSpec:
     provenance: ProvenanceSpec = field(default_factory=ProvenanceSpec)
     review: ReviewSpec = field(default_factory=ReviewSpec)
     reentry_lookback: int = REENTRY_LOOKBACK
-    edit_tools: frozenset[str] = EDIT_TOOLS
-    plan_tools: frozenset[str] = PLAN_TOOLS
-    denial_excluded_tools: frozenset[str] = DENIAL_EXCLUDED_TOOLS
+    edit_tools: frozenset[str] = field(default_factory=lambda: expand_tool_names(_TOOL_SETS["EDIT_TOOLS"]))
+    plan_tools: frozenset[str] = field(default_factory=lambda: expand_tool_names(_TOOL_SETS["PLAN_TOOLS"]))
+    denial_excluded_tools: frozenset[str] = field(
+        default_factory=lambda: expand_tool_names(_TOOL_SETS["DENIAL_EXCLUDED_TOOLS"])
+    )
 
 
 def bump(signal: CandidateSignal, delta: float, reason: str) -> CandidateSignal:

{cc_transcript-14.2.0 → cc_transcript-14.4.0}/cc_transcript/parser.py

@@ -108,9 +108,39 @@ def parse_event(data: Mapping[str, Any]) -> TranscriptEvent | None:
 
 
 def parse_events_from_bytes(raw: bytes) -> list[TranscriptEvent]:
+    """Parse a JSONL transcript byte buffer into typed native events.
+
+    Compositionality contract: parsing splits on newlines and folds each line
+    independently, so for any split of ``raw`` on a line boundary,
+    ``parse_events_from_bytes(prefix) + parse_events_from_bytes(suffix)`` equals
+    ``parse_events_from_bytes(prefix + suffix)`` — value equality on the views'
+    structural ``__eq__``. Each call owns its buffer; no state carries across calls.
+    Blank, undecodable, and non-mapping lines are skipped identically wherever the
+    split falls, and an unterminated final line parses the same as a terminated one.
+    A line that fails typed parsing — a JSON object missing a required field —
+    raises identically wherever the split falls: the side containing that line
+    raises, so the equation above applies to inputs that parse. Splits inside a
+    line are out of contract: a mid-line split is not a line boundary, and the
+    fragments may parse differently than the whole line.
+
+    Incremental consumers — tail parsers re-parsing an appended slice cut on a
+    newline boundary — may rely on this contract; it is pinned by the line-boundary
+    sweep in ``tests/test_parser.py``.
+    """
     return list(_native.parse_bytes(raw).events)
 
 
+def parse_events(*lines: Mapping[str, Any]) -> list[TranscriptEvent]:
+    """Parse raw transcript-line mappings into typed native events.
+
+    Serializes each mapping to a JSONL line and folds them through the native
+    backend — the same path :func:`parse_events_from_bytes` and production use — so
+    the result is a list of lazy views over a multi-line parse. Lines the tolerant
+    parser drops (a below-``MINYEAR`` timestamp) never materialize.
+    """
+    return parse_events_from_bytes(b"\n".join(orjson.dumps(dict(line)) for line in lines))
+
+
 def parse_print_result(raw: bytes) -> PrintResult:
     """Parse a 'claude -p --output-format json' payload into a :class:`~cc_transcript.models.PrintResult`.
 

cc_transcript-14.4.0/cc_transcript/synthetic.py

@@ -0,0 +1,219 @@
+"""Synthetic transcript builders — hand-assembled JSONL that parses into real events.
+
+The v14 view model has no Python constructors, so tests and tools can no longer
+hand-build ``UserEvent``/``ToolUseBlock``/… objects. Instead they synthesize the
+JSONL a real transcript carries and parse it through the native backend — the exact
+path production uses. The ``*_line`` builders assemble the raw envelope dicts
+(mirroring the fields Claude Code emits), the block builders emit the
+``message.content`` entries the parser lifts into block views, and
+:func:`synthetic_user_event`/:func:`synthetic_assistant_event` round-trip a single
+envelope through :func:`~cc_transcript.parser.parse_events` into one native event.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any
+
+from cc_transcript.models import AssistantEvent, UserEvent
+from cc_transcript.parser import parse_events
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+BASE = datetime(2026, 1, 1, 12, 0, 0, tzinfo=UTC)
+
+Content = str | list[dict[str, Any]]
+
+
+def text_block(text: str) -> dict[str, Any]:
+    """A ``text`` content block carrying ``text``."""
+    return {"type": "text", "text": text}
+
+
+def thinking_block(thinking: str) -> dict[str, Any]:
+    """A ``thinking`` content block carrying ``thinking``."""
+    return {"type": "thinking", "thinking": thinking}
+
+
+def tool_use(id: str, name: str, input: Mapping[str, Any]) -> dict[str, Any]:
+    """A ``tool_use`` content block invoking ``name`` with ``input`` under id ``id``."""
+    return {"type": "tool_use", "id": id, "name": name, "input": dict(input)}
+
+
+def tool_result(tool_use_id: str, content: Content = "ok", *, is_error: bool = False) -> dict[str, Any]:
+    """A ``tool_result`` content block for ``tool_use_id``; ``is_error`` marks a failed call."""
+    return {"type": "tool_result", "tool_use_id": tool_use_id, "content": content, "is_error": is_error}
+
+
+def meta_fields(
+    uuid: str,
+    *,
+    session_id: str = "s",
+    timestamp: datetime = BASE,
+    secs: int = 0,
+    parent_uuid: str | None = None,
+    cwd: str | None = "/repo",
+    git_branch: str | None = "main",
+    version: str | None = "1.2.3",
+    is_sidechain: bool = False,
+    is_meta: bool = False,
+    entrypoint: str | None = "cli",
+    is_compact_summary: bool = False,
+    is_visible_in_transcript_only: bool = False,
+    user_type: str | None = None,
+    slug: str | None = None,
+) -> dict[str, Any]:
+    """The envelope-level fields the parser lifts into :class:`~cc_transcript.models.EntryMeta`.
+
+    Optional string fields are omitted when ``None`` so the parser's ``.get`` chains
+    reproduce a ``None`` attribute; booleans always serialize.
+    """
+    fields: dict[str, Any] = {
+        "uuid": uuid,
+        "sessionId": session_id,
+        "timestamp": (timestamp + timedelta(seconds=secs)).isoformat(),
+        "isSidechain": is_sidechain,
+        "isMeta": is_meta,
+        "isCompactSummary": is_compact_summary,
+        "isVisibleInTranscriptOnly": is_visible_in_transcript_only,
+    }
+    for key, value in (
+        ("parentUuid", parent_uuid),
+        ("cwd", cwd),
+        ("gitBranch", git_branch),
+        ("version", version),
+        ("entrypoint", entrypoint),
+        ("userType", user_type),
+        ("slug", slug),
+    ):
+        if value is not None:
+            fields[key] = value
+    return fields
+
+
+def user_line(
+    uuid: str,
+    text: str = "",
+    *,
+    blocks: Sequence[dict[str, Any]] = (),
+    tool_use_result: Mapping[str, Any] | str | None = None,
+    tool_denial_kind: str | None = None,
+    interrupted: bool = False,
+    **meta_kw: Any,
+) -> dict[str, Any]:
+    """A ``type: user`` envelope; ``blocks`` are ``message.content`` entries.
+
+    With ``blocks`` the content is a list — ``text`` (when non-empty) becomes a
+    leading text block, exactly as a real transcript carries it. ``interrupted``
+    sets ``interruptedMessageId`` so the parser derives ``interrupted=True``.
+    """
+    content: Content = ([text_block(text)] if text else []) + list(blocks) if blocks else text
+    line: dict[str, Any] = {"type": "user", "message": {"role": "user", "content": content}} | meta_fields(
+        uuid, **meta_kw
+    )
+    if tool_use_result is not None:
+        line["toolUseResult"] = tool_use_result
+    if tool_denial_kind is not None:
+        line["toolDenialKind"] = tool_denial_kind
+    if interrupted:
+        line["interruptedMessageId"] = f"imid-{uuid}"
+    return line
+
+
+def assistant_line(
+    uuid: str,
+    text: str = "",
+    *,
+    model: str = "claude-opus-4-7",
+    blocks: Sequence[dict[str, Any]] = (),
+    stop_reason: str | None = None,
+    usage: Mapping[str, Any] | None = None,
+    **meta_kw: Any,
+) -> dict[str, Any]:
+    """An ``type: assistant`` envelope; ``blocks`` are ``message.content`` entries."""
+    content = ([text_block(text)] if text else []) + list(blocks)
+    message: dict[str, Any] = {"role": "assistant", "model": model, "content": content}
+    if stop_reason is not None:
+        message["stop_reason"] = stop_reason
+    if usage is not None:
+        message["usage"] = dict(usage)
+    return {"type": "assistant", "message": message} | meta_fields(uuid, **meta_kw)
+
+
+def mode_line(value: str, *, session_id: str = "s", channel: str = "mode") -> dict[str, Any]:
+    """A ``mode``/``permission-mode`` envelope the parser lifts into :class:`~cc_transcript.models.ModeEvent`."""
+    key = "permissionMode" if channel == "permission-mode" else "mode"
+    return {"type": channel, "sessionId": session_id, key: value}
+
+
+def system_line(subtype: str, *, content: str | None = None, level: str | None = None, **fields: Any) -> dict[str, Any]:
+    """A ``type: system`` envelope; ``fields`` carry the subtype-specific detail keys."""
+    line: dict[str, Any] = {"type": "system", "subtype": subtype} | meta_fields(fields.pop("uuid", "sys")) | fields
+    if content is not None:
+        line["content"] = content
+    if level is not None:
+        line["level"] = level
+    return line
+
+
+def other_line(type: str, **fields: Any) -> dict[str, Any]:
+    """An unmodeled-``type`` envelope lifted into :class:`~cc_transcript.models.OtherEvent`; ``raw`` is the line."""
+    return {"type": type} | fields
+
+
+def synthetic_user_event(
+    text: str = "",
+    *,
+    blocks: Sequence[Mapping[str, Any]] = (),
+    uuid: str = "synthetic",
+    **meta: Any,
+) -> UserEvent:
+    """Builds a native :class:`~cc_transcript.models.UserEvent` from text or content blocks.
+
+    Serializes a ``user`` envelope and parses it through the native backend, so the
+    result is a real view accepted anywhere parsed events are — including
+    :meth:`~cc_transcript.activity.SessionActivity.from_events`. Extra keywords forward
+    to the envelope metadata (``session_id``, ``timestamp``, …).
+
+    Example:
+        >>> synthetic_user_event("fix the bug", session_id="s1").text
+        'fix the bug'
+
+    Raises:
+        ValueError: When the envelope does not parse to exactly one ``UserEvent``.
+    """
+    events = parse_events(user_line(uuid, text, blocks=[dict(block) for block in blocks], **meta))
+    match events:
+        case [UserEvent() as event]:
+            return event
+    raise ValueError(f"expected one UserEvent, got {[type(event).__name__ for event in events]}")
+
+
+def synthetic_assistant_event(
+    text: str = "",
+    *,
+    blocks: Sequence[Mapping[str, Any]] = (),
+    uuid: str = "synthetic",
+    **meta: Any,
+) -> AssistantEvent:
+    """Builds a native :class:`~cc_transcript.models.AssistantEvent` from text or content blocks.
+
+    Serializes an ``assistant`` envelope and parses it through the native backend, so
+    the result is a real view accepted anywhere parsed events are — including
+    :meth:`~cc_transcript.activity.SessionActivity.from_events`. Extra keywords forward
+    to the envelope metadata (``session_id``, ``timestamp``, …) and message fields
+    (``stop_reason``, ``usage``, ``model``).
+
+    Example:
+        >>> synthetic_assistant_event("on it", stop_reason="end_turn").text
+        'on it'
+
+    Raises:
+        ValueError: When the envelope does not parse to exactly one ``AssistantEvent``.
+    """
+    events = parse_events(assistant_line(uuid, text, blocks=[dict(block) for block in blocks], **meta))
+    match events:
+        case [AssistantEvent() as event]:
+            return event
+    raise ValueError(f"expected one AssistantEvent, got {[type(event).__name__ for event in events]}")