@zerwiz/ymir 0.1.33 → 0.1.35

package/apps/smidja-factory/templates/smidja/smidja_modules/changes.py

@@ -0,0 +1,103 @@
+"""Deterministic change capture: what was built, straight from git.
+
+"What changed since main" is not a judgement call — it is two git commands and
+a subtraction. So it is code, and an agent is only handed the result. The
+capture writes the full diff into `context_handoff/` and returns a ChangeSet;
+`as_envelope` adapts that into the one door every agent handoff uses.
+
+The base is resolved, not assumed. Off the base branch the diff covers the
+whole branch plus the working tree; on it, the uncommitted tree; and on a clean
+tree, the last commit — because "document the work that was just done" still
+has an answer right after a chain committed. Whichever it picked rides along in
+`BaseRef.reason`, so the trace never leaves you guessing what a diff was
+measured against.
+"""
+
+from __future__ import annotations
+
+from . import git_helper
+from .data_types import BaseRef, ChangeCapture, ChangeSet, ChangesOutput
+
+DIFF_FILENAME = "changes.diff"
+
+
+def resolve_base(ref: str) -> BaseRef:
+    """Pick the commit the work is measured from, and record why that one."""
+    if not git_helper.is_repo():
+        raise RuntimeError(
+            "not a git repository — change capture needs one. Run `git init` in "
+            "the repo root before running an smidja that documents a change.")
+    if not git_helper.ref_exists(ref):
+        raise RuntimeError(
+            f"base ref {ref!r} does not exist in this repository — pass --base "
+            f"with a ref that does (e.g. --base master, --base HEAD~1).")
+
+    # Built first, then given its reason: BaseRef.label knows how to print a
+    # pinned sha, and the reason is the line a human reads in the trace.
+    base = BaseRef(ref=ref, commit=git_helper.merge_base(ref, "HEAD"))
+    if git_helper.short_sha(base.commit) != git_helper.short_sha("HEAD"):
+        base.reason = (f"HEAD is ahead of {base.label} — diffing every commit since, "
+                       f"plus the working tree")
+    elif git_helper.is_dirty():
+        base.reason = f"HEAD is on {base.label} — diffing the uncommitted working tree"
+    elif git_helper.ref_exists("HEAD~1"):
+        base.commit = git_helper.rev("HEAD~1")
+        base.reason = (f"HEAD is on {base.label} with a clean tree — falling back to "
+                       f"the last commit")
+    else:
+        base.reason = f"HEAD is on {base.label} with a clean tree and no parent commit"
+    return base
+
+
+def capture(run, params: ChangeCapture) -> ChangeSet:
+    """Diff the working tree against the resolved base and persist the evidence."""
+    base = resolve_base(params.base)
+    files = git_helper.diff_files(base.commit)
+    untracked = git_helper.untracked_files() if params.include_untracked else []
+    insertions, deletions = git_helper.diff_counts(base.commit)
+    stat = git_helper.diff_stat(base.commit)
+
+    text = git_helper.diff_text(base.commit)
+    lines = text.splitlines()
+    truncated = len(lines) > params.max_diff_lines
+    if truncated:
+        text = "\n".join(lines[:params.max_diff_lines])
+        text += (f"\n\n[truncated at {params.max_diff_lines} lines of "
+                 f"{len(lines)} — run `git diff {base.commit}` for the rest]")
+
+    # Untracked files are absent from `git diff` by construction, so they are
+    # named here rather than silently missing from the record. The reader has
+    # `read` and can open any of them.
+    untracked_block = ("\n".join(f"  {f}" for f in untracked) if untracked
+                       else "  (none)")
+    diff_path = run.context_handoff_dir / DIFF_FILENAME
+    diff_path.write_text(
+        f"# changes since {base.label} @ {git_helper.short_sha(base.commit)}\n"
+        f"# {base.reason}\n"
+        f"# +{insertions} -{deletions} across {len(files)} tracked file(s)\n\n"
+        f"## stat\n{stat or '  (no tracked changes)'}\n\n"
+        f"## untracked files\n{untracked_block}\n\n"
+        f"## diff\n{text}\n")
+
+    return ChangeSet(base=base, files=files, untracked=untracked,
+                     insertions=insertions, deletions=deletions, stat=stat,
+                     diff_path=str(diff_path), truncated=truncated)
+
+
+def as_envelope(changes: ChangeSet, notes: str = "") -> ChangesOutput:
+    """Wrap a captured change so an agent can be handed it directly."""
+    total = len(changes.files) + len(changes.untracked)
+    return ChangesOutput(
+        status="success",
+        summary=(f"{total} file(s) changed since {changes.base.label} "
+                 f"(+{changes.insertions} -{changes.deletions})"),
+        artifacts=[changes.diff_path],
+        notes_for_next_agent=notes,
+        base=f"{changes.base.label} @ {git_helper.short_sha(changes.base.commit)} "
+             f"— {changes.base.reason}",
+        changed_files=changes.files + changes.untracked,
+        insertions=changes.insertions,
+        deletions=changes.deletions,
+        stat=changes.stat,
+        diff_path=changes.diff_path,
+    )

package/apps/smidja-factory/templates/smidja/smidja_modules/console.py

@@ -0,0 +1,131 @@
+"""Console reporter: one narrative, two destinations.
+
+Every line an smidja prints ALSO lands in the db as a `log` event, so the swim-lane
+UI reads the same story the terminal does. Both go through `_emit` — print and
+trace cannot drift. Plain sequential lines only: no spinners, no live displays,
+so a CI log reads exactly like a terminal.
+"""
+
+from __future__ import annotations
+
+from rich.console import Console as RichConsole
+from rich.markup import escape
+from rich.panel import Panel
+from rich.text import Text
+
+from .data_types import EnvelopeBase, EventRecord, Phase
+
+KIND_COLOR = {"engineer": "cyan", "agent": "magenta", "code": "yellow"}
+MAX_LINE = 160          # dynamic text (summaries, violations, errors) is clipped
+
+
+def _clip(text: str, limit: int = MAX_LINE) -> str:
+    text = " ".join(str(text).split())
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+class Console:
+    """Bound to one run's tracer. Reachable as `run.console` everywhere."""
+
+    def __init__(self, tracer, smidja_id: str):
+        self.tracer = tracer
+        self.smidja_id = smidja_id
+        self.phase_id = ""          # current lane — log events attach to it
+        self.phase_name = ""
+        self.results: list[str] = []            # phase statuses, for the summary
+        self._finished = False                  # the summary panel prints once
+        self._out = RichConsole(highlight=False, soft_wrap=True)
+
+    # ── the one helper: print AND trace, always together ────────────────────
+    def _emit(self, markup: str, level: str = "info", renderable=None) -> None:
+        text = Text.from_markup(markup)
+        self._out.print(renderable if renderable is not None else text)
+        self.tracer.event(EventRecord(
+            smidja_id=self.smidja_id, phase_id=self.phase_id, type="log",
+            name=self.phase_name or "console",
+            payload={"message": text.plain, "level": level}))
+
+    # ── session ─────────────────────────────────────────────────────────────
+    def session_started(self, smidja_id: str, engineer: str) -> None:
+        self._emit(f"[bold cyan]smidja_id:[/bold cyan] [bold]{escape(smidja_id)}[/bold]"
+                   f"   [dim]engineer[/dim] {escape(engineer)}")
+
+    def session_finished(self, ok: bool, tokens: int, cost: float, db_path: str) -> None:
+        if self._finished:
+            return
+        self._finished = True
+        passed = sum(1 for r in self.results if r == "success")
+        status = "[green]✓ success[/green]" if ok else "[red]✗ fail[/red]"
+        rows = [f" [dim]status[/dim]   {status}",
+                f" [dim]phases[/dim]   {passed}/{len(self.results)} passed",
+                f" [dim]tokens[/dim]   {tokens:,}",
+                f" [dim]cost[/dim]     ${cost:.4f}",
+                f" [dim]smidja_id[/dim]   {escape(self.smidja_id)}",
+                f" [dim]db[/dim]       {escape(str(db_path))}",
+                f" [dim]next[/dim]     [bold]just phases {escape(self.smidja_id)}[/bold]"]
+        panel = Panel(Text.from_markup("\n".join(rows)),
+                      title="[bold]smidja complete[/bold]",
+                      border_style="green" if ok else "red", expand=False)
+        plain = (f"session {self.smidja_id} {'success' if ok else 'fail'} · "
+                 f"{passed}/{len(self.results)} phases · {tokens:,} tokens · ${cost:.4f}")
+        self._emit(escape(plain), level="info" if ok else "error", renderable=panel)
+
+    # ── phases ──────────────────────────────────────────────────────────────
+    def phase_started(self, phase: Phase) -> None:
+        self.phase_id, self.phase_name = phase.phase_id, phase.params.name
+        p = phase.params
+        color = KIND_COLOR.get(p.kind, "white")
+        line = (f"[bold {color}]▶ {phase.seq:02d} {escape(p.name)}[/bold {color}]"
+                f"  [{color}]{p.kind}[/{color}] [dim]· {escape(p.owner)}[/dim]")
+        if p.description:
+            line += f"  [dim]{escape(_clip(p.description))}[/dim]"
+        self._emit(line)
+
+    def phase_ended(self, phase: Phase, seconds: float) -> None:
+        ok = phase.status == "success"
+        self.results.append(phase.status)
+        line = (f"  {'[green]✓[/green]' if ok else '[red]✗[/red]'} "
+                f"{escape(phase.params.name)} [dim]{seconds:.1f}s[/dim]")
+        if not ok and phase.error:
+            line += f"  [red]{escape(_clip(phase.error))}[/red]"
+        self._emit(line, level="info" if ok else "error")
+        self.phase_id, self.phase_name = "", ""
+
+    def note(self, message: str) -> None:
+        """Free-form detail inside the current phase — what `ph.log()` recorded."""
+        self._emit(f"  [dim]· {escape(_clip(message))}[/dim]")
+
+    # ── agents ──────────────────────────────────────────────────────────────
+    def agent_started(self, name: str, model: str, session_id: str) -> None:
+        self._emit(f"  [magenta]▸[/magenta] {escape(name)} [dim]{escape(model)}[/dim]"
+                   f"  [dim]session {escape(session_id)}[/dim]")
+
+    def agent_finished(self, name: str, tokens: int, cost: float) -> None:
+        self._emit(f"  [dim]└ {escape(name)} used {tokens:,} tokens · ${cost:.4f}[/dim]")
+
+    def retry(self, name: str, attempt: int, limit: int, reason: str) -> None:
+        self._emit(f"  [yellow]⟳[/yellow] {escape(name)} retry {attempt}/{limit} "
+                   f"[dim]— same session · {escape(_clip(reason))}[/dim]", level="warn")
+
+    # ── verification ────────────────────────────────────────────────────────
+    def gate_result(self, name: str, report) -> None:
+        """A gate reports WHAT it checked, not just whether it passed."""
+        ok = report.passed
+        mark = "[green]✓[/green]" if ok else "[red]✗[/red]"
+        summary = (f"{len(report.checks)} checked" if ok
+                   else f"[red]{len(report.violations)} of {len(report.checks)} failed[/red]")
+        self._emit(f"  {mark} gate [dim]{escape(name)}[/dim] [dim]{summary}[/dim]",
+                   level="info" if ok else "error")
+        for check in report.checks:
+            style = "dim" if check.ok else "dim red"
+            detail = f" — {_clip(check.note)}" if check.note else ""
+            self._emit(f"    [{style}]{'·' if check.ok else '✗'} {escape(_clip(check.item))}"
+                       f"{escape(detail)}[/{style}]", level="info" if check.ok else "error")
+
+    def envelope_summary(self, envelope: EnvelopeBase) -> None:
+        ok = envelope.status == "success"
+        line = (f"  {'[green]✓[/green]' if ok else '[red]✗[/red]'} "
+                f"{type(envelope).__name__} [dim]{escape(_clip(envelope.summary))}[/dim]")
+        self._emit(line, level="info" if ok else "error")
+        if envelope.artifacts:
+            self._emit(f"    [dim]artifacts: {escape(_clip(', '.join(envelope.artifacts)))}[/dim]")

package/apps/smidja-factory/templates/smidja/smidja_modules/data_types.py

@@ -0,0 +1,447 @@
+"""Concrete data types for the smidja smidja system.
+
+RULE (four-param rule): any function that takes more than 4 parameters takes
+ONE of these objects instead. AgentCall and PhaseParams are the pattern.
+
+Every agent call declares a concrete output type — an EnvelopeBase subclass —
+that its final JSON response is parsed against. No untyped handoffs.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Literal, Optional, Type
+
+from pydantic import BaseModel, Field, ValidationInfo, field_validator
+
+PhaseKind = Literal["engineer", "agent", "code"]
+PhaseStatus = Literal["queued", "running", "success", "fail"]
+
+
+# ── Phases ────────────────────────────────────────────────────────────────────
+
+class PhaseParams(BaseModel):
+    """Everything run.phase() needs. Passed as one object, never loose params."""
+
+    name: str                       # short id, unique within the run: "plan", "build"
+    kind: PhaseKind                 # which lane the block renders in
+    owner: str                      # engineer's name, "git", or an agent name from config
+    description: str                # REQUIRED: what this phase does and why — see below
+    retries: int = 0                # agent phases: gate-failure retries via continue
+
+    @field_validator("description")
+    @classmethod
+    def _description_must_be_earned(cls, value: str, info: ValidationInfo) -> str:
+        """A phase name identifies; a description explains. Both are required.
+
+        The description is the only sentence the trace, the console, and the
+        phase block in the UI ever show about intent — everything else is ids,
+        statuses, and timings. `commit_plan: "Commit the plan"` tells a reader
+        nothing they could not already see, so an echo is rejected the same way
+        a blank one is. This is a construction-time error on purpose: it fires
+        before the phase opens, not after a run is already in the trace.
+        """
+        text = " ".join(value.split())
+        name = str(info.data.get("name", "?"))
+        if not text:
+            raise ValueError(
+                f"phase {name!r}: description is required — one sentence on what this "
+                f"phase does and why. It is what the trace and the UI show.")
+        if text.rstrip(".").casefold() == name.replace("_", " ").casefold():
+            raise ValueError(
+                f"phase {name!r}: description {text!r} only restates the phase name — "
+                f"say what it does and why instead.")
+        return text
+
+
+class Phase(BaseModel):
+    """The persisted phase record — PhaseParams plus lifecycle."""
+
+    phase_id: str
+    smidja_id: str
+    seq: int
+    params: PhaseParams
+    status: PhaseStatus = "fail"    # success must be earned
+    attempt: int = 0
+    error: Optional[str] = None
+    started_at: Optional[str] = None
+    ended_at: Optional[str] = None
+
+
+# ── Envelopes (agent output types) ───────────────────────────────────────────
+
+class EnvelopeBase(BaseModel):
+    """Base of every agent's final JSON response. Output types extend this."""
+
+    status: Literal["success", "fail"]
+    summary: str = ""
+    artifacts: list[str] = Field(default_factory=list)
+    notes_for_next_agent: str = ""
+
+
+class GenericOutput(EnvelopeBase):
+    pass
+
+
+class PlanOutput(EnvelopeBase):
+    # Subject for committing the PLAN — the spec file the planner wrote, not the
+    # implementation it describes. Each agent's commit_message covers its own
+    # work product, so a chain that commits per step never reuses one agent's
+    # words for another agent's diff.
+    commit_message: str = ""
+
+
+class BuildOutput(EnvelopeBase):
+    changed_files: list[str] = Field(default_factory=list)
+    commit_message: str = ""        # consumed by the git commit phase
+
+
+class ScoutFinding(BaseModel):
+    file: str
+    note: str = ""
+
+
+class ScoutOutput(EnvelopeBase):
+    findings: list[ScoutFinding] = Field(default_factory=list)
+
+
+class ReviewFinding(BaseModel):
+    """One thing the request (or plan) asked for, and whether it is there."""
+
+    requirement: str                # the ask, in the requester's words
+    met: bool
+    evidence: str = ""              # where it lives, or what is missing
+
+
+class ReviewOutput(EnvelopeBase):
+    """Confirmation that what was built is what was asked for — not a test run."""
+
+    approved: bool = False
+    findings: list[ReviewFinding] = Field(default_factory=list)
+    blocking: list[str] = Field(default_factory=list)   # what must change before approval
+
+
+class DocumentOutput(EnvelopeBase):
+    """Where the write-up of a completed change landed."""
+
+    document_path: str = ""         # the doc in the repo, e.g. app_docs/<smidja_id>_<slug>.md
+    documented_files: list[str] = Field(default_factory=list)
+    commit_message: str = ""
+
+
+# ── Deterministic quality blocks ─────────────────────────────────────────────
+
+QualityArea = Literal["frontend", "backend"]
+QualityOperation = Literal["lint", "typecheck", "build"]
+
+
+class QualityCheckSpec(BaseModel):
+    """One deterministic quality command."""
+
+    name: str
+    area: QualityArea
+    operation: QualityOperation
+    argv: list[str]
+    timeout_seconds: int = 120
+
+
+class QualityCheckResult(BaseModel):
+    """Captured evidence from one quality command."""
+
+    name: str
+    area: QualityArea
+    operation: QualityOperation
+    command: str
+    returncode: int
+    passed: bool
+    duration_seconds: float
+    output_artifact: str
+    # The tail of stdout+stderr, verbatim and unparsed. A failure has to travel
+    # back to the builder as an envelope, and the builder cannot open a log file
+    # it was never handed — so the evidence rides along. Deliberately raw: every
+    # runner formats failures differently and a generic parser would be
+    # confidently wrong. The full log is always at output_artifact.
+    output_tail: str = ""
+
+
+class QualityResult(BaseModel):
+    """Aggregate result from a quality block: every check it ran, and the verdict."""
+
+    passed: bool
+    checks: list[QualityCheckResult] = Field(default_factory=list)
+    failures: list[str] = Field(default_factory=list)
+    artifacts: list[str] = Field(default_factory=list)
+
+
+# ── Change capture (git diff, deterministic) ─────────────────────────────────
+
+class ChangeCapture(BaseModel):
+    """Everything documentation.capture() needs. One object, never loose params."""
+
+    base: str = "main"              # the ref the work is measured against
+    max_diff_lines: int = 2000      # the diff artifact is truncated past this
+    include_untracked: bool = True  # a brand-new file is part of the change
+
+
+class BaseRef(BaseModel):
+    """The commit a change is measured from, and why that one.
+
+    `reason` is the line the trace shows. A diff is only as trustworthy as the
+    thing it was taken against, so the smidja records that choice instead of
+    leaving the reader to infer it.
+    """
+
+    ref: str                        # what was asked for: "main", or a pinned sha
+    commit: str                     # the commit actually diffed against
+    reason: str = ""
+
+    @property
+    def label(self) -> str:
+        """Display form — a named ref as itself, a pinned raw sha shortened."""
+        if len(self.ref) == 40 and all(c in "0123456789abcdef" for c in self.ref):
+            return self.ref[:7]
+        return self.ref
+
+
+class ChangeSet(BaseModel):
+    """What changed since the base commit — pure git facts, no judgement."""
+
+    base: BaseRef
+    files: list[str] = Field(default_factory=list)
+    untracked: list[str] = Field(default_factory=list)
+    insertions: int = 0
+    deletions: int = 0
+    stat: str = ""                  # `git diff --stat` output, verbatim
+    diff_path: str = ""             # the full diff, written into context_handoff/
+    truncated: bool = False
+
+    @property
+    def empty(self) -> bool:
+        return not (self.files or self.untracked)
+
+
+class ChangesOutput(EnvelopeBase):
+    """A ChangeSet shaped as an envelope so an agent can be handed it directly.
+
+    Same adapter idea as VerifyOutput: code computes the diff, the documenter
+    consumes it through the one door every agent handoff uses.
+    """
+
+    base: str = ""                  # "<ref> @ <commit> — <reason>"
+    changed_files: list[str] = Field(default_factory=list)
+    insertions: int = 0
+    deletions: int = 0
+    stat: str = ""
+    diff_path: str = ""             # read this for the full diff
+
+
+class VerifyOutput(EnvelopeBase):
+    """A deterministic result, shaped as an envelope so an agent can consume it.
+
+    Agents hand each other typed envelopes; code blocks return QualityResult.
+    This is the adapter, so a failing lint or test run flows back into the
+    builder through exactly the same door a tester agent's report used to —
+    the smidja script is the only thing that knows the difference.
+    """
+
+    passed: bool = False
+    failures: list[str] = Field(default_factory=list)
+
+
+# ── Agent calls ──────────────────────────────────────────────────────────────
+
+class GateCheck(BaseModel):
+    """One thing a gate looked at, and what it found.
+
+    `note` is the evidence — "exists, 2.1KB", "exit 0", "not in the diff". On a
+    failed check it doubles as the reason, so it is what the agent is told.
+    """
+
+    item: str                       # what was checked: a path, a command, a test
+    ok: bool
+    note: str = ""
+
+
+class GateReport(BaseModel):
+    """What every gate returns: the checks it ran. Violations are derived.
+
+    Authoring stays a one-liner per item — `report.check(...)` appends and
+    returns self, so a gate is a loop and a return.
+    """
+
+    checks: list[GateCheck] = Field(default_factory=list)
+
+    def check(self, item: str, ok: bool, note: str = "") -> "GateReport":
+        self.checks.append(GateCheck(item=item, ok=ok, note=note))
+        return self
+
+    @property
+    def violations(self) -> list[str]:
+        return [f"{c.item}: {c.note or 'failed'}" for c in self.checks if not c.ok]
+
+    @property
+    def passed(self) -> bool:
+        return not self.violations
+
+
+class AgentCall(BaseModel):
+    """One agent invocation: prompt in, typed envelope out, gates verified."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    output_type: Type[EnvelopeBase]
+    prompt: str
+    previous: Optional[EnvelopeBase] = None
+    gates: list[Callable] = Field(default_factory=list)   # gate(envelope, run) -> list[str]
+
+
+# ── Config ───────────────────────────────────────────────────────────────────
+
+class PromptEngineering(BaseModel):
+    system: str                     # path to system.md
+    user: str                       # path to user.md
+
+
+class AgentConfig(BaseModel):
+    name: str
+    coding_agent: Literal["pi", "claude_code"] = "pi"
+    model: str = "google/gemini-3.6-flash"
+    thinking: str = "medium"        # off | minimal | low | medium | high | xhigh | max
+    color: str = ""                 # hex swatch for this agent's lane in the UI
+    purpose: str = ""
+    prompt_engineering: PromptEngineering
+    harness_engineering: list[str] = Field(default_factory=list)
+    tools: Optional[list[str]] = None    # allowlist; None = all tools usable
+    # What this agent may MODIFY in the repo, enforced in code after every call
+    # (see smidja_modules/permissions.py). `tools` cannot express this: `bash` runs
+    # anything and `write` reaches any path, so an agent's capability list is a
+    # statement of intent that nothing checks.
+    #   None  -> unrestricted, except the roster-wide `protected_files` paths
+    #   []    -> read-only: may modify nothing tracked
+    #   [...] -> only these. A trailing "/" means a directory prefix; a "*"
+    #            makes it a glob; anything else is an exact path.
+    writes: Optional[list[str]] = None
+
+
+class ConfigDefaults(BaseModel):
+    coding_agent: Literal["pi", "claude_code"] = "pi"
+    model: str = "google/gemini-3.6-flash"
+    thinking: str = "medium"
+    color: str = ""
+    harness_engineering: list[str] = Field(default_factory=list)
+    tools: Optional[list[str]] = None    # roster-wide allowlist; None = all tools usable
+    # Off-limits to every agent that has not named them in its own `writes`.
+    # The smidja's own code is the default: an agent must not be able to edit
+    # the machinery that decides whether its work passed.
+    protected_files: list[str] = Field(default_factory=lambda: [
+        "smidja/smidja_modules/", "smidja/smidja_smidja_config/", "smidja/smidja_*.py",
+    ])
+    data_dir: str = "smidja/smidja_data"
+
+
+class ObservabilityConfig(BaseModel):
+    db: str = "smidja/smidja_data/smidja.db"
+    poll_ms: int = 500
+
+
+class smidjaConfig(BaseModel):
+    defaults: ConfigDefaults = Field(default_factory=ConfigDefaults)
+    observability: ObservabilityConfig = Field(default_factory=ObservabilityConfig)
+    agents: list[AgentConfig] = Field(default_factory=list)
+
+
+# ── Tracing ──────────────────────────────────────────────────────────────────
+
+class EventRecord(BaseModel):
+    """One traced event, always logged against smidja_id + phase."""
+
+    smidja_id: str
+    phase_id: str = ""
+    type: str                       # phase_start | agent_start | tool_call | handoff | gate_pass | gate_fail | log | agent_end | phase_end | error
+    name: str = ""
+    payload: dict[str, Any] = Field(default_factory=dict)
+    parent_id: str = ""
+    tokens: Optional[int] = None
+    # Spans: set both when an event covers real elapsed time (a tool call), so
+    # the UI lays it out on a time axis without parsing payload JSON. Left unset,
+    # the tracer stamps started_at with the moment the event was recorded.
+    started_at: Optional[str] = None
+    ended_at: Optional[str] = None
+
+
+# ── Pi coding agent interface ────────────────────────────────────────────────
+
+class PiRequest(BaseModel):
+    """Everything one non-interactive pi run needs."""
+
+    prompt: str
+    system_prompt: str
+    model: str                      # registry pattern, resolved to provider + id
+    thinking: str = "medium"
+    session_id: str                 # pi --session-id: creates or continues
+    session_dir: str
+    raw_output_path: str            # JSONL stream lands here
+    tools: Optional[list[str]] = None
+    extensions: list[str] = Field(default_factory=list)
+    cwd: str = "."                  # set from run.repo_root — the codebase root agents work in
+
+
+class UsageBreakdown(BaseModel):
+    """Tokens and the dollars they cost, per component, summed over a call.
+
+    Mirrors pi's `usage` shape one-for-one so the numbers reconcile with what
+    pi itself reports: `input` EXCLUDES cache reads, which bill at their own
+    (cheaper) rate — add them to learn the size of the prompt that was sent.
+    """
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+    # Thinking tokens. NOT a fifth component: measured across every session on
+    # disk, reasoning is always <= output and the four components above always
+    # sum to totalTokens, so reasoning is the thinking SHARE of output, billed
+    # at the output rate. Report it nested under output, never added to it.
+    reasoning_tokens: int = 0
+    total_tokens: int = 0
+    input_cost: float = 0.0
+    output_cost: float = 0.0
+    cache_read_cost: float = 0.0
+    cache_write_cost: float = 0.0
+    total_cost: float = 0.0
+
+    def add_turn(self, usage: dict, total_tokens: int) -> None:
+        """Fold in one pi `message_end` usage object.
+
+        `total_tokens` is passed in rather than re-derived: the caller already
+        computes it pi's way (totalTokens, else the sum of the parts).
+        """
+        cost = usage.get("cost") or {}
+        self.input_tokens += usage.get("input") or 0
+        self.output_tokens += usage.get("output") or 0
+        self.cache_read_tokens += usage.get("cacheRead") or 0
+        self.cache_write_tokens += usage.get("cacheWrite") or 0
+        self.reasoning_tokens += usage.get("reasoning") or 0
+        self.total_tokens += total_tokens
+        self.input_cost += cost.get("input") or 0.0
+        self.output_cost += cost.get("output") or 0.0
+        self.cache_read_cost += cost.get("cacheRead") or 0.0
+        self.cache_write_cost += cost.get("cacheWrite") or 0.0
+        self.total_cost += cost.get("total") or 0.0
+
+    def merge(self, other: "UsageBreakdown") -> None:
+        """Add another call's usage — a phase that retries spends more than once."""
+        for field in self.model_fields:
+            setattr(self, field, getattr(self, field) + getattr(other, field))
+
+
+class PiResult(BaseModel):
+    text: str = ""
+    returncode: int = 0
+    session_id: str = ""
+    tokens: int = 0
+    cost: float = 0.0
+    usage: UsageBreakdown = Field(default_factory=UsageBreakdown)
+    # Context occupancy after the LAST turn — not a sum. `tokens` bills every
+    # turn; this is how full the window is right now, which is what the
+    # visualizer's context bar measures against `context_window`.
+    context_tokens: int = 0
+    context_window: int = 0         # 0 when the registry declares no ceiling