chatwright

Overview ¶

arena.go wires chatwright.dev/runtime/arena into the CLI as `chatwright arena run` and `chatwright arena report`. It is deliberately thin per this repository's own AGENTS.md ("the CLI is deliberately thin ... engine or wire logic never lives here"): every metric, every retry- breakdown count and the whole matrix-execution loop live in the arena package; this file only parses an arena.yaml config into arena.Matrix, calls arena.Run/arena.WriteReport, and persists what the arena package itself never writes to disk (see arena's own package doc comment) — bundles, the markdown report, and a machine-readable results.json.

example.go embeds this repository's own copy of the standard self-contained-scenario-document worked example — GreetBot's language- onboarding fixture, copied verbatim from chatwright.dev/runtime's own scenario/testdata/ (never re-authored; see run_test.go's own greetbotFixturePath) — so `chatwright run example` has something real to execute the moment a user installs this binary: no files of their own, no network call, no API key. The document's "bot" is exampleBot:greetbot (a bot compiled into chatwright.dev/runtime, no URL) and its one cast member is a cassette-replay provider (a canned recording, not a live model), so nothing about running it ever leaves the process.

KEEPING THE EMBEDDED CASSETTE IN SYNC: the cassette's entries are keyed by a hash of the whole actor Prompt, and Prompt.History embeds run-bundle wire types — so ANY change to those types (a renamed field, an added one) silently invalidates every key in this copy, and `chatwright run example` starts failing with a replay cache miss. It is not a copy that only drifts when someone edits it. When bumping chatwright.dev/runtime, re-copy scenario/testdata/cassettes/greetbot-language-onboarding.json from that module (it regenerates its own via a build-tag-guarded recorder) and re-run the tests here — TestRunExampleEndToEnd catches it, loudly, which is how the sdk Verdict->Freshness rename was caught on 2026-07-25.

chatwright.dev/runtime/scenario has no seam for supplying a Document or a cassette as in-memory bytes — scenario.ScenarioProvider.Load and, deeper, scenario.Build's own cassette loading (actor.LoadCassette) are both hard-wired to a filesystem path (see their own doc comments in that package: "Loading a cassette file is I/O this package only ever performs here, in Build"). So the embedded bytes are, whichever of the two materialize functions below is used, always written back out as real files before scenario.FileScenarioProvider ever sees them — a temporary, self-cleaning directory for a plain `chatwright run example`, or a directory the caller chose for `chatwright run example --write`. This is not a workaround bent around the runtime's API; it is that API, used exactly as every other document already is.

Command chatwright is the local command-line entry point for the Chatwright conversation execution platform. It is deliberately thin: the heavy lifting lives in chatwright.dev/runtime (platform emulation + the testing runtime) and chatwright.dev/sdk (the run-bundle wire model); this binary only fronts them from a terminal.

run.go wires chatwright.dev/runtime/scenario into the CLI as `chatwright run`. It is deliberately thin per this repository's own AGENTS.md ("the CLI is deliberately thin ... engine or wire logic never lives here"): loading, validating, resolving and executing a self-contained scenario document (https://chatwright.dev/formats/scenario-document/v1) all live in chatwright.dev/runtime/scenario; this file only parses flags, calls into that package, assembles the resulting sdk.Bundle (the one piece scenario.Build deliberately leaves to its caller — a bundle is a bundle-only, wire-typed concept with no runtime counterpart, exactly the same division run.AssembleBundleRun already draws for the arena subcommand) and writes it to disk.

server.go wires chatwright.dev/cli/internal/server into the CLI as `chatwright server serve|start|stop|restart`. It is deliberately thin per this repository's own AGENTS.md ("the CLI is deliberately thin ... engine or wire logic never lives here"): every HTTP handler, the reverse proxy, the metrics ring buffer, the datastate evaluation seam, and the PID-file/ daemon primitives live in internal/server; this file only parses flags (falling back to environment variables, then fixed defaults), and calls into that package.