omega-code 0.4.0__py3-none-any.whl

omega/eval/report.py

@@ -0,0 +1,135 @@
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .manifest import ContextManifest
+
+
+@dataclass(frozen=True)
+class RunResult:
+    task: str
+    model: str
+    repeat: int
+    passed: bool
+    turns: int
+    tool_calls: dict[str, int]
+    tokens_in: int
+    tokens_out: int
+    cost_usd: float | None
+    wall_time_s: float
+    cache_hit_ratio: float | None
+    error: str | None
+    check_output: str
+    manifest: ContextManifest | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "task": self.task, "model": self.model, "repeat": self.repeat,
+            "passed": self.passed, "turns": self.turns, "tool_calls": self.tool_calls,
+            "tokens_in": self.tokens_in, "tokens_out": self.tokens_out,
+            "cost_usd": self.cost_usd, "wall_time_s": round(self.wall_time_s, 3),
+            "cache_hit_ratio": self.cache_hit_ratio, "error": self.error,
+            "check_output": self.check_output[:2000],
+            "manifest": self.manifest.to_dict() if self.manifest else None,
+        }
+
+
+def _result_from_dict(d: dict[str, Any]) -> RunResult:
+    return RunResult(
+        task=d["task"], model=d["model"], repeat=d["repeat"], passed=d["passed"],
+        turns=d["turns"], tool_calls=dict(d["tool_calls"]), tokens_in=d["tokens_in"],
+        tokens_out=d["tokens_out"], cost_usd=d["cost_usd"], wall_time_s=d["wall_time_s"],
+        cache_hit_ratio=d["cache_hit_ratio"], error=d["error"], check_output=d["check_output"],
+        # `compare` only needs the summary row -- reloading a full ContextManifest
+        # from JSON isn't worth the code, so the manifest stays report.json-only.
+        manifest=None,
+    )
+
+
+@dataclass(frozen=True)
+class Report:
+    created: float
+    results: tuple[RunResult, ...] = field(default_factory=tuple)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"created": self.created, "results": [r.to_dict() for r in self.results]}
+
+    def summary_by_model(self) -> dict[str, dict[str, Any]]:
+        by_model: dict[str, list[RunResult]] = {}
+        for r in self.results:
+            by_model.setdefault(r.model, []).append(r)
+        out: dict[str, dict[str, Any]] = {}
+        for model, rows in by_model.items():
+            costs = [r.cost_usd for r in rows if r.cost_usd is not None]
+            out[model] = {
+                "runs": len(rows),
+                "pass_rate": sum(r.passed for r in rows) / len(rows),
+                "mean_cost_usd": (sum(costs) / len(costs)) if costs else None,
+                "mean_time_s": sum(r.wall_time_s for r in rows) / len(rows),
+            }
+        return out
+
+
+def render_table(report: Report) -> str:
+    if not report.results:
+        return "(no runs)"
+    header = (f"{'TASK':<30}{'MODEL':<10}{'RESULT':>7}{'TURNS':>7}{'TOOLS':>7}"
+             f"{'TOK IN':>9}{'TOK OUT':>9}{'$':>9}{'TIME':>8}")
+    lines = [header]
+    for r in report.results:
+        tool_total = sum(r.tool_calls.values())
+        cost = f"{r.cost_usd:.4f}" if r.cost_usd is not None else "-"
+        lines.append(f"{r.task[:29]:<30}{r.model:<10}{'PASS' if r.passed else 'FAIL':>7}"
+                     f"{r.turns:>7}{tool_total:>7}{r.tokens_in:>9}{r.tokens_out:>9}"
+                     f"{cost:>9}{r.wall_time_s:>7.1f}s")
+    lines.append("")
+    for model, s in sorted(report.summary_by_model().items()):
+        cost = f"${s['mean_cost_usd']:.4f}" if s["mean_cost_usd"] is not None else "$-"
+        lines.append(f"{model}: {s['pass_rate'] * 100:.0f}% pass · {cost} mean · "
+                     f"{s['mean_time_s']:.1f}s mean · {s['runs']} run(s)")
+    return "\n".join(lines)
+
+
+def compare(a: Report, b: Report) -> str:
+    def key(r: RunResult) -> tuple[str, str]:
+        return (r.task, r.model)
+
+    a_by = {key(r): r for r in a.results}
+    b_by = {key(r): r for r in b.results}
+    lines = [f"{'TASK':<30}{'MODEL':<10}{'PASS':>8}{'$ delta':>12}{'TIME delta':>14}"]
+    for k in sorted(set(a_by) | set(b_by)):
+        task, model = k
+        ra, rb = a_by.get(k), b_by.get(k)
+        if ra is None:
+            pass_change = "new(fail)" if not (rb and rb.passed) else "new(pass)"
+        elif rb is None:
+            pass_change = "gone"
+        elif ra.passed == rb.passed:
+            pass_change = "pass" if rb.passed else "fail"
+        else:
+            pass_change = "fixed" if rb.passed else "REGRESSED"
+        cost_delta = ("-" if not (ra and rb and ra.cost_usd is not None and rb.cost_usd is not None)
+                     else f"{rb.cost_usd - ra.cost_usd:+.4f}")
+        time_delta = "-" if not (ra and rb) else f"{rb.wall_time_s - ra.wall_time_s:+.1f}s"
+        lines.append(f"{task[:29]:<30}{model:<10}{pass_change:>8}{cost_delta:>12}{time_delta:>14}")
+    return "\n".join(lines)
+
+
+def write_report(report: Report, run_dir: Path) -> Path:
+    run_dir.mkdir(parents=True, exist_ok=True)
+    path = run_dir / "report.json"
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(report.to_dict(), indent=1))
+    tmp.replace(path)
+    return path
+
+
+def load_report(path: Path) -> Report:
+    raw = json.loads(path.read_text())
+    return Report(created=raw["created"], results=tuple(_result_from_dict(r) for r in raw["results"]))
+
+
+def new_run_dir(runs_root: Path) -> Path:
+    return runs_root / time.strftime("%Y%m%d-%H%M%S")

omega/eval/runner.py

@@ -0,0 +1,199 @@
+import asyncio
+import os
+import secrets
+import shutil
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .. import events, loop, tools
+from ..config import Config, Role
+from ..session import Message
+from .manifest import build_manifest
+from .prices import estimate_cost
+from .report import RunResult
+from .tasks import Task
+
+_CHECK_TIMEOUT_S = 300
+
+# `tools._bash` resolves its working directory via `os.getcwd()`, which is
+# process-wide -- two runs executing tools concurrently in different
+# worktrees would race on which directory a bash call actually lands in.
+# `--jobs` still bounds how many runs are in flight (workspace prep/cleanup
+# and the model's own network waits overlap fine); this lock only serializes
+# the tool-executing portion of each run, which is the part that touches cwd.
+_TOOL_LOCK = asyncio.Lock()
+
+
+@dataclass(frozen=True)
+class Workspace:
+    path: Path
+    is_git_worktree: bool
+    source_repo: Path
+
+
+def resolve_models(cfg: Config, models_arg: str | None) -> list[tuple[str, Role]]:
+    """`--models a,b,c` resolves each alias against the catalog; with no
+    `--models`, eval runs against whatever `main` currently points at."""
+    if not models_arg:
+        role = cfg.role("main")
+        return [(role.alias or "main", role)]
+    out: list[tuple[str, Role]] = []
+    for raw in models_arg.split(","):
+        alias = cfg.resolve_alias(raw.strip())
+        out.append((alias, cfg.model(alias)))
+    return out
+
+
+async def _is_git_repo(repo: Path) -> bool:
+    proc = await asyncio.create_subprocess_exec(
+        "git", "-C", str(repo), "rev-parse", "--is-inside-work-tree",
+        stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
+    await proc.communicate()
+    return proc.returncode == 0
+
+
+async def prepare_workspace(task: Task, work_root: Path) -> Workspace:
+    repo = Path(task.repo).expanduser().resolve()
+    work_root.mkdir(parents=True, exist_ok=True)
+    dest = work_root / f"{task.name.replace(' ', '_')}-{secrets.token_hex(3)}"
+    is_git = await _is_git_repo(repo)
+    if is_git:
+        proc = await asyncio.create_subprocess_exec(
+            "git", "-C", str(repo), "worktree", "add", "--detach", str(dest), "HEAD",
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
+        _out, err = await proc.communicate()
+        if proc.returncode != 0:
+            raise RuntimeError(f"git worktree add failed: {err.decode(errors='replace')[:500]}")
+    else:
+        shutil.copytree(repo, dest)
+
+    if task.setup:
+        proc = await asyncio.create_subprocess_shell(
+            task.setup, cwd=str(dest),
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
+        _out, err = await proc.communicate()
+        if proc.returncode != 0:
+            raise RuntimeError(f"setup command failed ({proc.returncode}): "
+                               f"{err.decode(errors='replace')[:2000]}")
+    return Workspace(path=dest, is_git_worktree=is_git, source_repo=repo)
+
+
+async def cleanup_workspace(ws: Workspace) -> None:
+    if ws.is_git_worktree:
+        proc = await asyncio.create_subprocess_exec(
+            "git", "-C", str(ws.source_repo), "worktree", "remove", "--force", str(ws.path),
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
+        await proc.communicate()
+    else:
+        shutil.rmtree(ws.path, ignore_errors=True)
+
+
+async def _run_check(check: str, cwd: Path) -> tuple[bool, str]:
+    proc = await asyncio.create_subprocess_shell(
+        check, cwd=str(cwd),
+        stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.STDOUT)
+    try:
+        out, _ = await asyncio.wait_for(proc.communicate(), timeout=_CHECK_TIMEOUT_S)
+    except TimeoutError:
+        proc.kill()
+        await proc.communicate()
+        return False, f"check timed out after {_CHECK_TIMEOUT_S}s"
+    return proc.returncode == 0, out.decode(errors="replace")[-4000:]
+
+
+async def run_one(cfg: Config, task: Task, label: str, role: Role, ws: Workspace,
+                  repeat: int = 0) -> RunResult:
+    """Runs one task against one model in an already-prepared workspace.
+    Consumes `loop.run_agent` exactly as the CLI does -- `--yolo` semantics
+    (no CONFIRM/ASK_USER), events collected via `emit` instead of rendered."""
+    system, tool_names = loop.MODES[task.mode]
+    system = f"{system}\n{loop.UNTRUSTED_NOTE}"
+    schemas = tools.schemas(tool_names)
+    history: list[Message] = [{"role": "user", "content": task.prompt}]
+    initial_history = list(history)
+    collected: list[events.Event] = []
+    error: str | None = None
+    result_text = ""
+
+    started = time.monotonic()
+    prev_cwd = os.getcwd()
+    # tools.SESSION_ID/CONFIRM/ASK_USER/TAINTED are process globals `tools.run`
+    # reads directly -- this run isn't the only thing that may touch them
+    # (a caller embedding the eval harness in a live session, or -- in
+    # tests -- an unrelated fixture), so snapshot and restore them rather
+    # than assuming None/False is always the right thing to leave behind.
+    prev_session_id, prev_confirm, prev_ask_user, prev_tainted = (
+        tools.SESSION_ID, tools.CONFIRM, tools.ASK_USER, tools.TAINTED)
+    async with _TOOL_LOCK:
+        tools.SESSION_ID = f"eval-{task.name}-{label}-{repeat}-{secrets.token_hex(3)}"
+        tools.CONFIRM = None
+        tools.ASK_USER = None
+        tools.set_tainted(False)
+        os.chdir(ws.path)
+        try:
+            result_text = await asyncio.wait_for(
+                loop.run_agent(cfg, "main" if task.mode == "build" else "plan",
+                               system, history, tool_names, emit=collected.append, role=role),
+                timeout=task.timeout_s)
+        except TimeoutError:
+            error = f"timed out after {task.timeout_s}s"
+        except Exception as e:
+            error = f"{type(e).__name__}: {e}"
+        finally:
+            os.chdir(prev_cwd)
+            tools.SESSION_ID, tools.CONFIRM, tools.ASK_USER = (
+                prev_session_id, prev_confirm, prev_ask_user)
+            tools.set_tainted(prev_tainted)
+    wall_time_s = time.monotonic() - started
+
+    passed, check_output = False, ""
+    if error is None:
+        (ws.path / "TRANSCRIPT.md").write_text(result_text)
+        passed, check_output = await _run_check(task.check, ws.path)
+    else:
+        check_output = error
+
+    turns = sum(1 for ev in collected if isinstance(ev, events.Phase) and ev.state == "waiting")
+    tool_calls: dict[str, int] = {}
+    for ev in collected:
+        if isinstance(ev, events.ToolStart):
+            tool_calls[ev.name] = tool_calls.get(ev.name, 0) + 1
+    usage_events = [ev for ev in collected if isinstance(ev, events.Usage)]
+    tokens_in = sum(ev.prompt_tokens for ev in usage_events)
+    tokens_out = sum(ev.completion_tokens for ev in usage_events)
+    cache_total = sum(getattr(ev, "cached_tokens", None) or getattr(ev, "cache_read", None) or 0
+                      for ev in usage_events)
+    cache_hit_ratio = (cache_total / tokens_in) if tokens_in else None
+    manifest = build_manifest(collected, system, schemas, initial_history, history)
+
+    return RunResult(task=task.name, model=label, repeat=repeat, passed=passed, turns=turns,
+                     tool_calls=tool_calls, tokens_in=tokens_in, tokens_out=tokens_out,
+                     cost_usd=estimate_cost(label, tokens_in, tokens_out),
+                     wall_time_s=wall_time_s, cache_hit_ratio=cache_hit_ratio,
+                     error=error, check_output=check_output, manifest=manifest)
+
+
+async def run_suite(cfg: Config, tasks: list[Task], roles: list[tuple[str, Role]],
+                    repeat: int = 1, jobs: int = 1,
+                    work_root: Path | None = None) -> list[RunResult]:
+    owns_root = work_root is None
+    work_root = work_root or Path(tempfile.mkdtemp(prefix="omega-eval-"))
+    sem = asyncio.Semaphore(max(1, jobs))
+
+    async def _one(task: Task, label: str, role: Role, i: int) -> RunResult:
+        async with sem:
+            ws = await prepare_workspace(task, work_root)
+            try:
+                return await run_one(cfg, task, label, role, ws, repeat=i)
+            finally:
+                await cleanup_workspace(ws)
+
+    coros = [_one(task, label, role, i)
+            for task in tasks for label, role in roles for i in range(repeat)]
+    try:
+        return list(await asyncio.gather(*coros))
+    finally:
+        if owns_root:
+            shutil.rmtree(work_root, ignore_errors=True)

omega/eval/tasks.py

@@ -0,0 +1,97 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+
+Mode = Literal["build", "plan"]
+
+_REQUIRED = ("name", "prompt", "check")
+_MODES = ("build", "plan")
+
+EXAMPLES_DIR = Path(__file__).parent / "examples"
+
+
+class TaskError(ValueError):
+    """A task file is missing a required field, has an invalid value, or the
+    given path/directory doesn't resolve to any task -- distinct from
+    ValueError so callers can catch just this without swallowing unrelated
+    bugs in yaml.safe_load or dataclass construction."""
+
+
+@dataclass(frozen=True)
+class Task:
+    name: str
+    prompt: str
+    check: str
+    repo: str = "."
+    setup: str | None = None
+    timeout_s: int = 600
+    mode: Mode = "build"
+    tags: tuple[str, ...] = field(default_factory=tuple)
+    source: str = ""
+
+
+def parse_task(raw: dict[str, Any], source: str = "") -> Task:
+    if not isinstance(raw, dict):
+        raise TaskError(f"{source}: task must be a YAML mapping, got {type(raw).__name__}")
+    missing = [f for f in _REQUIRED if not raw.get(f)]
+    if missing:
+        raise TaskError(f"{source}: missing required field(s): {', '.join(missing)}")
+
+    mode = raw.get("mode", "build")
+    if mode not in _MODES:
+        raise TaskError(f"{source}: mode must be one of {_MODES}, got {mode!r}")
+
+    timeout_s = raw.get("timeout_s", 600)
+    if not isinstance(timeout_s, int) or isinstance(timeout_s, bool) or timeout_s <= 0:
+        raise TaskError(f"{source}: timeout_s must be a positive integer, got {timeout_s!r}")
+
+    tags = raw.get("tags") or []
+    if not isinstance(tags, list) or not all(isinstance(t, str) for t in tags):
+        raise TaskError(f"{source}: tags must be a list of strings")
+
+    setup = raw.get("setup")
+    return Task(
+        name=str(raw["name"]), prompt=str(raw["prompt"]), check=str(raw["check"]),
+        repo=str(raw.get("repo", ".")), setup=(str(setup) if setup else None),
+        timeout_s=timeout_s, mode=mode, tags=tuple(tags), source=source,
+    )
+
+
+def load_task_file(path: Path) -> Task:
+    try:
+        raw = yaml.safe_load(path.read_text())
+    except yaml.YAMLError as e:
+        raise TaskError(f"{path}: invalid YAML: {e}") from e
+    return parse_task(raw or {}, source=str(path))
+
+
+def discover_task_files(path: str | None) -> list[Path]:
+    """`path=None` is the project default `.omega/evals/`; a directory globs
+    its *.yaml/*.yml; a file is used as-is."""
+    if path is None:
+        root = Path.cwd() / ".omega" / "evals"
+        if not root.exists():
+            return []
+        return sorted(root.glob("*.yaml")) + sorted(root.glob("*.yml"))
+    p = Path(path).expanduser()
+    if p.is_dir():
+        return sorted(p.glob("*.yaml")) + sorted(p.glob("*.yml"))
+    if p.is_file():
+        return [p]
+    raise TaskError(f"no such task file or directory: {p}")
+
+
+def load_tasks(path: str | None = None) -> list[Task]:
+    return [load_task_file(f) for f in discover_task_files(path)]
+
+
+def init_examples(dest: Path) -> list[Path]:
+    dest.mkdir(parents=True, exist_ok=True)
+    written = []
+    for src in sorted(EXAMPLES_DIR.glob("*.yaml")):
+        target = dest / src.name
+        target.write_text(src.read_text())
+        written.append(target)
+    return written

omega/events.py

@@ -0,0 +1,145 @@
+from dataclasses import dataclass
+from typing import Literal, TypedDict
+
+
+class Option(TypedDict, total=False):
+    """An `ask_user` choice, as passed to `tools.ASK_USER` and rendered by both UIs."""
+    label: str
+    description: str
+
+
+@dataclass(frozen=True)
+class TextDelta:
+    text: str
+
+
+@dataclass(frozen=True)
+class ToolStart:
+    call_id: str
+    name: str
+    args_preview: str
+    subagent_id: str | None = None
+    tier: str | None = None
+
+
+@dataclass(frozen=True)
+class ToolEnd:
+    call_id: str
+    name: str
+    result_preview: str
+    duration_s: float
+    offloaded: bool
+    artifact_id: str | None = None
+    result_chars: int = 0
+    outcome: str = ""
+
+
+@dataclass(frozen=True)
+class Compacted:
+    note: str
+
+
+@dataclass(frozen=True)
+class MemoryWrite:
+    node_id: str
+    type: str
+    title: str
+    scope: str
+
+
+@dataclass(frozen=True)
+class MemoryConsolidated:
+    summary: str
+
+
+@dataclass(frozen=True)
+class SubagentSpawned:
+    subagent_id: str
+    tier: str
+    task_preview: str
+
+
+@dataclass(frozen=True)
+class SubagentDone:
+    subagent_id: str
+    summary_preview: str
+
+
+@dataclass(frozen=True)
+class Error:
+    message: str
+
+
+@dataclass(frozen=True)
+class Done:
+    text: str
+
+
+@dataclass(frozen=True)
+class Usage:
+    prompt_tokens: int
+    completion_tokens: int
+    used: int
+    limit: int
+    cache_read: int = 0
+    cache_write: int = 0
+
+
+@dataclass(frozen=True)
+class Fallback:
+    from_model: str
+    to_model: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class ModelUsed:
+    alias: str | None
+    model: str
+    provider: str
+
+
+@dataclass(frozen=True)
+class Phase:
+    state: Literal["waiting", "thinking", "streaming", "tools", "idle"]
+
+
+@dataclass(frozen=True)
+class Checkpoint:
+    """A working-tree snapshot taken before a BUILD-mode turn -- see checkpoint.py."""
+    turn: int
+    id: str
+
+
+@dataclass(frozen=True)
+class Verified:
+    """One end-of-turn verification pass (possibly a retry) -- see verify.py."""
+    results_summary: str
+    ok: bool
+
+
+@dataclass(frozen=True)
+class JobStarted:
+    """A `bash(..., background=True)` job began running -- see tools.py."""
+    id: str
+    command: str
+
+
+@dataclass(frozen=True)
+class JobFinished:
+    id: str
+    exit_code: int
+
+
+@dataclass(frozen=True)
+class RetryBlocked:
+    """The harness refused to re-execute a tool call whose exact
+    (name, args) already failed repeatedly with the same error -- see
+    loop.py's per-turn repeat-fail guard."""
+    name: str
+    attempts: int
+
+
+Event = (TextDelta | ToolStart | ToolEnd | Compacted | MemoryWrite |
+         MemoryConsolidated | SubagentSpawned | SubagentDone | Error | Done | Usage | ModelUsed | Phase |
+         Fallback | Checkpoint | Verified | JobStarted | JobFinished | RetryBlocked)

omega/export.py

@@ -0,0 +1,80 @@
+"""Session transcript -> Markdown, for `/export`. A pure function of
+`history` (the same message list `session.Session` carries): user prompts as
+`## › …`, assistant text verbatim, tool calls as a compact fenced list with
+outcomes, and an offloaded result referenced by its artifact id rather than
+re-embedded in full."""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from . import session
+from .session import Message
+from .ui import format
+
+_ARTIFACT_RE = re.compile(r"saved as artifact ([0-9a-f]+)")
+_OUTCOME_CHARS = 120
+
+
+def _tool_call_args(call: dict[str, Any]) -> dict[str, Any]:
+    fn = call.get("function") or {}
+    try:
+        parsed = json.loads(fn.get("arguments") or "{}")
+    except json.JSONDecodeError:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _outcome(result: str) -> str:
+    m = _ARTIFACT_RE.search(result)
+    if m:
+        return f"[artifact {m.group(1)}]"
+    flat = " ".join(result.split())
+    return flat if len(flat) <= _OUTCOME_CHARS else flat[:_OUTCOME_CHARS - 1] + "…"
+
+
+def _tool_calls_block(tool_calls: list[dict[str, Any]], results: dict[str, str]) -> str:
+    lines = []
+    for call in tool_calls:
+        name = str((call.get("function") or {}).get("name", ""))
+        args = _tool_call_args(call)
+        result = results.get(str(call.get("id", "")), "")
+        lines.append(f"{format.describe_call(name, args)}  →  {_outcome(result)}")
+    return "```\n" + "\n".join(lines) + "\n```"
+
+
+def to_markdown(history: list[Message], session_id: str = "") -> str:
+    results: dict[str, str] = {
+        str(m.get("tool_call_id", "")): str(m.get("content", ""))
+        for m in history if m.get("role") == "tool"
+    }
+
+    parts: list[str] = [f"# omega session {session_id}"] if session_id else []
+    for msg in history:
+        role = msg.get("role")
+        if role == "user":
+            content = str(msg.get("content", ""))
+            if content.startswith(session.RESUME_PREFIX):
+                continue
+            parts.append(f"## › {content}")
+        elif role == "assistant":
+            assistant_text = msg.get("content")
+            if assistant_text:
+                parts.append(str(assistant_text))
+            tool_calls = msg.get("tool_calls")
+            if tool_calls:
+                parts.append(_tool_calls_block(tool_calls, results))
+    return "\n\n".join(parts) + "\n"
+
+
+def default_path(session_id: str) -> Path:
+    return session.DIR / session_id / "transcript.md"
+
+
+def write(history: list[Message], session_id: str, path: str | None = None) -> Path:
+    out = Path(path).expanduser() if path else default_path(session_id)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(to_markdown(history, session_id))
+    return out