teamrunner 0.0.3__tar.gz → 0.0.4__tar.gz

{teamrunner-0.0.3 → teamrunner-0.0.4}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -20,7 +20,7 @@ body:
     attributes:
       label: TeamRunner version
       description: The output of `teamrunner --version`
-      placeholder: teamrunner 0.0.3
+      placeholder: teamrunner 0.0.4
     validations:
       required: true
   - type: input

{teamrunner-0.0.3 → teamrunner-0.0.4}/.github/ISSUE_TEMPLATE/question.yml

@@ -15,4 +15,4 @@ body:
     id: version
     attributes:
       label: TeamRunner version, if it matters
-      placeholder: teamrunner 0.0.3
+      placeholder: teamrunner 0.0.4

{teamrunner-0.0.3 → teamrunner-0.0.4}/CHANGELOG.md

@@ -4,6 +4,46 @@ TeamRunner is in preview: 0.0.x versions are a soft launch, and until 0.1.0
 is announced a version may change in ways that break teams and run folders
 made with an earlier one. Each such change is listed here.
 
+## 0.0.4
+
+- **Local browser interface:** `teamrunner ui [folder]` (`gui` is an alias)
+  opens the team's files in a browser. Edit with offline syntax highlighting,
+  save, validate with clickable problems, inspect resolved instructions and
+  flow diagrams, create teams from examples, manage members and set up keys.
+- Start one run at a time with defaults, a message, a file or a task file;
+  rehearse for free, follow events live, stop cleanly and re-run saved inputs
+  with the current team. Browse and search run history, read conversations,
+  outputs and records, inspect what members could read, and download raw files.
+- Compare two runs' numbered member versions, outputs, cost and paths. New
+  event logs keep exact member source text and fingerprints, the declared
+  flow graph and the recorded engine path for source diffs and arrow counts.
+  Older logs remain readable and label missing historical data explicitly.
+  A saved `resolved/team.yaml`, when present, can be copied to a new team for
+  editing; ordinary runs do not yet save a complete resolved team.
+- The interface uses the CLI's Python functions, adds no Python runtime
+  dependencies or database, and bundles its editor, Markdown renderer and
+  Mermaid diagrams for offline use. It binds only to `127.0.0.1`, requires a
+  random access token, confines editing to the opened folder, keeps run
+  records read-only and never displays stored key values.
+- The README's tutorial gives a browser alternative beside each CLI step.
+- UI review fixes: teams under an unrelated folder named `runs` remain editable;
+  actual run records stay read-only. Case-only renames work on macOS, rename
+  selects the old filename, and new-member names are checked before creation.
+  Non-UTF-8 files and validation in an empty workspace show friendly messages.
+- Files changed on disk reload automatically when there are no unsaved edits.
+  The file tree refreshes automatically and after runs finish. macOS uses its
+  native Trash operation, preserving Finder's Put Back support. The runs list
+  keeps comparison controls aligned and offers column navigation on narrow screens.
+- Live transcripts append new cards and populate read context on demand;
+  member-version history is cached in memory and invalidated when run files change.
+  The historical diagram helpers have been reformatted for readability.
+- **Two email tools**: `read_email` hands a member one email from a folder of
+  `.eml` files in the package (`mailbox`, `max_chars`); `save_draft` saves a
+  reply in the run's `work/outbox/` and never sends it. By default a draft can
+  answer only the email's sender (`reply_only: false` lifts that).
+- Runs started in the same second get their own folders instead of failing
+  with `FileExistsError`.
+
 ## 0.0.3
 
 - **Backup models**: `model:` and `default_model:` may name several models,

{teamrunner-0.0.3 → teamrunner-0.0.4}/NOTICE

@@ -5,7 +5,17 @@ TeamRunner is licensed under GPL-3.0-or-later (see LICENSE). The shipped
 examples, the files `teamrunner new` writes and the authoring guide are
 MIT-0 (see examples/LICENSE).
 
-TeamRunner bundles no third-party code. It depends on these packages, which
+TeamRunner bundles CodeMirror 5.65.21 (MIT), by Marijn Haverbeke and others,
+for offline browser editing. Its licence and pinned source information are
+in src/teamrunner/ui/static/vendor/LICENSE and SOURCE.txt.
+The offline run viewer also bundles Marked 18.1.3 (MIT) and DOMPurify
+3.4.17 (Apache-2.0 OR MPL-2.0). Their licences and pinned source information
+are in the same vendor folder, under marked-* and dompurify-*.
+
+Offline flow diagrams bundle Mermaid 12.3.0 (MIT); its licence, source
+information and bundled dependency notices are in vendor/mermaid-*.
+
+It depends on these packages, which
 pip installs separately, each under its own licence:
 
   LiteLLM        MIT

{teamrunner-0.0.3 → teamrunner-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: teamrunner
-Version: 0.0.3
+Version: 0.0.4
 Summary: The experimentation platform for agent organizations — run multi-agent orchestrations and factorial experiments entirely from text files.
 Project-URL: Homepage, https://github.com/teamrunner/teamrunner
 Project-URL: Repository, https://github.com/teamrunner/teamrunner
@@ -68,6 +68,7 @@ No Python. No graph-building API. No framework vocabulary. If you can edit a tex
 - [Why we built it](#why-we-built-it)
 - [The five ideas](#the-five-ideas)
 - [Tutorial: your first debate in 10 minutes](#tutorial-your-first-debate-in-10-minutes)
+- [Use TeamRunner in your browser](#use-teamrunner-in-your-browser)
 - [What lands in a run folder](#what-lands-in-a-run-folder)
   - [What your runs keep, and where your words go](#what-your-runs-keep-and-where-your-words-go)
 - [Going further: the worked examples](#going-further-the-worked-examples)
@@ -164,7 +165,7 @@ Two more ideas are designed but not built yet — a whiteboard for who sees what
 
 We'll build a three-agent debate, run it, give it rounds, a fact checker and the web. Zero code throughout. Turning it into a 40-run experiment comes with 0.2: see [PREVIEW.md](PREVIEW.md#experiments-v02).
 
-> Everything in this tutorial works in the preview. See [Status](#status-and-roadmap).
+> Every step works in a terminal, and from 0.0.4 also in your browser: see [Use TeamRunner in your browser](#use-teamrunner-in-your-browser).
 
 ### Step 0 — install
 
@@ -185,6 +186,8 @@ Keys stay with you, never with your teams: team folders get copied, zipped and s
 
 Models on your own machine work too, free: install [Ollama](https://ollama.com), pull a model (`ollama pull gpt-oss:20b`), and write `default_model: ollama/gpt-oss:20b` in `team.yaml`. If Ollama runs somewhere other than this computer, put its address in the key file as `OLLAMA_API_BASE`. Choose one of about 20 billion parameters or more: the smallest models often fail at exactly what teams need most — answering in a fixed form and asking toolkeepers properly — so they test the wiring better than they stand in for a real team. Before the first turn of every run, TeamRunner checks that each model your team names is available and lists every problem it finds in one table, so you never pay for half a run. `teamrunner validate --online` runs the same check without a run.
 
+Or open `teamrunner ui` and choose **Set up keys** after selecting a team. It saves keys to the same key file and shows whether each key is present, never its saved value. **Check keys and models online** is a separate check.
+
 ### Step 1 — make a team
 
 ```bash
@@ -199,6 +202,8 @@ Two other ways to start, when you'd rather not begin from nothing:
 - `teamrunner new my_debate --from fact_checked` copies one of the examples that ship with TeamRunner (or any team folder you name), with fresh ids; each file remembers what it was copied from.
 - `teamrunner new my_debate --describe "two debaters argue a topic, a fact checker checks each speech, and a judge decides"` asks a model to write the team for you. It checks its own work with `validate`, never overwrites files, tells you what it cost, and ends by printing `teamrunner explain`, so you can read what it made before you run it. (If you work with an AI coding assistant, `teamrunner skill` gives it the same instructions: it installs a skill for Claude Code and Codex, and `teamrunner skill --agents-md <folder>` writes an `AGENTS.md` for other assistants that read one.)
 
+Or run `teamrunner ui` in the folder where you want to keep your teams. Choose **New team**, enter `debate`, and select an empty team or a shipped example. Select `team.yaml` on the left to edit it.
+
 This tutorial starts from nothing, so you see every file.
 
 `team.yaml` is the only required file. It marks the folder as a team, says what the team does, and names the model its agents run on:
@@ -220,6 +225,8 @@ Two things worth knowing now:
 
 An agent file is Markdown. Frontmatter configures, body prompts.
 
+In the browser, select the team, choose **New member** for each Markdown file below, and paste its contents into the editor. **Save** (Ctrl/Cmd+S), then use **Show as it will run** to read the instructions with inputs filled in.
+
 ```markdown
 <!-- advocate.md -->
 ---
@@ -314,6 +321,8 @@ teamrunner run . --message "Four-day weeks make teams more productive"
 
 The first runs the default topic; the second replaces it. Either way, the run log records the topic and whether it was given or the default.
 
+Or do the editing, validation and running in `teamrunner ui .`: **Validate** checks the same files, and clicking a problem opens its file at the line to fix. Choose **Run…**, keep **Rehearse (free, no model)** checked for a free test, and start. To use a model, clear that checkbox; choose team defaults, a message, a file or a task file. The page shows the conversation as it happens and a **Stop run** button.
+
 What you see while it runs (the words are invented; the layout is the real one):
 
 ```
@@ -341,6 +350,8 @@ Each turn shows who spoke, what they decided, how long it took, what it cost and
 
 Later, `teamrunner runs` lists every run of this package — when, which team, the input, the result (`winner = advocate`), status, time and cost — and `teamrunner runs latest` (or `teamrunner runs 14:32`) shows one again exactly as it looked while it ran.
 
+In the browser, choose **Runs** to reopen the conversation, output, path or record. Select two runs with the checkboxes and choose **Compare selected runs** to see member versions, outputs, cost and paths side by side.
+
 That's a working multi-agent system: four text files, one command.
 
 ### Step 5 — take control of the flow
@@ -364,7 +375,7 @@ The flow grammar is deliberately tiny — it is a whiteboard sketch that happens
 - **[v0.3]** `[a, b]` — **at the same time**: `editor -> [reviewer_1, reviewer_2] -> editor` sends the paper to both reviewers at once, and the editor waits for both reports. Neither sees the other's work in progress.
 - `done` ends the flow — or, inside a named block, just that block; `stop` ends the whole run immediately.
 
-Now the debate runs `advocate → critic → advocate → critic → advocate → critic → judge`. To see it as a picture, `teamrunner explain --diagram` opens the flow as a flowchart in your browser.
+Now the debate runs `advocate → critic → advocate → critic → advocate → critic → judge`. To see it as a picture, `teamrunner explain --diagram` opens the flow as a flowchart in your browser. Or, in the local interface, refresh the file tree after adding `chair.md`, select it, and choose **Flow diagram**. Save an edit to redraw the diagram and plain-words summary.
 
 ### Step 6 — add a fact checker and a decision
 
@@ -459,10 +470,37 @@ A toolkeeper step means the member just before it must end its turn with a reque
 
 `teamrunner explain .` prints, in plain English, who may use which toolkeeper and on what terms.
 
-TeamRunner 0.1 has four built-in tools: `web_search_brave` (Brave Search), `read_page` (a link in, the page's text out), `read_file` (a file the run was given with `--file`, its text out) and `run_code` (Python in a sandbox: no internet unless the toolkeeper allows it, and files written only in the run's own work folder). The sandbox is Python running in WebAssembly, and it installs with TeamRunner — nothing else to set up; it can use packages built for it (numpy, pandas, scipy, sympy and many more), but not every package. `examples/fact_checked` gives the fact checker a second toolkeeper, `sandbox.md`, so it can check the sums in a claim by running them. A toolkeeper holds one tool in 0.1, so its limits always mean one thing; a member who needs two tools asks two toolkeepers, as the fact checker does here. `examples/reference_check` uses `read_page` and `read_file`: it checks every reference in a paper.
+TeamRunner 0.1 has six built-in tools: `web_search_brave` (Brave Search), `read_page` (a link in, the page's text out), `read_file` (a file the run was given with `--file`, its text out), `run_code` (Python in a sandbox: no internet unless the toolkeeper allows it, and files written only in the run's own work folder), `read_email` (one email from a folder of `.eml` files in the package) and `save_draft` (a reply saved in the run's `work/outbox/`, never sent, addressed only to the email's sender unless `reply_only: false`). The sandbox is Python running in WebAssembly, and it installs with TeamRunner — nothing else to set up; it can use packages built for it (numpy, pandas, scipy, sympy and many more), but not every package. `examples/fact_checked` gives the fact checker a second toolkeeper, `sandbox.md`, so it can check the sums in a claim by running them. A toolkeeper holds one tool in 0.1, so its limits always mean one thing; a member who needs two tools asks two toolkeepers, as the fact checker does here. `examples/reference_check` uses `read_page` and `read_file`: it checks every reference in a paper.
 
 ---
 
+## Use TeamRunner in your browser
+
+From 0.0.4, open a team folder with:
+
+```bash
+teamrunner ui debate
+```
+
+`teamrunner ui` opens the current folder when you leave out `debate`; `teamrunner gui` is an alias. To create teams, open their parent folder instead. The command opens a browser tab and prints its local address. Keep that terminal running while you work; press Ctrl+C there to stop the server. If the tab does not open, paste the full printed address, including its token, into your browser.
+
+The page works on the same files as the CLI. Choose a team or file on the left. You can create an empty team or copy a shipped example, add members, edit and save, rename members, or move files to the system trash. The editor warns about unsaved edits and files changed by another editor. Validation points to the file, line and suggested fix. **Show as it will run** fills in a member's instructions; **Flow diagram** shows the team's flow and summary. For a ready-made flow to edit, start from the `fact_checked` example.
+
+**Run…** accepts team defaults, a message, a file or a YAML task file. Rehearsal is selected by default for a team with no prior run; it uses placeholder words and random answers, needs no key and costs nothing. A model run uses your configured provider and its normal charges. The interface validates before starting, allows one active run at a time, streams the recorded events, and can stop the run cleanly. Key setup uses `~/.teamrunner/.env`; stored key values are never displayed.
+
+**Runs** is the archive. Filter by team or status, search the message and output, then open a run:
+
+- **Conversation:** member messages, decisions, tool calls, retries, tokens, models and cost, with a toggle for what each member could read.
+- **Path:** the saved flow with taken arrows highlighted and transition counts. Older logs without a saved engine path show only observed completed-turn transitions, labelled accordingly.
+- **Output:** the rendered `output.md`.
+- **Record:** inputs, numbered member versions, recorded settings and files. Version numbers come from the available run history.
+
+Select two runs to compare their outputs, cost, time, paths and member versions. Exact member source diffs are available for new logs that record the source and its fingerprint; older logs show their recorded prompts, which may include substituted inputs.
+
+**Re-run with these inputs…** uses the current team with the old run's input values and copied input files. It does not restore old member versions. **Edit a copy of the saved team…** appears only when a run contains `resolved/team.yaml`; it creates an independent team with fresh IDs and lineage. Open the teams' parent folder to give that copy a place outside the original team. Ordinary runs do not yet save a complete resolved team, so their original files cannot be reconstructed from prompts alone.
+
+Every run has **Open folder** and raw-file download links. The editor stays inside the folder you opened, and run records remain read-only. The server listens only on this computer at `127.0.0.1`, with a random access token. Editor, Markdown and diagram assets are bundled for offline use; model calls and online checks still need their usual services. The page adds no database or separate project format, and shows equivalent CLI commands alongside actions.
+
 ## What lands in a run folder
 
 Every run is logged in a `runs/` folder at the top of the package you ran — even when you run just one subteam (**[v0.3]**). The folder is git-ignored, so sharing the package never shares its history.
@@ -483,12 +521,12 @@ runs/01JZXG7T3M9QKWP5RVB2C8HD6N/
 
 | Event | What it records |
 |---|---|
-| `run_started` | the inputs, and every member exactly as it will run — model, settings, prompt |
+| `run_started` | the inputs, and every member exactly as it will run — model, settings, prompt; from 0.0.4, also each member's source text, content fingerprints and the declared flow graph |
 | `agent_message` | from, **to** (the *realized* topology), stage, attempt, **what it could read**, everything it said, typed outputs, the model actually used, tokens, cost, time |
 | `route_decision` | who decided, which option, which arrow — the audit trail for "no hidden if-statements" |
 | `tool_call` | who asked, which toolkeeper, the toolkeeper's yes or no, tool, arguments, the full result (for a search, how many results came back, unless `keep_results: true`) |
 | `state_write` **[v0.3]** | item, old → new, writer |
-| `check`, `retry`, `warning`, `error`, `run_finished` | the pre-run check, retries, warnings, failures, and the totals |
+| `check`, `retry`, `warning`, `error`, `run_finished` | the pre-run check, retries, warnings, failures, and the totals; from 0.0.4, `run_finished` also saves the path taken, for arrow counts |
 
 A field never changes its meaning between versions — later versions only add — so an analysis script you write today keeps working.
 
@@ -567,9 +605,10 @@ The recasting campaign is the point, not decoration: each one is run *before* th
 |---|---|
 | **Design** | Spec drafted; paper recasts written as pure text ✅ |
 | **0.1 · The org package** ← now: in preview as 0.0.x | A folder that gets a job done: validation with friendly errors, its own runner, the event log, toolkeepers and four built-in tools, rehearsals, `run`, `runs`, `explain`, `new`, the authoring skill ✅ |
+| **Before 0.2 · Local browser interface** | In 0.0.4 ✅ `teamrunner ui` / `gui`: edit, validate, rehearse or run, browse recorded conversations and paths, compare two runs |
 | **0.2 · Experiments** | Experiments outside the package (`base:`), factorial designs, seeded replications, manifests, response cache, the answer-key metric, `teamrunner experiment`, export; `promote` / `export`. First real result: leader vs. flat |
 | **0.3 · Richer organizations** | Managers and rules-table chairs, `whiteboard.yaml` (private information, sealed and conditional visibility, addressed messages), subteams, parallel work, announcers; the recasts run for real, and the Invisible Orchestrators replication |
-| **0.4+ · Later** | LLM-as-judge metrics, `teamrunner ui` (run browser, cross-run comparison, communication-graph visualization), template library of canonical org structures, human-in-the-loop, automated improvement, running packages in production |
+| **0.4+ · Later** | LLM-as-judge metrics, communication-network statistics and visualization, template library of canonical org structures, human-in-the-loop, automated improvement, running packages in production |
 
 Human-in-the-loop nodes (`kind: human` — the runner pauses and asks a person) are for mixed human–agent studies.
 
@@ -597,7 +636,7 @@ Inside a package, these names are reserved. **Every one of them is optional exce
 | `chair.md` | How a protocol team is run: the script, as the file's body, or a `kind: rules` table **[v0.3]** | Everyone may talk to everyone; members act in alphabetical filename order, one turn each |
 | `manager.md` **[v0.3]** | How a managed team is run: an LLM that decides who acts next; only it may use input placeholders. A team has at most one of `chair.md` and `manager.md` | — |
 | `whiteboard.yaml` **[v0.3]** | Who sees what: declared items with `read_by` / `written_by`, and who can read what each member says (`said`) | Everyone reads everything said; built-in items only (e.g. `stage`) |
-| `tools/` | Reserved for a package's own tools, which come after 0.1. In 0.1 toolkeepers use the built-ins: `web_search_brave`, `read_page`, `read_file`, `run_code` | Built-ins only |
+| `tools/` | Reserved for a package's own tools, which come after 0.1. In 0.1 toolkeepers use the built-ins: `web_search_brave`, `read_page`, `read_file`, `run_code`, `read_email`, `save_draft` | Built-ins only |
 | `models/` | Model profiles: a model and its settings in one `.yaml`, named by agents as `model: careful.yaml` or by `team.yaml` as `default_model:` | Agents name provider models directly |
 | `runs/` | Where every run of this package is logged, whichever team you started; git-ignored | Created on the first run |
 | *subfolder with `team.yaml`* **[v0.3]** | A subteam — a node in the parent flow, with its own whiteboard; the parent hears only its report (`report_from:`) | — |

{teamrunner-0.0.3 → teamrunner-0.0.4}/README.md

@@ -33,6 +33,7 @@ No Python. No graph-building API. No framework vocabulary. If you can edit a tex
 - [Why we built it](#why-we-built-it)
 - [The five ideas](#the-five-ideas)
 - [Tutorial: your first debate in 10 minutes](#tutorial-your-first-debate-in-10-minutes)
+- [Use TeamRunner in your browser](#use-teamrunner-in-your-browser)
 - [What lands in a run folder](#what-lands-in-a-run-folder)
   - [What your runs keep, and where your words go](#what-your-runs-keep-and-where-your-words-go)
 - [Going further: the worked examples](#going-further-the-worked-examples)
@@ -129,7 +130,7 @@ Two more ideas are designed but not built yet — a whiteboard for who sees what
 
 We'll build a three-agent debate, run it, give it rounds, a fact checker and the web. Zero code throughout. Turning it into a 40-run experiment comes with 0.2: see [PREVIEW.md](PREVIEW.md#experiments-v02).
 
-> Everything in this tutorial works in the preview. See [Status](#status-and-roadmap).
+> Every step works in a terminal, and from 0.0.4 also in your browser: see [Use TeamRunner in your browser](#use-teamrunner-in-your-browser).
 
 ### Step 0 — install
 
@@ -150,6 +151,8 @@ Keys stay with you, never with your teams: team folders get copied, zipped and s
 
 Models on your own machine work too, free: install [Ollama](https://ollama.com), pull a model (`ollama pull gpt-oss:20b`), and write `default_model: ollama/gpt-oss:20b` in `team.yaml`. If Ollama runs somewhere other than this computer, put its address in the key file as `OLLAMA_API_BASE`. Choose one of about 20 billion parameters or more: the smallest models often fail at exactly what teams need most — answering in a fixed form and asking toolkeepers properly — so they test the wiring better than they stand in for a real team. Before the first turn of every run, TeamRunner checks that each model your team names is available and lists every problem it finds in one table, so you never pay for half a run. `teamrunner validate --online` runs the same check without a run.
 
+Or open `teamrunner ui` and choose **Set up keys** after selecting a team. It saves keys to the same key file and shows whether each key is present, never its saved value. **Check keys and models online** is a separate check.
+
 ### Step 1 — make a team
 
 ```bash
@@ -164,6 +167,8 @@ Two other ways to start, when you'd rather not begin from nothing:
 - `teamrunner new my_debate --from fact_checked` copies one of the examples that ship with TeamRunner (or any team folder you name), with fresh ids; each file remembers what it was copied from.
 - `teamrunner new my_debate --describe "two debaters argue a topic, a fact checker checks each speech, and a judge decides"` asks a model to write the team for you. It checks its own work with `validate`, never overwrites files, tells you what it cost, and ends by printing `teamrunner explain`, so you can read what it made before you run it. (If you work with an AI coding assistant, `teamrunner skill` gives it the same instructions: it installs a skill for Claude Code and Codex, and `teamrunner skill --agents-md <folder>` writes an `AGENTS.md` for other assistants that read one.)
 
+Or run `teamrunner ui` in the folder where you want to keep your teams. Choose **New team**, enter `debate`, and select an empty team or a shipped example. Select `team.yaml` on the left to edit it.
+
 This tutorial starts from nothing, so you see every file.
 
 `team.yaml` is the only required file. It marks the folder as a team, says what the team does, and names the model its agents run on:
@@ -185,6 +190,8 @@ Two things worth knowing now:
 
 An agent file is Markdown. Frontmatter configures, body prompts.
 
+In the browser, select the team, choose **New member** for each Markdown file below, and paste its contents into the editor. **Save** (Ctrl/Cmd+S), then use **Show as it will run** to read the instructions with inputs filled in.
+
 ```markdown
 <!-- advocate.md -->
 ---
@@ -279,6 +286,8 @@ teamrunner run . --message "Four-day weeks make teams more productive"
 
 The first runs the default topic; the second replaces it. Either way, the run log records the topic and whether it was given or the default.
 
+Or do the editing, validation and running in `teamrunner ui .`: **Validate** checks the same files, and clicking a problem opens its file at the line to fix. Choose **Run…**, keep **Rehearse (free, no model)** checked for a free test, and start. To use a model, clear that checkbox; choose team defaults, a message, a file or a task file. The page shows the conversation as it happens and a **Stop run** button.
+
 What you see while it runs (the words are invented; the layout is the real one):
 
 ```
@@ -306,6 +315,8 @@ Each turn shows who spoke, what they decided, how long it took, what it cost and
 
 Later, `teamrunner runs` lists every run of this package — when, which team, the input, the result (`winner = advocate`), status, time and cost — and `teamrunner runs latest` (or `teamrunner runs 14:32`) shows one again exactly as it looked while it ran.
 
+In the browser, choose **Runs** to reopen the conversation, output, path or record. Select two runs with the checkboxes and choose **Compare selected runs** to see member versions, outputs, cost and paths side by side.
+
 That's a working multi-agent system: four text files, one command.
 
 ### Step 5 — take control of the flow
@@ -329,7 +340,7 @@ The flow grammar is deliberately tiny — it is a whiteboard sketch that happens
 - **[v0.3]** `[a, b]` — **at the same time**: `editor -> [reviewer_1, reviewer_2] -> editor` sends the paper to both reviewers at once, and the editor waits for both reports. Neither sees the other's work in progress.
 - `done` ends the flow — or, inside a named block, just that block; `stop` ends the whole run immediately.
 
-Now the debate runs `advocate → critic → advocate → critic → advocate → critic → judge`. To see it as a picture, `teamrunner explain --diagram` opens the flow as a flowchart in your browser.
+Now the debate runs `advocate → critic → advocate → critic → advocate → critic → judge`. To see it as a picture, `teamrunner explain --diagram` opens the flow as a flowchart in your browser. Or, in the local interface, refresh the file tree after adding `chair.md`, select it, and choose **Flow diagram**. Save an edit to redraw the diagram and plain-words summary.
 
 ### Step 6 — add a fact checker and a decision
 
@@ -424,10 +435,37 @@ A toolkeeper step means the member just before it must end its turn with a reque
 
 `teamrunner explain .` prints, in plain English, who may use which toolkeeper and on what terms.
 
-TeamRunner 0.1 has four built-in tools: `web_search_brave` (Brave Search), `read_page` (a link in, the page's text out), `read_file` (a file the run was given with `--file`, its text out) and `run_code` (Python in a sandbox: no internet unless the toolkeeper allows it, and files written only in the run's own work folder). The sandbox is Python running in WebAssembly, and it installs with TeamRunner — nothing else to set up; it can use packages built for it (numpy, pandas, scipy, sympy and many more), but not every package. `examples/fact_checked` gives the fact checker a second toolkeeper, `sandbox.md`, so it can check the sums in a claim by running them. A toolkeeper holds one tool in 0.1, so its limits always mean one thing; a member who needs two tools asks two toolkeepers, as the fact checker does here. `examples/reference_check` uses `read_page` and `read_file`: it checks every reference in a paper.
+TeamRunner 0.1 has six built-in tools: `web_search_brave` (Brave Search), `read_page` (a link in, the page's text out), `read_file` (a file the run was given with `--file`, its text out), `run_code` (Python in a sandbox: no internet unless the toolkeeper allows it, and files written only in the run's own work folder), `read_email` (one email from a folder of `.eml` files in the package) and `save_draft` (a reply saved in the run's `work/outbox/`, never sent, addressed only to the email's sender unless `reply_only: false`). The sandbox is Python running in WebAssembly, and it installs with TeamRunner — nothing else to set up; it can use packages built for it (numpy, pandas, scipy, sympy and many more), but not every package. `examples/fact_checked` gives the fact checker a second toolkeeper, `sandbox.md`, so it can check the sums in a claim by running them. A toolkeeper holds one tool in 0.1, so its limits always mean one thing; a member who needs two tools asks two toolkeepers, as the fact checker does here. `examples/reference_check` uses `read_page` and `read_file`: it checks every reference in a paper.
 
 ---
 
+## Use TeamRunner in your browser
+
+From 0.0.4, open a team folder with:
+
+```bash
+teamrunner ui debate
+```
+
+`teamrunner ui` opens the current folder when you leave out `debate`; `teamrunner gui` is an alias. To create teams, open their parent folder instead. The command opens a browser tab and prints its local address. Keep that terminal running while you work; press Ctrl+C there to stop the server. If the tab does not open, paste the full printed address, including its token, into your browser.
+
+The page works on the same files as the CLI. Choose a team or file on the left. You can create an empty team or copy a shipped example, add members, edit and save, rename members, or move files to the system trash. The editor warns about unsaved edits and files changed by another editor. Validation points to the file, line and suggested fix. **Show as it will run** fills in a member's instructions; **Flow diagram** shows the team's flow and summary. For a ready-made flow to edit, start from the `fact_checked` example.
+
+**Run…** accepts team defaults, a message, a file or a YAML task file. Rehearsal is selected by default for a team with no prior run; it uses placeholder words and random answers, needs no key and costs nothing. A model run uses your configured provider and its normal charges. The interface validates before starting, allows one active run at a time, streams the recorded events, and can stop the run cleanly. Key setup uses `~/.teamrunner/.env`; stored key values are never displayed.
+
+**Runs** is the archive. Filter by team or status, search the message and output, then open a run:
+
+- **Conversation:** member messages, decisions, tool calls, retries, tokens, models and cost, with a toggle for what each member could read.
+- **Path:** the saved flow with taken arrows highlighted and transition counts. Older logs without a saved engine path show only observed completed-turn transitions, labelled accordingly.
+- **Output:** the rendered `output.md`.
+- **Record:** inputs, numbered member versions, recorded settings and files. Version numbers come from the available run history.
+
+Select two runs to compare their outputs, cost, time, paths and member versions. Exact member source diffs are available for new logs that record the source and its fingerprint; older logs show their recorded prompts, which may include substituted inputs.
+
+**Re-run with these inputs…** uses the current team with the old run's input values and copied input files. It does not restore old member versions. **Edit a copy of the saved team…** appears only when a run contains `resolved/team.yaml`; it creates an independent team with fresh IDs and lineage. Open the teams' parent folder to give that copy a place outside the original team. Ordinary runs do not yet save a complete resolved team, so their original files cannot be reconstructed from prompts alone.
+
+Every run has **Open folder** and raw-file download links. The editor stays inside the folder you opened, and run records remain read-only. The server listens only on this computer at `127.0.0.1`, with a random access token. Editor, Markdown and diagram assets are bundled for offline use; model calls and online checks still need their usual services. The page adds no database or separate project format, and shows equivalent CLI commands alongside actions.
+
 ## What lands in a run folder
 
 Every run is logged in a `runs/` folder at the top of the package you ran — even when you run just one subteam (**[v0.3]**). The folder is git-ignored, so sharing the package never shares its history.
@@ -448,12 +486,12 @@ runs/01JZXG7T3M9QKWP5RVB2C8HD6N/
 
 | Event | What it records |
 |---|---|
-| `run_started` | the inputs, and every member exactly as it will run — model, settings, prompt |
+| `run_started` | the inputs, and every member exactly as it will run — model, settings, prompt; from 0.0.4, also each member's source text, content fingerprints and the declared flow graph |
 | `agent_message` | from, **to** (the *realized* topology), stage, attempt, **what it could read**, everything it said, typed outputs, the model actually used, tokens, cost, time |
 | `route_decision` | who decided, which option, which arrow — the audit trail for "no hidden if-statements" |
 | `tool_call` | who asked, which toolkeeper, the toolkeeper's yes or no, tool, arguments, the full result (for a search, how many results came back, unless `keep_results: true`) |
 | `state_write` **[v0.3]** | item, old → new, writer |
-| `check`, `retry`, `warning`, `error`, `run_finished` | the pre-run check, retries, warnings, failures, and the totals |
+| `check`, `retry`, `warning`, `error`, `run_finished` | the pre-run check, retries, warnings, failures, and the totals; from 0.0.4, `run_finished` also saves the path taken, for arrow counts |
 
 A field never changes its meaning between versions — later versions only add — so an analysis script you write today keeps working.
 
@@ -532,9 +570,10 @@ The recasting campaign is the point, not decoration: each one is run *before* th
 |---|---|
 | **Design** | Spec drafted; paper recasts written as pure text ✅ |
 | **0.1 · The org package** ← now: in preview as 0.0.x | A folder that gets a job done: validation with friendly errors, its own runner, the event log, toolkeepers and four built-in tools, rehearsals, `run`, `runs`, `explain`, `new`, the authoring skill ✅ |
+| **Before 0.2 · Local browser interface** | In 0.0.4 ✅ `teamrunner ui` / `gui`: edit, validate, rehearse or run, browse recorded conversations and paths, compare two runs |
 | **0.2 · Experiments** | Experiments outside the package (`base:`), factorial designs, seeded replications, manifests, response cache, the answer-key metric, `teamrunner experiment`, export; `promote` / `export`. First real result: leader vs. flat |
 | **0.3 · Richer organizations** | Managers and rules-table chairs, `whiteboard.yaml` (private information, sealed and conditional visibility, addressed messages), subteams, parallel work, announcers; the recasts run for real, and the Invisible Orchestrators replication |
-| **0.4+ · Later** | LLM-as-judge metrics, `teamrunner ui` (run browser, cross-run comparison, communication-graph visualization), template library of canonical org structures, human-in-the-loop, automated improvement, running packages in production |
+| **0.4+ · Later** | LLM-as-judge metrics, communication-network statistics and visualization, template library of canonical org structures, human-in-the-loop, automated improvement, running packages in production |
 
 Human-in-the-loop nodes (`kind: human` — the runner pauses and asks a person) are for mixed human–agent studies.
 
@@ -562,7 +601,7 @@ Inside a package, these names are reserved. **Every one of them is optional exce
 | `chair.md` | How a protocol team is run: the script, as the file's body, or a `kind: rules` table **[v0.3]** | Everyone may talk to everyone; members act in alphabetical filename order, one turn each |
 | `manager.md` **[v0.3]** | How a managed team is run: an LLM that decides who acts next; only it may use input placeholders. A team has at most one of `chair.md` and `manager.md` | — |
 | `whiteboard.yaml` **[v0.3]** | Who sees what: declared items with `read_by` / `written_by`, and who can read what each member says (`said`) | Everyone reads everything said; built-in items only (e.g. `stage`) |
-| `tools/` | Reserved for a package's own tools, which come after 0.1. In 0.1 toolkeepers use the built-ins: `web_search_brave`, `read_page`, `read_file`, `run_code` | Built-ins only |
+| `tools/` | Reserved for a package's own tools, which come after 0.1. In 0.1 toolkeepers use the built-ins: `web_search_brave`, `read_page`, `read_file`, `run_code`, `read_email`, `save_draft` | Built-ins only |
 | `models/` | Model profiles: a model and its settings in one `.yaml`, named by agents as `model: careful.yaml` or by `team.yaml` as `default_model:` | Agents name provider models directly |
 | `runs/` | Where every run of this package is logged, whichever team you started; git-ignored | Created on the first run |
 | *subfolder with `team.yaml`* **[v0.3]** | A subteam — a node in the parent flow, with its own whiteboard; the parent hears only its report (`report_from:`) | — |

{teamrunner-0.0.3 → teamrunner-0.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "teamrunner"
-version = "0.0.3"
+version = "0.0.4"
 description = "The experimentation platform for agent organizations — run multi-agent orchestrations and factorial experiments entirely from text files."
 readme = "README.md"
 license = "GPL-3.0-or-later AND MIT-0"

{teamrunner-0.0.3 → teamrunner-0.0.4}/src/teamrunner/__init__.py

@@ -11,7 +11,7 @@ https://github.com/teamrunner/teamrunner.
 
 import os as _os
 
-__version__ = "0.0.3"
+__version__ = "0.0.4"
 
 # LiteLLM fetches its price table from the internet on import unless told not to. TeamRunner
 # uses the table that came with the installed LiteLLM, so a run's prices depend only on what

{teamrunner-0.0.3 → teamrunner-0.0.4}/src/teamrunner/authoring/AGENTS.md

@@ -153,6 +153,8 @@ I search the web. Send me a query and I return the top five results.
 | `read_page` | a link → the page's text, PDFs too | `domains`, `max_chars`, `types: [pdf]` |
 | `read_file` | a file the run was given with `--file` → its text | `max_chars`, `types: [pdf]` |
 | `run_code` | Python → its output and errors, in a sandbox | `network: true` (off by default), `paths: [folder]` to read — the code finds it at `/package/<folder>` |
+| `read_email` | an email's id → its sender, recipients, date, subject and text, from a folder of `.eml` files in the package | `mailbox: <folder>` (`mailbox` if not written), `max_chars` |
+| `save_draft` | an email's id and a reply → the reply saved in the run's `work/outbox/`, never sent; it answers only the email's sender | `mailbox: <folder>`, `max_chars`, `reply_only: false` (lets a draft name any address) |
 
   Every tool also understands `calls_per_turn` (5 if not written),
   `calls_per_run` and `timeout` (seconds). Any other limit is an error.

{teamrunner-0.0.3 → teamrunner-0.0.4}/src/teamrunner/builtin_tools.py

@@ -298,6 +298,97 @@ async def run_code(args: dict, guardrails: dict, ctx: Context) -> Answer:
                   service=f"pyodide {sandbox.PYODIDE} (Python {ran.python}), deno {version('deno')}")
 
 
+# --- read_email and save_draft: a mailbox folder of .eml files --------------------------
+
+EMAIL_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,99}")
+DEFAULT_MAILBOX = "mailbox"
+
+
+def mailbox_folder(guardrails: dict, ctx: Context) -> Path:
+    """The mailbox this toolkeeper reads: a folder of .eml files, written relative to the package."""
+    written = str(guardrails.get("mailbox", DEFAULT_MAILBOX))
+    folder = Path(written).expanduser()
+    if not folder.is_absolute() and ctx.package_top is not None:
+        folder = ctx.package_top / folder
+    if not folder.is_dir():
+        raise Refused(f"the mailbox {written} that this toolkeeper reads does not exist")
+    return folder
+
+
+def find_email(asked: str, guardrails: dict, ctx: Context):
+    """One email in the mailbox, by its id (its file name without .eml)."""
+    from email import policy
+    from email.parser import BytesParser
+    asked = asked.strip().removesuffix(".eml")
+    if not EMAIL_ID.fullmatch(asked):
+        raise Refused("an email is asked for by its id, such as m001")
+    path = mailbox_folder(guardrails, ctx) / f"{asked}.eml"
+    if not path.is_file():
+        raise Refused(f"there is no email {asked} in the mailbox")
+    return asked, BytesParser(policy=policy.default).parsebytes(path.read_bytes())
+
+
+def email_text(message) -> str:
+    """The headers a reader needs, the body as plain text, and the names of any attachments."""
+    lines = [f"{h}: {message[h]}" for h in ("From", "To", "Cc", "Date", "Subject") if message[h]]
+    part = message.get_body(preferencelist=("plain", "html"))
+    body = "" if part is None else part.get_content()
+    if part is not None and part.get_content_type() == "text/html":
+        body = html_text(body)
+    attached = [p.get_filename() or p.get_content_type() for p in message.iter_attachments()]
+    if attached:
+        lines.append("Attachments: " + ", ".join(attached))
+    return "\n".join(lines) + "\n\n" + body.strip()
+
+
+async def read_email(args: dict, guardrails: dict, ctx: Context) -> Answer:
+    _, message = find_email(str(args.get("id", "")), guardrails, ctx)
+    return Answer(cut(email_text(message), guardrails), service="mailbox folder")
+
+
+async def save_draft(args: dict, guardrails: dict, ctx: Context) -> Answer:
+    """A reply saved to the run's work/outbox/, never sent. By default it goes to the
+    email's sender and no one else (`reply_only`)."""
+    from email.message import EmailMessage
+    from email.utils import getaddresses
+    asked, original = find_email(str(args.get("reply_to", "")), guardrails, ctx)
+    body = str(args.get("body", "")).strip()
+    if not body:
+        raise Refused("the draft was empty")
+    limit = guardrails.get("max_chars", DEFAULT_MAX_CHARS)
+    if len(body) > limit:
+        raise Refused(f"the draft is {len(body)} characters; this outbox takes at most {limit}")
+    sender = original.get("Reply-To") or original.get("From") or ""
+    sender_address = next((a for _, a in getaddresses([sender]) if a), "")
+    wanted = str(args.get("to") or "").strip()
+    wanted_addresses = [a for _, a in getaddresses([wanted]) if a]
+    if wanted and guardrails.get("reply_only", True):
+        if [a.lower() for a in wanted_addresses] != [sender_address.lower()]:
+            raise Refused("this outbox only answers the sender of the email "
+                          f"({sender_address}); it does not write to other addresses")
+    to = wanted if wanted and not guardrails.get("reply_only", True) else sender
+    if not to:
+        raise Refused(f"email {asked} has no sender to answer")
+    outbox = ctx.work_dir / "outbox"
+    path = outbox / f"{asked}.eml"
+    if path.exists():
+        raise Refused(f"a draft answering {asked} is already in the outbox")
+    draft = EmailMessage()
+    draft["To"] = to
+    if original["To"]:
+        draft["From"] = original["To"]
+    subject = str(original.get("Subject") or "")
+    draft["Subject"] = subject if subject.lower().startswith("re:") else f"Re: {subject}".strip()
+    if original["Message-ID"]:
+        draft["In-Reply-To"] = original["Message-ID"]
+    draft["X-TeamRunner"] = "draft, not sent"
+    draft.set_content(body + "\n", cte="8bit")  # readable as it is, in any text editor
+    outbox.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(bytes(draft))
+    return Answer(f"Saved a draft to {to} in the outbox as outbox/{asked}.eml. It has not been sent.",
+                  service="outbox folder")
+
+
 TOOLS: dict[str, Tool] = {
     "web_search_brave": Tool("web_search_brave", "Searches the web: a query in, titles, links and snippets out.",
                        {"type": "object", "properties": {"query": {"type": "string"}},
@@ -312,6 +403,18 @@ TOOLS: dict[str, Tool] = {
                      "errors out. Files it writes in the current folder are kept for the rest of the run.",
                      {"type": "object", "properties": {"code": {"type": "string"}},
                       "required": ["code"], "additionalProperties": False}, run_code),
+    "read_email": Tool("read_email", "Reads one email from the mailbox: its id in, its sender, "
+                       "recipients, date, subject and text out.",
+                       {"type": "object", "properties": {"id": {"type": "string"}},
+                        "required": ["id"], "additionalProperties": False}, read_email),
+    "save_draft": Tool("save_draft", "Saves a reply to an email in the outbox, where a person reads it "
+                       "before anything is sent: the id of the email it answers and the reply's text in. "
+                       "Nothing is sent.",
+                       {"type": "object", "properties": {
+                           "reply_to": {"type": "string", "description": "the id of the email this answers"},
+                           "body": {"type": "string", "description": "the reply's text"},
+                           "to": {"type": "string", "description": "who it goes to; leave out to answer the sender"}},
+                        "required": ["reply_to", "body"], "additionalProperties": False}, save_draft),
 }
 NOT_BUILT: dict[str, str] = {}  # tool -> why this version cannot run it yet
 TOOL_KEYS = {"web_search_brave": BRAVE_KEY}

{teamrunner-0.0.3 → teamrunner-0.0.4}/src/teamrunner/checks.py

@@ -23,6 +23,15 @@ from .keys import NO_KEY, PROVIDER_KEYS, SET_UP_ELSEWHERE, Keys
 Lister = Callable[[str | None, dict], "set[str] | None"]
 
 
+def online_check(report):
+    """The explicit CLI/browser online check, without printing or prompting."""
+    from .build import load_team
+    from .keys import extra_settings, find_keys
+    team, _ = load_team(report.package.team.folder)
+    keys = find_keys(needed_keys(team), team.package_top, None)
+    return run_check(team, keys, LISTERS, extra_settings(), litellm_data, litellm_params), keys
+
+
 @dataclass
 class Problem:
     what: str  # the model or key
@@ -213,8 +222,12 @@ def _probe(model: str, keys: Keys, listers: dict[str, Lister], settings: dict, l
     available = lists[provider]
     if isinstance(available, Exception):
         e = available
+        reason = str(e)
+        for secret in keys.values.values():
+            if secret:
+                reason = reason.replace(secret, "[key hidden]")
         return Probe(row, lambda who: Problem(
-            model, who, f"could not reach {provider} to check it: {e}",
+            model, who, f"could not reach {provider} to check it: {reason}",
             "check your connection" + (", and that Ollama is running" if provider in NO_KEY else
                                        f", and that {key_name} is right")),
             f"{provider} could not be reached")

{teamrunner-0.0.3 → teamrunner-0.0.4}/src/teamrunner/cli.py

@@ -52,13 +52,9 @@ def print_problems(report: Report, out: Style) -> None:
 def _online_check(report, out, quiet: bool):
     """validate --online (D100): the same key and model check as `run`, and no run.
     It never asks: a key found only in the shell is used for the check, not saved."""
-    from .build import load_team
-    from .checks import LISTERS, litellm_data, litellm_params, needed_keys, run_check
+    from .checks import online_check
     from .console import Console
-    from .keys import extra_settings, find_keys
-    team, _ = load_team(report.package.team.folder)
-    keys = find_keys(needed_keys(team), team.package_top, None)
-    check = run_check(team, keys, LISTERS, extra_settings(), litellm_data, litellm_params)
+    check, keys = online_check(report)
     if not quiet:
         Console(False, sys.stdout).check(check, keys)
     return check
@@ -356,6 +352,11 @@ def cmd_skill(args) -> int:
     return 1 if failed else 0
 
 
+def cmd_ui(args) -> int:
+    from .ui.server import serve
+    return serve(Path(args.folder))
+
+
 def main(argv=None) -> int:
     for stream in (sys.stdout, sys.stderr):  # Windows sends piped output in its old code page, without ✓ or ≈
         if hasattr(stream, "reconfigure") and (stream.encoding or "").lower().replace("-", "") != "utf8":
@@ -365,6 +366,10 @@ def main(argv=None) -> int:
     parser.add_argument("--version", action="version", version=f"teamrunner {__version__}")
     commands = parser.add_subparsers(dest="command", required=True)
 
+    ui = commands.add_parser("ui", aliases=["gui"], help="open this folder in the local browser interface")
+    ui.add_argument("folder", nargs="?", default=".", help="the folder to open (default: this folder)")
+    ui.set_defaults(func=cmd_ui)
+
     v = commands.add_parser("validate", help="check a team's files before running it")
     v.add_argument("team", nargs="?", default=".", help="the team folder (default: this folder)")
     v.add_argument("-v", "--verbose", action="store_true",

{teamrunner-0.0.3 → teamrunner-0.0.4}/src/teamrunner/console.py

@@ -164,7 +164,7 @@ class Console:
         request = " ".join(str(first).split())
         request = request if len(request) <= 50 else request[:49] + "…"
         verb = {"web_search_brave": "search", "read_page": "read", "read_file": "read",
-                "run_code": "run"}.get(e["tool"], e["tool"])
+                "run_code": "run", "read_email": "read", "save_draft": "draft"}.get(e["tool"], e["tool"])
         if e["access"] == "allowed" and e.get("result") is not None:
             allowance = e.get("allowance") or {}
             mark = p.green(f"✓ {allowance.get('used')} of {allowance.get('of')}")