zettcode-engine 0.3.4__py3-none-any.whl

zettcode/engine/export/__init__.py

@@ -0,0 +1,421 @@
+"""Render a stored session as a self-contained HTML trace.
+
+The page follows the shape a reader wants when they open a session: a sidebar of
+turns on the left, the selected turn's events on the right, each event a card
+holding the raw text it carried, the time it was written, and what it cost. The
+request the next turn would send is the last entry in the sidebar, so the file
+shows both what was said and what the model is carrying now.
+
+The document is one template: nothing is fetched, and every string reaches it
+through :func:`html.escape`. The only script is the handful of lines that switch
+the sidebar selection, and the page reads fine without it.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+from collections.abc import Sequence
+from dataclasses import dataclass, field, replace
+from datetime import datetime
+from functools import lru_cache
+from importlib.resources import files
+from pathlib import Path
+from string import Template
+
+from zett_agent.messages import AnyMessage, AssistantMessage, SystemMessage, ToolMessage, UserMessage
+
+from zettcode.relay import relay_of
+
+from ..dialogue.side import is_side_line
+from ..extensions.context import ContextReport
+from ..storage import MessageLine, Session
+
+#: Characters a block keeps inline before it collapses. The system prompt and
+#: long tool output are the only things that usually pass it.
+COLLAPSE_AFTER = 220
+
+#: Characters of a turn's opening user line the sidebar shows.
+TITLE_CHARS = 64
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    """One message as the trace shows it.
+
+    Attributes:
+        number: ``#N`` position in the whole session, in file order.
+        kind: What the message is, which decides its heading and its colour.
+        title: Heading the card prints.
+        text: Raw text the message carried; markup is escaped, never rendered.
+        reasoning: Reasoning that came with an assistant message, if any.
+        calls: Tool calls the message asked for, as ``(name, arguments)``.
+        ok: Whether a tool result succeeded; ``None`` for other messages.
+        created_at: When the message was written.
+        duration_ns: Wall time of the call that produced it, when one is known.
+        duplicate_of: Number of an earlier event with the same text, so a
+            repeated system instruction is pointed at rather than reprinted.
+    """
+
+    number: int
+    kind: str
+    title: str
+    text: str
+    reasoning: str = ""
+    calls: tuple[tuple[str, str], ...] = ()
+    ok: bool | None = None
+    created_at: datetime | None = None
+    duration_ns: int | None = None
+    duplicate_of: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Section:
+    """One entry in the sidebar and the panel it opens."""
+
+    label: str
+    title: str
+    stats: str
+    note: str = ""
+    events: tuple[Event, ...] = field(default=())
+
+
+@dataclass(frozen=True, slots=True)
+class Trace:
+    """The whole page: where it came from, and what it holds."""
+
+    title: str
+    subtitle: str
+    meta: tuple[tuple[str, str], ...]
+    sections: tuple[Section, ...]
+    tags: tuple[str, ...] = ()
+    exported_at: str = ""
+
+
+def build_trace(
+    session: Session,
+    *,
+    title: str = "",
+    subtitle: str = "",
+    meta: Sequence[tuple[str, str]] = (),
+    tags: Sequence[str] = (),
+    context_messages: Sequence[AnyMessage] = (),
+    tools: Sequence[str] = (),
+    report: ContextReport | None = None,
+) -> Trace:
+    """Group a stored branch into turns, and put the live context after them."""
+    events: list[Event] = []
+    seen: dict[str, int] = {}
+    for line in session.branch():
+        if is_side_line(line):
+            # A side question never joined the conversation, so it is not part of
+            # the record a reader is handed either.
+            continue
+        event = _event(len(events) + 1, line)
+        if event.text:
+            first = seen.setdefault(event.text, event.number)
+            if first != event.number:
+                event = replace(event, duplicate_of=first)
+        events.append(event)
+    sections = tuple(_sections(events)) + (_context_section(context_messages, tools, report),)
+    stored = session.header.session_id if session.header is not None else "session"
+    return Trace(
+        title=title or stored,
+        subtitle=subtitle,
+        meta=tuple(meta),
+        sections=tuple(section for section in sections if section.events),
+        tags=tuple(tags),
+    )
+
+
+@lru_cache(maxsize=1)
+def _assets() -> tuple[Template, str, str]:
+    """Read the document, its stylesheet, and its script, once per process.
+
+    They live beside this module as ordinary files — a page is easier to work on
+    as markup and CSS than as a Python string — and are folded back into one
+    document here, so what is exported still fetches nothing.
+    """
+    root = files("zettcode.engine.export").joinpath("trace")
+    template = Template(root.joinpath("template.html").read_text(encoding="utf-8"))
+    style = root.joinpath("style.css").read_text(encoding="utf-8")
+    script = root.joinpath("script.js").read_text(encoding="utf-8")
+    return template, style, script
+
+
+def render_html(trace: Trace) -> str:
+    """Return the whole page for one trace."""
+    template, style, script = _assets()
+    return template.substitute(
+        style=style,
+        script=script,
+        title=html.escape(trace.title),
+        subtitle=html.escape(trace.subtitle),
+        meta=_render_meta(trace.meta),
+        tags=_render_tags(trace.tags),
+        turns=str(len(trace.sections)),
+        summary=html.escape(_summary(trace)),
+        sidebar=_render_sidebar(trace.sections),
+        panels=_render_panels(trace.sections, _render_tags(trace.tags)),
+        exported_at=html.escape(trace.exported_at),
+    )
+
+
+def write_export(path: str | Path, content: str) -> Path:
+    """Write the page and return the absolute path that was written."""
+    target = Path(path).expanduser()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8")
+    return target.resolve()
+
+
+def _user_label(message: UserMessage) -> str:
+    """Return what a user message is called: a message another session sent says whose it is."""
+    relayed = relay_of(message.attributes, message.text)
+    return "User message" if relayed is None else f"Message from session {relayed.sender}"
+
+
+def _event(number: int, line: MessageLine) -> Event:
+    """Build the event one stored message becomes."""
+    message = line.message[0]
+    timing = line.timing
+    match message:
+        case SystemMessage():
+            return Event(number, "system", "System instruction", message.content, created_at=line.created_at)
+        case UserMessage():
+            return Event(number, "user", _user_label(message), message.text, created_at=line.created_at)
+        case AssistantMessage():
+            calls = tuple(
+                (call.name, json.dumps(call.arguments, ensure_ascii=False, sort_keys=True))
+                for call in message.tool_calls
+            )
+            return Event(
+                number,
+                "assistant",
+                "Model response",
+                message.content,
+                reasoning=message.reasoning or "",
+                calls=calls,
+                created_at=line.created_at,
+                duration_ns=timing.duration_ns,
+            )
+        case ToolMessage():
+            return Event(
+                number,
+                "tool",
+                "Tool result",
+                message.text,
+                ok=message.success,
+                created_at=line.created_at,
+                duration_ns=timing.duration_ns,
+            )
+        case _:
+            return Event(number, "other", type(message).__name__, repr(message), created_at=line.created_at)
+
+
+def _sections(events: Sequence[Event]) -> list[Section]:
+    """Split the session's events into turns, one per user message."""
+    turns: list[list[Event]] = []
+    for event in events:
+        if event.kind == "user" or not turns:
+            turns.append([])
+        turns[-1].append(event)
+    sections: list[Section] = []
+    for index, turn in enumerate(turns, start=1):
+        duration = sum(event.duration_ns or 0 for event in turn) / 1_000_000_000
+        opening = next((event for event in turn if event.kind == "user"), turn[0])
+        sections.append(
+            Section(
+                label=f"Turn {index}",
+                title=_title(opening.text),
+                stats=f"{len(turn)} events · {duration:.1f} s",
+                events=tuple(turn),
+            )
+        )
+    return sections
+
+
+def _context_section(
+    messages: Sequence[AnyMessage],
+    tools: Sequence[str],
+    report: ContextReport | None,
+) -> Section:
+    """Build the sidebar entry for the request the next turn would send."""
+    events: list[Event] = []
+    seen: dict[str, int] = {}
+    number = 0
+    for message in messages:
+        number += 1
+        event = _context_event(number, message)
+        first = seen.setdefault(event.text, event.number) if event.text else event.number
+        events.append(replace(event, duplicate_of=first) if first != event.number else event)
+    if tools:
+        number += 1
+        events.append(
+            Event(number, "tools", "Tools offered", "\n".join(tools)),
+        )
+    stats = f"{len(events)} messages"
+    note = f"{report.used:,} tokens" if report is not None else ""
+    if report is not None:
+        stats += f" · {report.used:,} tokens"
+    return Section(label="Context", title="Current request", stats=stats, note=note, events=tuple(events))
+
+
+def _context_event(number: int, message: AnyMessage) -> Event:
+    """Build the event one model-facing message becomes."""
+    match message:
+        case SystemMessage():
+            return Event(number, "system", "System instruction", message.content)
+        case AssistantMessage():
+            calls = tuple(
+                (call.name, json.dumps(call.arguments, ensure_ascii=False, sort_keys=True))
+                for call in message.tool_calls
+            )
+            return Event(
+                number, "assistant", "Model response", message.content, reasoning=message.reasoning or "", calls=calls
+            )
+        case ToolMessage():
+            return Event(number, "tool", "Tool result", message.text, ok=message.success)
+        case UserMessage():
+            return Event(number, "user", _user_label(message), message.text)
+        case _:
+            return Event(number, "other", type(message).__name__, repr(message))
+
+
+def _title(text: str) -> str:
+    """Return the one line a sidebar entry shows for a turn."""
+    line = next((part.strip() for part in text.splitlines() if part.strip()), "")
+    return line[:TITLE_CHARS] + ("…" if len(line) > TITLE_CHARS else "")
+
+
+def _summary(trace: Trace) -> str:
+    """Return the counts the top bar prints."""
+    events = sum(len(section.events) for section in trace.sections)
+    return f"{len(trace.sections)} sections · {events} events"
+
+
+def _render_meta(meta: Sequence[tuple[str, str]]) -> str:
+    """Return the sidebar's footer: one small label over each value."""
+    return "".join(f"<div><dt>{html.escape(label)}</dt><dd>{html.escape(value)}</dd></div>" for label, value in meta)
+
+
+def _render_sidebar(sections: Sequence[Section]) -> str:
+    """Return the turn buttons, the first one selected."""
+    buttons = []
+    for index, section in enumerate(sections):
+        note = f'<span class="note">{html.escape(section.note)}</span>' if section.note else ""
+        current = " is-current" if index == 0 else ""
+        buttons.append(
+            f'<button class="turn{current}" data-panel="panel-{index}" type="button">'
+            f'<span class="turn-top"><span class="label">{html.escape(section.label)}</span>{note}</span>'
+            f'<span class="turn-title">{html.escape(section.title)}</span>'
+            f'<span class="turn-stats">{html.escape(section.stats)}</span>'
+            "</button>"
+        )
+    return "".join(buttons)
+
+
+def _render_panels(sections: Sequence[Section], tags: str) -> str:
+    """Return one panel per section, the first one selected."""
+    panels = []
+    for index, section in enumerate(sections):
+        current = " is-current" if index == 0 else ""
+        panels.append(
+            f'<section class="panel{current}" id="panel-{index}">'
+            f'<header class="panel-head"><h2>{html.escape(section.label)}</h2>{tags}'
+            f'<span class="panel-stats">{html.escape(section.stats)}</span></header>'
+            f'<ol class="timeline">{"".join(_render_event(event) for event in section.events)}</ol>'
+            "</section>"
+        )
+    return "".join(panels)
+
+
+def _render_tags(tags: Sequence[str]) -> str:
+    """Return the model and effort chips every panel head carries."""
+    return "".join(f'<span class="chip">{html.escape(tag)}</span>' for tag in tags)
+
+
+def _render_event(event: Event) -> str:
+    """Return one event card: heading, metadata, then the text it carried."""
+    meta = [f"#{event.number}"]
+    if event.created_at is not None:
+        meta.append(event.created_at.astimezone().strftime("%H:%M:%S"))
+    if event.duration_ns:
+        meta.append(f"{event.duration_ns / 1_000_000_000:.2f} s")
+    if event.ok is not None:
+        meta.append("ok" if event.ok else "failed")
+    # A duplicate points at the text instead of repeating it, so it has none to copy.
+    copy = (
+        ""
+        if event.duplicate_of is not None
+        else f'<button class="copy" type="button" data-copy="{html.escape(event.text, quote=True)}">Copy</button>'
+    )
+    return (
+        '<li class="event">'
+        '<span class="dot"></span>'
+        '<div class="event-card">'
+        f'<div class="event-head"><h3 class="kind-{html.escape(event.kind)}">{html.escape(event.title)}</h3>{copy}</div>'
+        f'<p class="event-meta">{html.escape(" · ".join(meta))}</p>'
+        f"{_render_text(event)}"
+        f"{_render_reasoning(event)}"
+        f"{_render_calls(event)}"
+        "</div></li>"
+    )
+
+
+def _render_calls(event: Event) -> str:
+    """Return the tool calls an assistant message asked for."""
+    if not event.calls:
+        return ""
+    rows = "".join(
+        f'<div class="call"><span class="arrow">→</span>{html.escape(name)}({html.escape(arguments)})</div>'
+        for name, arguments in event.calls
+    )
+    return f'<div class="calls">{rows}</div>'
+
+
+def _render_text(event: Event) -> str:
+    """Return the event's text: inline when short, a collapsible block when long."""
+    if not event.text:
+        return ""
+    if event.duplicate_of is not None:
+        return f'<p class="duplicate">Same text as #{event.duplicate_of}.</p>'
+    if _is_block(event):
+        note = _block_note(event)
+        return (
+            f'<details class="block"><summary><span class="block-title">{html.escape(event.title)}</span>'
+            f'<span class="block-note">{html.escape(note)}</span></summary>'
+            f"<pre>{html.escape(event.text)}</pre></details>"
+        )
+    return f'<div class="body">{_render_inline(event.text)}</div>'
+
+
+def _render_reasoning(event: Event) -> str:
+    """Return the reasoning an assistant message carried, collapsed."""
+    if not event.reasoning:
+        return ""
+    note = f"{len(event.reasoning)} chars"
+    return (
+        f'<details class="block reasoning"><summary><span class="block-title">Reasoning</span>'
+        f'<span class="block-note">{note}</span></summary><pre>{html.escape(event.reasoning)}</pre></details>'
+    )
+
+
+def _is_block(event: Event) -> bool:
+    """Return whether the event's text starts collapsed.
+
+    The system prompt is furniture a reader skims past, and a wall of tool
+    output hides the rest of the turn; an answer with line breaks in it is what
+    the reader came for and stays open.
+    """
+    return event.kind == "system" or len(event.text) > COLLAPSE_AFTER
+
+
+def _block_note(event: Event) -> str:
+    """Return what a collapsed block shows beside its title."""
+    return f"{len(event.text)} chars"
+
+
+def _render_inline(text: str) -> str:
+    """Return short text with its line breaks kept and its markup escaped."""
+    return html.escape(text).replace("\n", "<br>")

zettcode/engine/export/trace/script.js

@@ -0,0 +1,18 @@
+document.documentElement.classList.add("js");
+var buttons = Array.prototype.slice.call(document.querySelectorAll(".turn"));
+var panels = Array.prototype.slice.call(document.querySelectorAll(".panel"));
+function show(id) {
+  buttons.forEach(function (button) { button.classList.toggle("is-current", button.dataset.panel === id); });
+  panels.forEach(function (panel) { panel.classList.toggle("is-current", panel.id === id); });
+}
+buttons.forEach(function (button) {
+  button.addEventListener("click", function () { show(button.dataset.panel); });
+});
+Array.prototype.slice.call(document.querySelectorAll(".copy")).forEach(function (button) {
+  button.addEventListener("click", function () {
+    navigator.clipboard.writeText(button.dataset.copy).then(function () {
+      button.textContent = "Copied";
+      setTimeout(function () { button.textContent = "Copy"; }, 1200);
+    });
+  });
+});

zettcode/engine/export/trace/style.css

@@ -0,0 +1,136 @@
+:root {
+  color-scheme: light dark;
+  --page: #f6f6f7; --card: #ffffff; --text: #1d1d1f; --muted: #86868b;
+  --line: #e6e6e8; --soft: #f1f1f3; --accent: #0071e3; --radius: 16px;
+  --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+}
+@media (prefers-color-scheme: dark) {
+  :root { --page: #0d0d0f; --card: #17171a; --text: #f5f5f7; --muted: #98989d; --line: #2a2a2e; --soft: #202024; }
+}
+* { box-sizing: border-box; }
+html, body { height: 100%; }
+body {
+  display: flex; flex-direction: column; overflow: hidden;
+  margin: 0; background: var(--page); color: var(--text);
+  font: 400 14px/1.55 -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+.topbar {
+  display: flex; align-items: center; gap: 12px; flex: none; height: 52px; padding: 0 22px;
+  background: var(--card); border-bottom: 1px solid var(--line);
+}
+.brand { font-weight: 600; }
+.crumb, .count { color: var(--muted); font-size: 12.5px; }
+.count { font-variant-numeric: tabular-nums; }
+.count:first-of-type { margin-left: auto; }
+.when { padding-left: 12px; border-left: 1px solid var(--line); }
+.app {
+  display: grid; grid-template-columns: 300px minmax(0, 1fr); gap: 22px; flex: 1; min-height: 0;
+  width: 100%; max-width: 1440px; margin: 0 auto; padding: 22px 22px 22px;
+}
+.sidebar { display: flex; flex-direction: column; min-height: 0; }
+.turns { flex: 1; min-height: 0; overflow-y: auto; padding-right: 4px; scrollbar-width: thin; }
+.turns::-webkit-scrollbar { width: 10px; }
+.turns::-webkit-scrollbar-track { background: transparent; }
+.turns::-webkit-scrollbar-thumb {
+  background: var(--line); border: 3px solid transparent; border-radius: 999px; background-clip: content-box;
+}
+.sidebar-head { flex: none; padding: 2px 6px 14px; }
+.kicker { color: var(--muted); font-size: 11px; font-weight: 500; letter-spacing: .07em; text-transform: uppercase; }
+.sidebar-head h1 { margin: 6px 0 4px; font-size: 15px; font-weight: 600; }
+.sidebar-head p { margin: 0; color: var(--muted); font-size: 12.5px; overflow-wrap: anywhere; }
+.turn {
+  display: flex; flex-direction: column; gap: 4px; width: 100%; margin: 0 0 6px; padding: 11px 13px;
+  text-align: left; font: inherit; color: var(--text); background: transparent;
+  border: 1px solid transparent; border-radius: 12px; cursor: pointer;
+}
+.turn:hover { background: var(--soft); }
+.turn.is-current { background: var(--card); border-color: var(--line); box-shadow: 0 1px 2px rgba(0,0,0,.05); }
+.turn-top { display: flex; align-items: center; gap: 8px; }
+.label { color: var(--muted); font-size: 11px; font-weight: 500; letter-spacing: .07em; text-transform: uppercase; }
+.note { margin-left: auto; font-family: var(--mono); font-size: 11px; color: var(--muted); }
+.turn-title { font-weight: 600; overflow-wrap: anywhere; }
+.turn-stats { color: var(--muted); font-size: 12px; }
+.sidebar-foot { flex: none; margin: 14px 6px 0; padding-top: 14px; border-top: 1px solid var(--line); }
+.sidebar-foot dt { color: var(--muted); font-size: 10.5px; font-weight: 500; letter-spacing: .07em; text-transform: uppercase; }
+.sidebar-foot dd { margin: 3px 0 10px; font-size: 12.5px; overflow-wrap: anywhere; }
+.trace { display: flex; flex-direction: column; min-height: 0; }
+.panel {
+  display: flex; flex-direction: column; min-height: 0; flex: 1;
+  padding: 20px 24px 24px; background: var(--card);
+  border: 1px solid var(--line); border-radius: var(--radius);
+  box-shadow: 0 1px 2px rgba(0,0,0,.04);
+}
+.js .panel { display: none; }
+.js .panel.is-current { display: flex; }
+.panel-head { flex: none; display: flex; align-items: center; gap: 10px; margin: 0 0 18px; }
+.panel-head h2 { margin: 0; font-size: 15px; font-weight: 600; }
+.chip { padding: 2px 9px; border-radius: 999px; background: var(--soft); color: var(--muted); font-size: 11px; }
+.panel-stats { margin-left: auto; color: var(--muted); font-size: 12px; font-variant-numeric: tabular-nums; }
+.timeline {
+  flex: 1; min-height: 0; overflow-y: auto; margin: 0; padding: 0 6px 0 0; list-style: none;
+  scrollbar-width: thin;
+}
+.timeline::-webkit-scrollbar { width: 10px; }
+.timeline::-webkit-scrollbar-track { background: transparent; }
+.timeline::-webkit-scrollbar-thumb {
+  background: var(--line); border: 3px solid transparent; border-radius: 999px; background-clip: content-box;
+}
+.event { position: relative; padding: 0 0 20px 22px; border-left: 1px solid var(--line); }
+.event:last-child { border-left-color: transparent; padding-bottom: 0; }
+.dot {
+  position: absolute; left: -4.5px; top: 6px; width: 8px; height: 8px;
+  background: var(--card); border: 1.5px solid var(--muted); border-radius: 50%;
+}
+.event-head { display: flex; align-items: center; gap: 10px; }
+.event-head h3 { margin: 0; font-size: 13.5px; font-weight: 600; }
+.kind-system { color: var(--muted); }
+.kind-tool { color: var(--accent); }
+.copy {
+  margin-left: auto; padding: 2px 9px; font: inherit; font-size: 11.5px; color: var(--muted);
+  background: var(--card); border: 1px solid var(--line); border-radius: 999px; cursor: pointer;
+}
+.copy:hover { color: var(--text); }
+.event-meta { margin: 3px 0 8px; color: var(--muted); font-size: 11.5px; font-family: var(--mono); }
+.body {
+  padding: 11px 13px; background: var(--soft); border-radius: 10px;
+  white-space: pre-wrap; overflow-wrap: anywhere; font-family: var(--mono); font-size: 12.5px;
+}
+.duplicate { margin: 0; color: var(--muted); font-size: 12.5px; }
+.calls { margin: 0 0 8px; font-family: var(--mono); font-size: 12.5px; }
+.call { padding: 2px 0; overflow-wrap: anywhere; }
+.arrow { color: var(--muted); margin-right: 6px; }
+.block { margin: 0 0 8px; border: 1px solid var(--line); border-radius: 10px; overflow: hidden; }
+.block summary {
+  display: flex; align-items: center; gap: 10px; padding: 8px 12px; cursor: pointer;
+  list-style: none; background: var(--soft);
+}
+.block summary::-webkit-details-marker { display: none; }
+.block-title { font-size: 12.5px; font-weight: 500; }
+.block-note { margin-left: auto; color: var(--muted); font-size: 11.5px; font-family: var(--mono); }
+.block pre {
+  margin: 0; padding: 12px; overflow: auto; overscroll-behavior: contain;
+  max-height: 22rem; scrollbar-width: thin; scrollbar-color: var(--line) transparent;
+  font-family: var(--mono); font-size: 12.5px; white-space: pre-wrap; overflow-wrap: anywhere;
+}
+.block pre::-webkit-scrollbar { width: 10px; height: 10px; }
+.block pre::-webkit-scrollbar-track { background: transparent; }
+.block pre::-webkit-scrollbar-thumb {
+  background: var(--line); border: 3px solid transparent; border-radius: 999px; background-clip: content-box;
+}
+.reasoning summary { background: transparent; }
+.empty { padding: 40px 0; color: var(--muted); text-align: center; }
+@media (max-width: 900px) {
+  /* Stacked: the page scrolls again, and the lists stop clipping themselves. */
+  html, body { height: auto; }
+  body { overflow: auto; }
+  .app { grid-template-columns: minmax(0, 1fr); padding-bottom: 40px; }
+  .turns, .timeline { overflow: visible; }
+}
+@media print {
+  html, body { height: auto; }
+  body { overflow: visible; }
+  .topbar, .sidebar, .copy { display: none; }
+  .js .panel { display: block !important; }
+  .timeline, .turns { overflow: visible; }
+}

zettcode/engine/export/trace/template.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="ZettCode">
+<title>$title · ZettCode trace</title>
+<style>$style</style>
+</head>
+<body>
+<header class="topbar">
+<span class="brand">✦ ZettCode</span>
+<span class="crumb">$title</span>
+<span class="count">$summary</span>
+<span class="count when">$exported_at</span>
+</header>
+<div class="app">
+<aside class="sidebar">
+<div class="sidebar-head">
+<span class="kicker">Raw message storage</span>
+<h1>LLM interaction trace</h1>
+<p>$subtitle</p>
+</div>
+<nav class="turns">$sidebar</nav>
+<dl class="sidebar-foot">$meta</dl>
+</aside>
+<main class="trace">$panels</main>
+</div>
+<script>$script</script>
+</body>
+</html>

zettcode/engine/extensions/__init__.py

@@ -0,0 +1,8 @@
+"""What the runtime plugs into zett-agent that is ZettCode's own.
+
+Each module here is one extension, profile, or accounting piece the runtime
+(:mod:`zettcode.engine.core`) composes into a request: the tools a model can
+use, an on-demand compaction, the request the next turn carries, MCP, subagents, and
+token usage. They are separate modules so the runtime imports only the ones a
+configuration turns on.
+"""