codetrail-cli 1.4.1__py3-none-any.whl

codetrail/assistant/codex.py

@@ -0,0 +1,260 @@
+"""The codex adapter: the reader's own `codex exec`, in a read-only sandbox, on the reader's sign-in (design 15.1).
+
+Codex's tools are shell commands, and its read-only sandbox prevents writes, not reads, so Codetrail can't confine it to
+`source/`; targets must opt in to it (section 15.5). Each call runs with an empty temporary `HOME`, `/bin/sh`, no
+`USER` or `LOGNAME`, the reader's `CODEX_HOME` for the sign-in, and `-c` overrides that switch off the reader's MCP
+servers, notifications and shell environment and the target's `AGENTS.md`. The prompt goes in on stdin; structured
+answers follow `--output-schema`; tokens come from `turn.completed` events. Answers are buffered, not streamed, so the
+bridge can scan the whole text before the reader sees it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import tempfile
+from collections.abc import AsyncIterator, Iterator, Mapping
+from contextlib import aclosing, contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Final
+
+import anyio
+
+from codetrail.assistant import (
+    AnswerChunk,
+    AssistantError,
+    DigestDraft,
+    DigestRequest,
+    GradeRequest,
+    PageDraft,
+    PageRequest,
+    PlanDraft,
+    PlanRequest,
+    QuestionRequest,
+    Usage,
+    Verdict,
+    runner,
+)
+from codetrail.assistant.environment import child_environment, resolve_program
+from codetrail.assistant.prompts import (
+    ANSWER_RULES,
+    DIGEST_SCHEMA,
+    GRADE_RULES,
+    GRADE_SCHEMA,
+    GROUND_RULES,
+    PAGE_SYNTAX,
+    PLAN_SCHEMA,
+    answer_prompt,
+    digest_prompt,
+    grade_prompt,
+    neutralize,
+    page_task,
+    plan_prompt,
+)
+from codetrail.config import CodexSettings, GenerationSettings
+
+PROVIDER: Final = "codex"
+# Switch off what the reader's Codex configuration and the target's instructions could add (design section 15.5).
+ISOLATION = ("mcp_servers={}", "notify=[]", "project_doc_max_bytes=0", 'shell_environment_policy.inherit="none"')
+
+
+class _ProgramFailed(AssistantError):
+    """The program ended without an answer: worth another try."""
+
+
+@dataclass
+class _Outcome:
+    message: str | None = None
+    failure: str | None = None
+    input_tokens: int = 0
+    cached_input_tokens: int = 0
+    output_tokens: int = 0
+    files_read: list[str] = field(default_factory=list)
+
+
+class CodexAssistant:
+    def __init__(
+        self,
+        source_root: Path,
+        models: Mapping[str, str],
+        settings: CodexSettings,
+        limits: GenerationSettings,
+        retries: int = 2,
+        environ: Mapping[str, str] = os.environ,
+    ) -> None:
+        self.root = source_root.resolve()
+        self.models = dict(models)
+        self.settings = settings
+        self.limits = limits
+        self.retries = retries
+        self.environ = dict(environ)
+        self.program = resolve_program(settings.command, self.environ.get("PATH", ""))
+
+    async def plan(self, request: PlanRequest) -> PlanDraft:
+        data, outcome, usage = await self._run("plan", GROUND_RULES, plan_prompt(request), PLAN_SCHEMA)
+        return PlanDraft(list(data.get("pages", [])), list(data.get("paths", [])), outcome.files_read, 0.0, usage)
+
+    async def write_page(self, request: PageRequest) -> PageDraft:
+        prompt, schema = page_task(request)  # a new page, or a revision's sections
+        data, outcome, usage = await self._run("write", GROUND_RULES + "\n" + PAGE_SYNTAX, prompt, schema)
+        return PageDraft(str(data.get("body", "")), list(data.get("checks", [])), outcome.files_read, 0.0, usage,
+                         list(data.get("sections", [])), str(data.get("brief", "")))  # fmt: skip
+
+    async def write_digest(self, request: DigestRequest) -> DigestDraft:
+        data, outcome, usage = await self._run(
+            "digest", GROUND_RULES + "\n" + PAGE_SYNTAX, digest_prompt(request), DIGEST_SCHEMA
+        )
+        return DigestDraft(str(data.get("title", "")), str(data.get("body", "")), outcome.files_read, 0.0, usage)
+
+    async def grade(self, request: GradeRequest) -> Verdict:
+        data, _outcome, usage = await self._run("grade", GRADE_RULES, grade_prompt(request), GRADE_SCHEMA)
+        missed = [str(item) for item in data.get("missed", [])]
+        return Verdict(str(data.get("verdict", "")), missed, str(data.get("feedback", "")), 0.0, usage)
+
+    async def answer(self, request: QuestionRequest) -> AsyncIterator[AnswerChunk]:
+        outcome = await self._call(
+            "answer", GROUND_RULES + "\n" + PAGE_SYNTAX + "\n" + ANSWER_RULES, answer_prompt(request), None
+        )
+        # One final chunk: the bridge shows it only after scanning it (design section 15.5).
+        yield AnswerChunk(outcome.message or "", True, outcome.files_read, usage=self._usage("answer", outcome))
+
+    async def _run(
+        self, kind: str, rules: str, prompt: str, schema: dict[str, Any]
+    ) -> tuple[dict[str, Any], _Outcome, Usage]:
+        last_error: Exception | None = None
+        for attempt in range(self.retries + 1):
+            if attempt:
+                await anyio.sleep(2)
+            try:
+                outcome = await self._call(kind, rules, prompt, schema)
+            except _ProgramFailed as error:
+                last_error = error
+                continue
+            try:
+                data = json.loads(outcome.message or "")
+            except ValueError as error:
+                raise AssistantError("Codex's answer wasn't the JSON it was asked for.") from error
+            if not isinstance(data, dict):
+                raise AssistantError("Codex's answer wasn't a JSON object.")
+            return data, outcome, self._usage(kind, outcome)
+        raise last_error or AssistantError("Codex couldn't be run.")
+
+    async def _call(self, kind: str, rules: str, prompt: str, schema: dict[str, Any] | None) -> _Outcome:
+        outcome = _Outcome()
+        with self._call_folder() as folder:
+            environment = child_environment(PROVIDER, self.settings.auth, self.environ, empty_home=folder / "home")
+            command = [
+                self.program,
+                "exec",
+                "-",
+                "--sandbox",
+                "read-only",
+                "--json",
+                "--ephemeral",
+                "--skip-git-repo-check",
+                "-C",
+                str(self.root),
+            ]
+            for override in ISOLATION:
+                command += ["-c", override]
+            model = self.models.get(kind, "")
+            if model:
+                command += ["-m", model]
+            if schema is not None:
+                schema_file = folder / "schema.json"
+                schema_file.write_text(json.dumps(schema), encoding="utf-8")
+                command += ["--output-schema", str(schema_file)]
+            # Codex has no system prompt flag; Codetrail's rules lead the prompt, above the task.
+            text = neutralize(f"{rules}\n\n{prompt}")
+            try:
+                lines = runner.run_program(command, text, self.root, environment, self.settings.timeout_seconds)
+                async with aclosing(lines):
+                    async for line in lines:
+                        self._note(line, outcome)
+            except _LimitPassed:
+                raise
+            except AssistantError as error:
+                if outcome.message is None:
+                    raise _ProgramFailed(str(error)) from error
+                raise
+        if outcome.failure is not None:
+            raise AssistantError(f"Codex didn't finish the task: {outcome.failure[:300]}")
+        if outcome.message is None:
+            raise _ProgramFailed("Codex ended without an answer.")
+        return outcome
+
+    def _note(self, line: str, outcome: _Outcome) -> None:
+        try:
+            event = json.loads(line)
+        except ValueError:
+            return
+        if not isinstance(event, dict):
+            return
+        kind = event.get("type")
+        found = event.get("item")
+        item: dict[str, Any] = found if isinstance(found, dict) else {}
+        if kind == "item.completed" and item.get("type") == "agent_message":
+            outcome.message = str(item.get("text", ""))
+        elif kind == "item.completed" and item.get("type") == "command_execution":
+            for path in self._paths_in(str(item.get("command", ""))):
+                if path not in outcome.files_read:
+                    outcome.files_read.append(path)
+        elif kind == "turn.completed":
+            usage = event.get("usage") or {}
+            outcome.input_tokens += _count(usage, "input_tokens")
+            outcome.cached_input_tokens += _count(usage, "cached_input_tokens")
+            outcome.output_tokens += _count(usage, "output_tokens")
+            if outcome.input_tokens + outcome.output_tokens > self.settings.max_tokens_per_call:
+                raise _LimitPassed(
+                    f"Codex passed its token limit ({self.settings.max_tokens_per_call}) and was stopped."
+                )
+        elif kind == "turn.failed":
+            outcome.failure = str((event.get("error") or {}).get("message", "the turn failed"))
+        elif kind == "error":
+            outcome.failure = str(event.get("message", "an error"))
+
+    def _paths_in(self, command: str) -> list[str]:
+        """Files inside `source/` that a command names: a best-effort record of what Codex read."""
+        words = _words(command)
+        words += [inner for word in words if " " in word for inner in _words(word)]  # bash -lc '<script>'
+        found = []
+        for word in words:
+            candidate = Path(word) if os.path.isabs(word) else self.root / word
+            candidate = candidate.resolve()
+            if candidate.is_relative_to(self.root) and candidate.is_file():
+                found.append(candidate.relative_to(self.root).as_posix())
+        return found
+
+    def _usage(self, kind: str, outcome: _Outcome) -> Usage:
+        return Usage(
+            PROVIDER,
+            self.models.get(kind, ""),
+            outcome.input_tokens - outcome.cached_input_tokens,
+            outcome.cached_input_tokens,
+            outcome.output_tokens,
+        )
+
+    @contextmanager
+    def _call_folder(self) -> Iterator[Path]:
+        """A private folder outside `source/` for the schema file and the empty `HOME`, removed after the call."""
+        with tempfile.TemporaryDirectory(prefix="codetrail-codex-") as folder:
+            (Path(folder) / "home").mkdir(mode=0o700)
+            yield Path(folder)
+
+
+class _LimitPassed(AssistantError):
+    """The call passed its token limit; not worth another try."""
+
+
+def _words(command: str) -> list[str]:
+    try:
+        return shlex.split(command)
+    except ValueError:
+        return command.split()
+
+
+def _count(usage: Mapping[str, Any], key: str) -> int:
+    value = usage.get(key, 0)
+    return int(value) if isinstance(value, int | float) else 0

codetrail/assistant/environment.py

@@ -0,0 +1,66 @@
+"""The environment a provider's program starts with: an allowlist, so no key or token leaks in (design 15.2).
+
+With `subscription`, no key variable is passed, so the program can only use its own saved sign-in. With `api_key`, the
+provider's key variables pass by name; Codetrail never reads their values. Codex also gets an empty `HOME` and a plain
+shell, so no profile runs and `~` leads nowhere (section 15.5). Relative `PATH` entries are dropped, and programs are
+resolved to absolute paths before they start.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Literal
+
+from codetrail.assistant import AssistantError
+
+Provider = Literal["claude_code", "codex"]
+Auth = Literal["subscription", "api_key"]
+
+# Claude Code's sign-in on macOS lives in the Keychain, which needs USER and LOGNAME (checked on 5 October 2026).
+CLAUDE_NAMES = ("HOME", "USER", "LOGNAME", "LANG", "TMPDIR", "TERM", "CLAUDE_CONFIG_DIR")
+CODEX_NAMES = ("LANG", "TMPDIR", "TERM")
+KEY_NAMES: dict[Provider, tuple[str, ...]] = {
+    "claude_code": ("ANTHROPIC_API_KEY",),
+    "codex": ("OPENAI_API_KEY", "CODEX_API_KEY"),
+}
+
+
+def safe_path(value: str) -> str:
+    """`PATH` without empty or relative entries, which would resolve against the working folder (`source/`)."""
+    return os.pathsep.join(entry for entry in value.split(os.pathsep) if entry and os.path.isabs(entry))
+
+
+def child_environment(
+    provider: Provider, auth: Auth, environ: Mapping[str, str] = os.environ, empty_home: Path | None = None
+) -> dict[str, str]:
+    names = CLAUDE_NAMES if provider == "claude_code" else CODEX_NAMES
+    environment = {name: environ[name] for name in names if name in environ}
+    environment |= {name: value for name, value in environ.items() if name.startswith("LC_")}
+    environment["PATH"] = safe_path(environ.get("PATH", ""))
+    if provider == "codex":
+        if empty_home is None:
+            raise AssistantError("Codex needs an empty folder for its HOME.")
+        codex_home = environ.get("CODEX_HOME") or str(Path(environ.get("HOME", str(Path.home()))) / ".codex")
+        if not os.path.isabs(codex_home):
+            raise AssistantError(f"CODEX_HOME must be an absolute path, not {codex_home!r}.")
+        environment |= {"HOME": str(empty_home), "SHELL": "/bin/sh", "CODEX_HOME": codex_home}
+    if auth == "api_key":
+        environment |= {name: environ[name] for name in KEY_NAMES[provider] if name in environ}
+    return environment
+
+
+def resolve_program(command: str, path: str) -> str:
+    """The program's absolute path, found only through absolute `PATH` entries."""
+    if os.sep in command:
+        if not os.path.isabs(command):
+            raise AssistantError(f"The program {command!r} must be a name on PATH or an absolute path.")
+        if not os.access(command, os.X_OK):
+            raise AssistantError(f"{command} isn't installed or isn't executable.")
+        return command
+    found = shutil.which(command, path=safe_path(path))
+    if found is None:
+        raise AssistantError(f"{command} isn't installed (it isn't on PATH).")
+    return found

codetrail/assistant/estimate.py

@@ -0,0 +1,225 @@
+"""Estimates of what assistant calls will use, before they are made; they never call a provider (design 15.4).
+
+Tokens per call are the median of the last `estimates.history_size` recorded calls of the same kind, provider and
+model, once there are three; before that, the starting values in `[estimates]`. The cost is the median recorded cost,
+or the tokens at the configured prices; local models cost nothing; a model with no price has tokens only.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from statistics import median
+
+from codetrail.assistant import Usage
+from codetrail.assistant.usage import priced
+from codetrail.config import EstimateSettings, Price
+
+MIN_HISTORY = 3
+
+
+@dataclass(frozen=True)
+class CallEstimate:
+    kind: str
+    provider: str
+    model: str
+    input_tokens: int
+    output_tokens: int
+    cost_usd: float | None  # None when the model has no configured price
+    from_history: bool
+
+    @property
+    def tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+
+@dataclass(frozen=True)
+class PlanUsageReading:
+    provider: str
+    window: str
+    utilization: float
+    resets_at: int
+    observed_at: str
+
+
+def estimate_call(
+    connection: sqlite3.Connection,
+    kind: str,
+    provider: str,
+    model: str,
+    settings: EstimateSettings,
+    prices: Mapping[str, Price],
+) -> CallEstimate:
+    rows = connection.execute(
+        "SELECT input_tokens, cached_input_tokens, output_tokens, cost_usd FROM assistant_calls"
+        " WHERE kind = ? AND provider = ? AND model = ? ORDER BY id DESC LIMIT ?",
+        (kind, provider, model, settings.history_size),
+    ).fetchall()
+    if len(rows) >= MIN_HISTORY:
+        input_tokens = int(median(row["input_tokens"] + row["cached_input_tokens"] for row in rows))
+        output_tokens = int(median(row["output_tokens"] for row in rows))
+        costs = [row["cost_usd"] for row in rows if row["cost_usd"] is not None]
+        cost = float(median(costs)) if costs else priced(Usage(provider, model, input_tokens, 0, output_tokens), prices)
+        return CallEstimate(kind, provider, model, input_tokens, output_tokens, cost, True)
+    guess = getattr(settings, kind)
+    cost = priced(Usage(provider, model, guess.input, 0, guess.output), prices)
+    return CallEstimate(kind, provider, model, guess.input, guess.output, cost, False)
+
+
+def plan_usage(connection: sqlite3.Connection) -> list[PlanUsageReading]:
+    rows = connection.execute(
+        "SELECT provider, window, utilization, resets_at, observed_at FROM plan_usage ORDER BY provider, window"
+    ).fetchall()
+    return [PlanUsageReading(row["provider"], row["window"], float(row["utilization"]), int(row["resets_at"]),
+                             str(row["observed_at"])) for row in rows]  # fmt: skip
+
+
+@dataclass(frozen=True)
+class EstimateLine:
+    call: CallEstimate
+    expected: int  # how many calls are expected
+    maximum: int  # how many at most
+
+
+@dataclass(frozen=True)
+class PageToWrite:
+    """A page the update expects to write, and why: "new", "outline" (its outline entry changed), "update" (`changed`
+    of its facts changed in this update) or "catching_up" (they changed in an earlier update)."""
+
+    title: str
+    reason: str
+    changed: int = 0
+    revise: bool = False  # revised (design 6.3): only the sections the changes affect are rewritten
+
+
+@dataclass(frozen=True)
+class UpdateEstimate:
+    """What an update's paid calls are expected to use, and at most, before it starts (design section 15.4)."""
+
+    lines: list[EstimateLine]
+    sign_ins: dict[str, str]  # provider -> how it is signed in
+    plan_usage: list[PlanUsageReading]
+    budget_usd: float  # the update's own limits: generation.max_budget_usd_per_update
+    budget_tokens: int  # and generation.max_tokens_per_update, which counts every provider
+    pages: list[PageToWrite] = field(default_factory=list)  # in the order they're written; empty before an outline
+    skipped: list[str] = field(default_factory=list)  # titles of pages that failed before and haven't changed
+
+    @property
+    def expected_tokens(self) -> int:
+        return sum(line.call.tokens * line.expected for line in self.lines)
+
+    @property
+    def maximum_tokens(self) -> int:
+        return min(sum(line.call.tokens * line.maximum for line in self.lines), self.budget_tokens)
+
+    @property
+    def expected_usd(self) -> float | None:
+        return _dollars(self.lines, expected=True)
+
+    @property
+    def maximum_usd(self) -> float | None:
+        total = _dollars(self.lines, expected=False)
+        return None if total is None else min(total, self.budget_usd)
+
+    def as_json(self) -> dict[str, object]:
+        return {
+            "lines": [{"kind": line.call.kind, "provider": line.call.provider, "model": line.call.model,
+                       "expected": line.expected, "maximum": line.maximum, "tokens_each": line.call.tokens,
+                       "cost_each_usd": line.call.cost_usd, "from_history": line.call.from_history}
+                      for line in self.lines],
+            "expected_tokens": self.expected_tokens, "maximum_tokens": self.maximum_tokens,
+            "expected_usd": self.expected_usd, "maximum_usd": self.maximum_usd,
+            "budget_usd": self.budget_usd, "budget_tokens": self.budget_tokens,
+            "sign_ins": self.sign_ins,
+            "pages": [{"title": page.title, "reason": page.reason, "changed": page.changed, "revise": page.revise}
+                      for page in self.pages],
+            "skipped": self.skipped,
+            "plan_usage": [{"provider": reading.provider, "window": reading.window,
+                            "utilization": reading.utilization, "resets_at": reading.resets_at,
+                            "observed_at": reading.observed_at} for reading in self.plan_usage],
+        }  # fmt: skip
+
+
+def estimate_update(
+    connection: sqlite3.Connection,
+    calls: list[tuple[str, str, str, int, int]],  # kind, provider, model, expected, maximum
+    settings: EstimateSettings,
+    prices: Mapping[str, Price],
+    sign_ins: Mapping[str, str],
+    budget_usd: float,
+    budget_tokens: int,
+    pages: list[PageToWrite] | None = None,
+    skipped: list[str] | None = None,
+) -> UpdateEstimate:
+    lines = [
+        EstimateLine(estimate_call(connection, kind, provider, model, settings, prices), expected, maximum)
+        for kind, provider, model, expected, maximum in calls
+        if maximum > 0
+    ]
+    return UpdateEstimate(lines, dict(sign_ins), plan_usage(connection), budget_usd, budget_tokens, pages or [],
+                          skipped or [])  # fmt: skip
+
+
+def _why(page: PageToWrite) -> str:
+    if page.reason == "update":
+        return f"{page.changed} of its facts changed in this update"
+    reasons = {"new": "a new page", "outline": "its outline entry changed",
+               "catching_up": "catching up, since its facts changed after it was written"}  # fmt: skip
+    return reasons.get(page.reason, page.reason)
+
+
+def _dollars(lines: list[EstimateLine], expected: bool) -> float | None:
+    total = 0.0
+    for line in lines:
+        count = line.expected if expected else line.maximum
+        if count and line.call.cost_usd is None:
+            return None
+        total += (line.call.cost_usd or 0.0) * count
+    return total
+
+
+def when_text(observed_at: str) -> str:
+    """A recorded UTC time for people: 2026-10-05 06:38 UTC."""
+    return observed_at[:16].replace("T", " ") + " UTC"
+
+
+def tokens_text(tokens: int) -> str:
+    """A token count for people: 950, 12k, 1.4M."""
+    if tokens >= 1_000_000:
+        return f"{tokens / 1_000_000:.1f}M"
+    if tokens >= 1_000:
+        return f"{round(tokens / 1_000)}k"
+    return str(tokens)
+
+
+def describe(estimate: UpdateEstimate) -> list[str]:
+    """The estimate as lines of text, for the command line."""
+    lines = ["This update will call:"]
+    for line in estimate.lines:
+        count = str(line.expected) if line.expected == line.maximum else f"{line.expected} to {line.maximum}"
+        cost = "free" if line.call.cost_usd == 0 else (
+            "no price configured" if line.call.cost_usd is None else f"~${line.call.cost_usd:.2f} each")  # fmt: skip
+        source = "" if line.call.from_history else " (a starting guess)"
+        lines.append(f"  {line.call.kind:<7} {line.call.provider} · {line.call.model or 'default model'}: "
+                     f"{count} call(s), ~{tokens_text(line.call.tokens)} tokens each{source}, {cost}")  # fmt: skip
+    expected, maximum = estimate.expected_usd, estimate.maximum_usd
+    money = "" if expected is None or maximum is None else f", ~${expected:.2f} (at most ${maximum:.2f})"
+    lines.append(f"Expected: ~{tokens_text(estimate.expected_tokens)} tokens (at most "
+                 f"~{tokens_text(estimate.maximum_tokens)}){money} at API prices. "
+                 f"The update stops at its budget of ${estimate.budget_usd:.2f} "
+                 f"or {tokens_text(estimate.budget_tokens)} tokens.")  # fmt: skip
+    if estimate.pages:
+        lines.append("Pages, in the order they're written:")
+        lines += [f"  {page.title}{' (revised)' if page.revise else ''}: {_why(page)}" for page in estimate.pages]
+    if estimate.skipped:
+        lines.append("Skipped, since they failed last time and nothing in them changed: " + ", ".join(estimate.skipped))
+    for provider, method in estimate.sign_ins.items():
+        if "subscription" in method.lower():
+            lines.append(f"{provider}: {method}, so no charge; the work counts against your plan's usage limits.")
+        elif provider != "local":
+            lines.append(f"{provider}: {method}, billed to that account at its prices.")
+    for reading in estimate.plan_usage:
+        lines.append(f"Plan usage ({reading.provider}, {reading.window.replace('_', ' ')}): "
+                     f"{reading.utilization:.0%}, as of {when_text(reading.observed_at)}.")  # fmt: skip
+    return lines

codetrail/assistant/fake.py

@@ -0,0 +1,74 @@
+"""A fake assistant for tests: it replays scripted drafts and records every request it was given."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from dataclasses import dataclass, field
+
+from codetrail.assistant import (
+    AnswerChunk,
+    AssistantError,
+    DigestDraft,
+    DigestRequest,
+    GradeRequest,
+    PageDraft,
+    PageRequest,
+    PlanDraft,
+    PlanRequest,
+    QuestionRequest,
+    Verdict,
+)
+
+PageScript = Callable[[PageRequest], PageDraft]
+
+
+@dataclass
+class FakeAssistant:
+    plans: list[PlanDraft] = field(default_factory=list)
+    pages: dict[str, list[PageDraft | Exception]] = field(default_factory=dict)
+    page_writer: PageScript | None = None
+    digests: list[DigestDraft] = field(default_factory=list)
+    answers: list[list[AnswerChunk] | Exception] = field(default_factory=list)
+    verdicts: list[Verdict | Exception] = field(default_factory=list)
+    requests: list[PlanRequest | PageRequest | DigestRequest | QuestionRequest | GradeRequest] = field(
+        default_factory=list
+    )
+
+    async def plan(self, request: PlanRequest) -> PlanDraft:
+        self.requests.append(request)
+        if not self.plans:
+            raise AssistantError("The fake has no plan scripted.")
+        return self.plans.pop(0)
+
+    async def write_page(self, request: PageRequest) -> PageDraft:
+        self.requests.append(request)
+        scripted = self.pages.get(request.page_id)
+        if scripted:
+            draft = scripted.pop(0)
+            if isinstance(draft, Exception):
+                raise draft
+            return draft
+        if self.page_writer is not None:
+            return self.page_writer(request)
+        raise AssistantError(f"The fake has no page scripted for {request.page_id}.")
+
+    async def write_digest(self, request: DigestRequest) -> DigestDraft:
+        self.requests.append(request)
+        if not self.digests:
+            return DigestDraft(title="Changes", body="Things changed.")
+        return self.digests.pop(0)
+
+    async def answer(self, request: QuestionRequest) -> AsyncIterator[AnswerChunk]:
+        self.requests.append(request)
+        scripted = self.answers.pop(0) if self.answers else [AnswerChunk("An answer."), AnswerChunk(done=True)]
+        if isinstance(scripted, Exception):
+            raise scripted
+        for chunk in scripted:
+            yield chunk
+
+    async def grade(self, request: GradeRequest) -> Verdict:
+        self.requests.append(request)
+        scripted = self.verdicts.pop(0) if self.verdicts else Verdict("pass", [], "Well explained.")
+        if isinstance(scripted, Exception):
+            raise scripted
+        return scripted