llm-tool-cli 0.2.0__py3-none-any.whl

llm_tool_cli/protocol/logic_cells/tests/test_environment_error.py

@@ -0,0 +1,130 @@
+from decimal import Decimal
+from pathlib import Path
+
+import pytest
+
+from llm_tool_cli.core.errors import EnvironmentError
+from llm_tool_cli.protocol import Protocol
+from llm_tool_cli.protocol.logic_cells import EnvironmentErrorCell
+from llm_tool_cli.protocol.output_cells import AutomationOutputCell, HumanErrorOutputCell, LLMOutputCell
+from llm_tool_cli.protocol.output_cells.base import OutputCell
+
+
+class ContextFailure(EnvironmentError):
+    path: Path
+    labels: list[str]
+    retryable: bool
+    attempts: int
+    detail: str | None
+    amount: Decimal
+
+
+class TestEnvironmentErrorCell:
+    def test_to_journal_record__keeps_structured_error_without_private_cause(self) -> None:
+        error = ContextFailure(
+            code="unavailable",
+            message="{error.path}: failed",
+            path=Path("/project"),
+            labels=["first"],
+            retryable=False,
+            attempts=0,
+            detail=None,
+            amount=Decimal("1.5"),
+        ).with_cause(OSError("private"))
+        original = error.model_dump()
+        record = EnvironmentErrorCell(error=error).to_journal_record()
+        assert record.message == "/project: failed"
+        assert record.attributes == {
+            "type": "error",
+            "code": "unavailable",
+            "path": "/project",
+            "labels": ["first"],
+            "retryable": False,
+            "attempts": 0,
+            "detail": None,
+            "amount": "1.5",
+        }
+        assert error.model_dump() == original
+
+    @pytest.mark.parametrize(
+        ("protocol", "output_type"),
+        [
+            (Protocol.human, HumanErrorOutputCell),
+            (Protocol.llm, LLMOutputCell),
+            (Protocol.automation, AutomationOutputCell),
+        ],
+    )
+    def test_render__retains_typed_error_and_projects_serialized_context(
+        self, protocol: Protocol, output_type: type[OutputCell]
+    ) -> None:
+        error = ContextFailure(
+            code="unavailable",
+            message="{error.path}: café\nTry again.",
+            path=Path("/project"),
+            labels=["one", "two"],
+            retryable=False,
+            attempts=0,
+            detail=None,
+            amount=Decimal("1.5"),
+        ).with_cause(OSError("private"))
+        original = error.model_dump()
+        logic_cell = EnvironmentErrorCell(error=error)
+
+        cells = logic_cell.render(protocol)
+
+        assert isinstance(logic_cell.error, ContextFailure)
+        assert logic_cell.error.path == Path("/project")
+        assert len(cells) == 1
+        cell = cells[0]
+        assert isinstance(cell, output_type)
+        assert cell.kind == "error"
+        assert cell.media_type == "text/markdown"
+        assert cell.content == "/project: café\nTry again."
+        assert cell.meta == {
+            "type": "error",
+            "code": "unavailable",
+            "path": "/project",
+            "labels": ["one", "two"],
+            "retryable": False,
+            "attempts": 0,
+            "detail": None,
+            "amount": "1.5",
+        }
+        assert error.model_dump() == original
+        assert logic_cell.error.model_dump() == original
+        assert isinstance(logic_cell.error.cause, OSError)
+
+    @pytest.mark.parametrize("protocol", list(Protocol))
+    @pytest.mark.parametrize(
+        ("guidance", "suffix"),
+        [
+            ([], ""),
+            ([" Retry {error.code}. "], "\nWay to fix: Retry unavailable."),
+            (
+                [" Retry {error.code}. ", "Check configuration."],
+                "\n\nWays to fix:\n\n- Retry unavailable.\n- Check configuration.",
+            ),
+        ],
+    )
+    def test_render__includes_formatted_guidance(self, protocol: Protocol, guidance: list[str], suffix: str) -> None:
+        error = EnvironmentError(code="unavailable", message="Service unavailable", ways_to_fix=guidance)
+        original = error.model_dump()
+
+        cell = EnvironmentErrorCell(error=error).render(protocol)[0]
+
+        assert cell.content == "Service unavailable" + suffix
+        assert cell.meta == {"type": "error", "code": "unavailable"}
+        assert error.model_dump() == original
+
+    @pytest.mark.parametrize("protocol", list(Protocol))
+    def test_render__recomputes_output_with_fresh_identifiers(self, protocol: Protocol) -> None:
+        error = EnvironmentError(code="empty", message="")
+        cell = EnvironmentErrorCell(error=error)
+
+        first = cell.render(protocol)[0]
+        second = cell.render(protocol)[0]
+
+        assert first.id != second.id
+        assert first.model_dump(exclude={"id"}) == second.model_dump(exclude={"id"})
+        assert first.content == ""
+        assert first.meta == {"type": "error", "code": "empty"}

llm_tool_cli/protocol/logic_cells/tests/test_journal.py

@@ -0,0 +1,47 @@
+import json
+
+import pytest
+
+from llm_tool_cli.core.settings import ToolLabel
+from llm_tool_cli.protocol import Protocol
+from llm_tool_cli.protocol.logic_cells.journal import JournalCell
+from llm_tool_cli.protocol.output_cells.base import RenderContext
+
+
+class TestJournalCell:
+    def test_to_journal_record__preserves_timestamp_and_subclass_fields(self) -> None:
+        class EventCell(JournalCell):
+            task_id: str | None = None
+
+        cell = EventCell(message="event", actor_id="actor", task_id="T-1", is_warning=True)
+        original = cell.model_dump()
+        record = cell.to_journal_record()
+        assert record.timestamp == cell.timestamp
+        assert record.message == cell.message
+        assert record.actor_id == "actor"
+        assert record.attributes == {"task_id": "T-1"}
+        assert cell.model_dump() == original
+
+    @pytest.mark.parametrize("protocol", list(Protocol))
+    def test_render__uses_normalized_multiline_data_and_emits_one_line(self, protocol: Protocol) -> None:
+        message = "  first\nsecond\rthird\\n  "
+        cell = JournalCell(message=message, actor_id="  actor\nname  ")
+        context = RenderContext(index=0, total=1, tool_label=ToolLabel("TEST"))
+        rendered = cell.render(protocol)[0].render(context).decode()
+        assert cell.message == message.strip()
+        assert len(rendered.splitlines()) == 1
+        if protocol == Protocol.automation:
+            record = json.loads(rendered)
+            assert record["message"] == message.strip()
+            assert record["actor_id"] == "actor\nname"
+            assert "is_journal" not in record
+            assert "is_warning" not in record
+        else:
+            assert r"first\nsecond\rthird\\n" in rendered
+            assert r"actor\nname" in rendered
+
+    def test_render__absent_actor_and_empty_message(self) -> None:
+        cell = JournalCell(message="")
+        context = RenderContext(index=0, total=1, tool_label=ToolLabel("TEST"))
+        for protocol in [Protocol.human, Protocol.llm]:
+            assert "<->" in cell.render(protocol)[0].render(context).decode()

llm_tool_cli/protocol/logic_cells/tests/test_uniform.py

@@ -0,0 +1,60 @@
+import pytest
+from pytest_mock import MockerFixture
+
+from llm_tool_cli.protocol import Protocol
+from llm_tool_cli.protocol.errors import JournalConversionUnsupported
+from llm_tool_cli.protocol.logic_cells.uniform import UniformCell
+from llm_tool_cli.protocol.output_cells import AutomationOutputCell, HumanOutputCell, LLMOutputCell
+from llm_tool_cli.protocol.output_cells.base import OutputCell
+
+
+class ExampleUniformCell(UniformCell):
+    items: tuple[str, ...]
+
+    def _render(self, cell_type: type[OutputCell]) -> OutputCell:
+        return cell_type.build_markdown(kind="items", content="\n".join(self.items), items=list(self.items))
+
+
+class TestUniformCell:
+    def test_to_journal_record__does_not_fall_back_to_rendering(self, mocker: MockerFixture) -> None:
+        cell = ExampleUniformCell(items=("first", "second"))
+        render = mocker.spy(ExampleUniformCell, "_render")
+
+        with pytest.raises(JournalConversionUnsupported):
+            cell.to_journal_record()
+
+        render.assert_not_called()
+
+    @pytest.mark.parametrize(
+        ("protocol", "cell_type"),
+        [
+            (Protocol.human, HumanOutputCell),
+            (Protocol.llm, LLMOutputCell),
+            (Protocol.automation, AutomationOutputCell),
+        ],
+    )
+    @pytest.mark.parametrize("items", [(), ("first", "café")])
+    def test_render__projects_one_fresh_cell_without_mutating_input(
+        self, protocol: Protocol, cell_type: type[OutputCell], items: tuple[str, ...]
+    ) -> None:
+        cell = ExampleUniformCell(items=items)
+        original = cell.model_dump()
+
+        first = cell.render(protocol)
+        second = cell.render(protocol)
+
+        assert len(first) == len(second) == 1
+        assert isinstance(first[0], cell_type)
+        assert isinstance(second[0], cell_type)
+        assert (
+            first[0].model_dump(exclude={"id"})
+            == second[0].model_dump(exclude={"id"})
+            == {
+                "kind": "items",
+                "media_type": "text/markdown",
+                "content": "\n".join(items),
+                "meta": {"items": list(items)},
+            }
+        )
+        assert first[0].id != second[0].id
+        assert cell.model_dump() == original

llm_tool_cli/protocol/logic_cells/tests/test_warning.py

@@ -0,0 +1,34 @@
+import pytest
+
+from llm_tool_cli.protocol import Protocol
+from llm_tool_cli.protocol.logic_cells.warning import WarningCell
+from llm_tool_cli.protocol.output_cells import AutomationOutputCell, HumanWarningOutputCell, LLMOutputCell
+from llm_tool_cli.protocol.output_cells.base import OutputCell
+
+
+class TestWarningCell:
+    def test_to_journal_record__retains_warning_message(self) -> None:
+        cell = WarningCell(message="first\nsecond", is_journal=True)
+        record = cell.to_journal_record()
+        assert record.message == "first\nsecond"
+        assert record.attributes == {"type": "warning"}
+
+    @pytest.mark.parametrize(
+        ("protocol", "output_type"),
+        [
+            (Protocol.human, HumanWarningOutputCell),
+            (Protocol.llm, LLMOutputCell),
+            (Protocol.automation, AutomationOutputCell),
+        ],
+    )
+    def test_render__preserves_warning_payload_without_delivery_flags(
+        self, protocol: Protocol, output_type: type[OutputCell]
+    ) -> None:
+        cell = WarningCell(message="first\nsecond", is_warning=False)
+        rendered = cell.render(protocol)
+        assert len(rendered) == 1
+        assert isinstance(rendered[0], output_type)
+        assert rendered[0].kind == "warning"
+        assert rendered[0].content is None
+        assert rendered[0].meta == {"type": "warning", "message": "first\nsecond"}
+        assert "is_warning" not in cell.model_dump()

llm_tool_cli/protocol/logic_cells/uniform.py

@@ -0,0 +1,21 @@
+from abc import abstractmethod
+
+from llm_tool_cli.protocol.logic_cells.base import LogicCell
+from llm_tool_cli.protocol.output_cells import AutomationOutputCell, HumanOutputCell, LLMOutputCell
+from llm_tool_cli.protocol.output_cells.base import OutputCell
+
+
+class UniformCell(LogicCell):
+    """One output cell with the same payload in each output protocol."""
+
+    def render_human(self) -> list[OutputCell]:
+        return [self._render(HumanOutputCell)]
+
+    def render_llm(self) -> list[OutputCell]:
+        return [self._render(LLMOutputCell)]
+
+    def render_automation(self) -> list[OutputCell]:
+        return [self._render(AutomationOutputCell)]
+
+    @abstractmethod
+    def _render(self, cell_type: type[OutputCell]) -> OutputCell: ...  # noqa: E704

llm_tool_cli/protocol/logic_cells/warning.py

@@ -0,0 +1,22 @@
+import pydantic
+
+from llm_tool_cli.protocol.journal import JournalRecord
+from llm_tool_cli.protocol.logic_cells.uniform import UniformCell
+from llm_tool_cli.protocol.output_cells import HumanWarningOutputCell
+from llm_tool_cli.protocol.output_cells.base import OutputCell
+
+
+class WarningCell(UniformCell):
+    """A non-fatal diagnostic delivered after ordinary results."""
+
+    is_warning: bool = pydantic.Field(default=True, exclude=True)
+    message: str
+
+    def render_human(self) -> list[OutputCell]:
+        return [self._render(HumanWarningOutputCell)]
+
+    def to_journal_record(self) -> JournalRecord:
+        return JournalRecord(message=self.message, attributes={"type": "warning"})
+
+    def _render(self, cell_type: type[OutputCell]) -> OutputCell:
+        return cell_type.build_meta(kind="warning", type="warning", message=self.message)

llm_tool_cli/protocol/output_cells/__init__.py

@@ -0,0 +1,11 @@
+from llm_tool_cli.protocol.output_cells.automation import AutomationOutputCell
+from llm_tool_cli.protocol.output_cells.human import HumanErrorOutputCell, HumanOutputCell, HumanWarningOutputCell
+from llm_tool_cli.protocol.output_cells.llm import LLMOutputCell
+
+__all__ = [
+    "AutomationOutputCell",
+    "HumanErrorOutputCell",
+    "HumanOutputCell",
+    "HumanWarningOutputCell",
+    "LLMOutputCell",
+]

llm_tool_cli/protocol/output_cells/automation.py

@@ -0,0 +1,14 @@
+from llm_tool_cli.protocol import to_jsonl
+from llm_tool_cli.protocol.output_cells.base import MetaValue, OutputCell, RenderContext
+
+
+class AutomationOutputCell(OutputCell):
+    def render(self, context: RenderContext) -> bytes:
+        data: dict[str, MetaValue] = {"id": self.short_id}
+
+        for meta_key, meta_value in sorted(self.meta.items()):
+            data[meta_key] = meta_value
+
+        data["content"] = self.content.strip() if self.content else None
+
+        return to_jsonl(data).encode("utf-8")

llm_tool_cli/protocol/output_cells/base.py

@@ -0,0 +1,65 @@
+import base64
+import uuid
+from abc import ABC, abstractmethod
+from typing import Self
+
+import pydantic
+
+from llm_tool_cli.core.entities import BaseEntity
+
+MetaValue = str | int | bool | None | list[str]
+
+
+def to_meta_value(value: object) -> MetaValue:
+    if isinstance(value, (str, int, bool)) or value is None:
+        return value
+    if isinstance(value, list) and all(isinstance(item, str) for item in value):
+        return value
+
+    return str(value)
+
+
+class RenderContext(BaseEntity):
+    model_config = pydantic.ConfigDict(str_strip_whitespace=False)
+
+    index: int = pydantic.Field(ge=0)
+    total: int = pydantic.Field(ge=1)
+    tool_label: str
+
+    @pydantic.model_validator(mode="after")
+    def validate_position(self) -> Self:
+        if self.index >= self.total:
+            raise ValueError("Cell index must be smaller than the sequence size")
+        return self
+
+
+class OutputCell(BaseEntity, ABC):
+    id: uuid.UUID = pydantic.Field(default_factory=uuid.uuid4)
+    kind: str
+    media_type: str | None
+    content: str | None
+    meta: dict[str, MetaValue] = pydantic.Field(default_factory=dict)
+
+    @classmethod
+    def build(cls, kind: str, media_type: str | None, content: str | None, **meta: MetaValue) -> Self:
+        if media_type is None and content is not None:
+            from llm_tool_cli.protocol.errors import ContentWithoutMediaType
+
+            raise ContentWithoutMediaType()
+
+        return cls(kind=kind, media_type=media_type, content=content, meta=meta)
+
+    @classmethod
+    def build_meta(cls, kind: str, **meta: MetaValue) -> Self:
+        return cls.build(kind=kind, media_type=None, content=None, **meta)
+
+    @classmethod
+    def build_markdown(cls, kind: str, content: str, **meta: MetaValue) -> Self:
+        return cls.build(kind=kind, media_type="text/markdown", content=content, **meta)
+
+    @property
+    def short_id(self) -> str:
+        return base64.urlsafe_b64encode(self.id.bytes).rstrip(b"=").decode()
+
+    @abstractmethod
+    def render(self, context: RenderContext) -> bytes: ...  # noqa: E704

llm_tool_cli/protocol/output_cells/human.py

@@ -0,0 +1,24 @@
+from llm_tool_cli.protocol.output_cells.base import OutputCell, RenderContext
+
+
+class HumanOutputCell(OutputCell):
+    def render(self, context: RenderContext) -> bytes:
+        sections = [self._render_metadata(), (self.content or "").strip()]
+        text = "\n\n".join(section for section in sections if section) or self.kind
+        return (text + "\n\n").encode("utf-8")
+
+    def _render_metadata(self) -> str:
+        return "\n".join(
+            f"{key}: {value}" for key, value in sorted(self.meta.items()) if not (key == "type" and value == self.kind)
+        )
+
+
+class HumanErrorOutputCell(HumanOutputCell):
+    def render(self, context: RenderContext) -> bytes:
+        sections = [f"Error: {(self.content or '').strip()}".rstrip(), self._render_metadata()]
+        return ("\n\n".join(section for section in sections if section) + "\n\n").encode("utf-8")
+
+
+class HumanWarningOutputCell(HumanOutputCell):
+    def render(self, context: RenderContext) -> bytes:
+        return (f"Warning: {self.meta['message']}".rstrip() + "\n\n").encode("utf-8")

llm_tool_cli/protocol/output_cells/journal.py

@@ -0,0 +1,23 @@
+import pydantic
+
+from llm_tool_cli.protocol.output_cells.base import OutputCell, RenderContext
+from llm_tool_cli.protocol.serialization import to_jsonl
+
+
+class JournalTextOutputCell(OutputCell):
+    """Compact journal presentation without changing the logical message."""
+
+    model_config = pydantic.ConfigDict(str_strip_whitespace=False)
+
+    def render(self, context: RenderContext) -> bytes:
+        text = (self.content or "").replace("\\", "\\\\").replace("\r", "\\r").replace("\n", "\\n")
+        return (text + "\n").encode("utf-8")
+
+
+class JournalAutomationOutputCell(OutputCell):
+    """One structured journal record with its original field values."""
+
+    model_config = pydantic.ConfigDict(str_strip_whitespace=False)
+
+    def render(self, context: RenderContext) -> bytes:
+        return to_jsonl(self.meta).encode("utf-8")

llm_tool_cli/protocol/output_cells/llm.py

@@ -0,0 +1,25 @@
+from llm_tool_cli.protocol.output_cells.base import OutputCell, RenderContext
+
+
+class LLMOutputCell(OutputCell):
+    def render(self, context: RenderContext) -> bytes:  # noqa: CCR001
+        id = self.short_id
+
+        lines = [f"--{context.tool_label}-CELL {id} BEGIN--"]
+
+        lines.append(f"kind={self.kind}")
+
+        if self.media_type is not None:
+            lines.append(f"media_type={self.media_type}")
+
+        for meta_key, meta_value in sorted(self.meta.items()):
+            lines.append(f"{meta_key}={meta_value}")
+
+        if self.content:
+            lines.append("")
+            lines.append(self.content.strip())
+
+        lines.append(f"--{context.tool_label}-CELL {id} END--")
+        lines.append("")
+
+        return "\n".join(lines).encode()

llm_tool_cli/protocol/output_cells/tests/make.py

@@ -0,0 +1,15 @@
+import uuid
+
+from llm_tool_cli.protocol.output_cells.base import OutputCell
+
+
+def cell(cell_type: type[OutputCell], **kwargs: object) -> OutputCell:
+    values = {
+        "id": uuid.UUID("12345678-1234-5678-9234-567812345678"),
+        "kind": "sample_status",
+        "media_type": "text/markdown",
+        "content": "  Sample content.  ",
+        "meta": {"zeta": 2, "alpha": "first", "enabled": True, "missing": None},
+    }
+    values.update(kwargs)
+    return cell_type.model_validate(values)

llm_tool_cli/protocol/output_cells/tests/test_automation.py

@@ -0,0 +1,58 @@
+import json
+
+import pytest
+
+from llm_tool_cli.protocol.output_cells.automation import AutomationOutputCell
+from llm_tool_cli.protocol.output_cells.base import RenderContext
+from llm_tool_cli.protocol.output_cells.tests.make import cell
+
+
+class TestAutomationOutputCell:
+    def test_render__serializes_cell_as_sorted_json_line(self) -> None:
+        formatted = cell(
+            AutomationOutputCell,
+        ).render(RenderContext(index=0, total=1, tool_label="TOOL"))
+
+        assert json.loads(formatted) == {
+            "alpha": "first",
+            "content": "Sample content.",
+            "enabled": True,
+            "id": "EjRWeBI0VniSNFZ4EjRWeA",
+            "missing": None,
+            "zeta": 2,
+        }
+        assert formatted == (
+            b'{"alpha":"first","content":"Sample content.","enabled":true,'
+            b'"id":"EjRWeBI0VniSNFZ4EjRWeA","missing":null,"zeta":2}\n'
+        )
+
+    @pytest.mark.parametrize("content", [None, ""])
+    def test_render__serializes_missing_content_as_null(self, content: str | None) -> None:
+        formatted = cell(AutomationOutputCell, content=content).render(
+            RenderContext(index=0, total=1, tool_label="TOOL")
+        )
+
+        assert json.loads(formatted)["content"] is None
+
+    def test_render__preserves_metadata_field_precedence(self) -> None:
+        source = cell(AutomationOutputCell, content="Actual content", meta={"id": "metadata-id", "content": "ignored"})
+
+        formatted = source.render(RenderContext(index=0, total=1, tool_label="TOOL"))
+
+        assert json.loads(formatted) == {"id": "metadata-id", "content": "Actual content"}
+
+    def test_render__preserves_unicode_and_list_metadata(self) -> None:
+        source = cell(
+            AutomationOutputCell, content="日本語\nSecond line.", meta={"labels": ["一", "two"], "enabled": False}
+        )
+
+        formatted = source.render(RenderContext(index=0, total=1, tool_label="TOOL"))
+
+        assert json.loads(formatted) == {
+            "id": source.short_id,
+            "content": "日本語\nSecond line.",
+            "labels": ["一", "two"],
+            "enabled": False,
+        }
+        assert "日本語".encode() in formatted
+        assert len(formatted.splitlines()) == 1

llm_tool_cli/protocol/output_cells/tests/test_base.py

@@ -0,0 +1,86 @@
+import uuid
+
+import pydantic
+import pytest
+
+from llm_tool_cli.protocol.errors import ContentWithoutMediaType
+from llm_tool_cli.protocol.output_cells import HumanOutputCell
+from llm_tool_cli.protocol.output_cells.base import MetaValue, RenderContext, to_meta_value
+
+
+class TestToMetaValue:
+    @pytest.mark.parametrize(
+        ("value", "expected"),
+        (
+            ("value", "value"),
+            ("  Заметка  ", "  Заметка  "),
+            (1, 1),
+            (True, True),
+            (None, None),
+            ([], []),
+            (["first", " second "], ["first", " second "]),
+            (["first", 2], "['first', 2]"),
+            ({"count": 2}, "{'count': 2}"),
+            (1.5, "1.5"),
+            (uuid.UUID("12345678-1234-5678-9234-567812345678"), "12345678-1234-5678-9234-567812345678"),
+        ),
+    )
+    def test_converts_metadata_values(self, value: object, expected: MetaValue) -> None:
+        assert to_meta_value(value) == expected
+
+
+class TestOutputCell:
+    @pytest.mark.parametrize("content", ("content", ""))
+    def test_build__requires_media_type_when_content_is_present(self, content: str) -> None:
+        with pytest.raises(ContentWithoutMediaType):
+            HumanOutputCell.build(kind="status", media_type=None, content=content)
+
+    def test_build__stores_metadata_as_cell_metadata(self) -> None:
+        cell = HumanOutputCell.build(kind="status", media_type="text/plain", content="content", count=2, label="ready")
+
+        assert cell.meta == {"count": 2, "label": "ready"}
+
+    def test_build__accepts_media_type_without_content(self) -> None:
+        cell = HumanOutputCell.build(kind="status", media_type="text/plain", content=None)
+
+        assert cell.media_type == "text/plain"
+        assert cell.content is None
+
+    def test_build_meta__generates_fresh_uuid4_identifiers(self) -> None:
+        first = HumanOutputCell.build_meta(kind="status")
+        second = HumanOutputCell.build_meta(kind="status")
+
+        assert first.id.version == 4
+        assert second.id.version == 4
+        assert first.id != second.id
+
+    def test_build_meta__creates_contentless_cell(self) -> None:
+        cell = HumanOutputCell.build_meta(kind="status", count=0)
+
+        assert cell.media_type is None
+        assert cell.content is None
+        assert cell.meta == {"count": 0}
+
+    def test_build_markdown__uses_markdown_media_type(self) -> None:
+        cell = HumanOutputCell.build_markdown(kind="status", content="# Done", count=1)
+
+        assert cell.media_type == "text/markdown"
+        assert cell.meta == {"count": 1}
+
+    def test_short_id__returns_unpadded_urlsafe_base64_id(self) -> None:
+        cell = HumanOutputCell.build_meta(kind="status").replace(id=uuid.UUID("12345678-1234-5678-9234-567812345678"))
+
+        assert cell.short_id == "EjRWeBI0VniSNFZ4EjRWeA"
+
+
+class TestRenderContext:
+    @pytest.mark.parametrize(("index", "total"), [(-1, 1), (0, 0), (1, 1), (3, 2)])
+    def test_validate_position__rejects_invalid_sequence_position(self, index: int, total: int) -> None:
+        with pytest.raises(pydantic.ValidationError):
+            RenderContext(index=index, total=total, tool_label="TOOL")
+
+    @pytest.mark.parametrize(("index", "total"), [(0, 1), (0, 2), (1, 2)])
+    def test_validate_position__accepts_sequence_boundaries(self, index: int, total: int) -> None:
+        context = RenderContext(index=index, total=total, tool_label="TOOL")
+
+        assert (context.index, context.total) == (index, total)