diff --git a/.agent/DEFERRED_VERIFICATION.md b/.agent/DEFERRED_VERIFICATION.md index 0f63228..6b3b177 100644 --- a/.agent/DEFERRED_VERIFICATION.md +++ b/.agent/DEFERRED_VERIFICATION.md @@ -14,7 +14,6 @@ is named in the commit that closes it. | 1663afd, a327458 | MCP `emit` refuses what `validate` would refuse and takes `inbox_read`; `inbox` marks a reply to an earlier asking `stale`; driven over stdio by tests, not by an agent session | An agent may misread a refusal or ignore `stale` | One agent session using the MCP tools: a refused event, an `inbox_read` through `emit`, a stale reply seen | | 45bc2ef | A round that is started again is allowed and counted on; tested, not seen from a real loop | A real restart shows a wrong round or a problem | A real loop restarting a round, shown on the board and passing `validate` | | 5c6efbf, 5672f1a | The board's state lives in the user's state folder, and each repository and loop is a boundary. Seen on a running board on 2026-11-19: a watched folder whose `.loops` cannot be entered is named with the reason, a line dated 9999 and a `loop.json` that cannot be read leave every other loop shown, and Stop for another loop goes through beside the broken one. Not seen: a board started inside a watched repository that holds a planted state folder | The board reads state a repository planted | A board started inside a watched repository with a planted state folder, which it must leave unread | -| 5672f1a | A fault answers with the board's page (500); tested through the app. The 422 page was opened in Chrome on a running board (2026-11-18) | The page may not render in a real browser | The 500 page opened on a running board | | c07643a | The overview's pulse turns an open page to stalled when a loop goes quiet; tested through the app | An open overview keeps showing running | An overview left open past 45 minutes of silence turns to stalled | | cbe60a1 | A worktree counts only when its repository lists it back; tested with planted `.git` files | A real worktree is split from its repository, or a claim still passes | A real worktree and a folder with a `.git` file naming another repository, both on a running board | | df0e651 | The browser is let in by the printed address (cookie `SameSite=Strict`); shown with curl and Chrome, not in Safari or Firefox | Another browser refuses the cookie on the redirect and shows the locked page | The printed address opened in Safari and Firefox, a loop page reached | @@ -24,3 +23,5 @@ is named in the commit that closes it. | the key per loop | Seen on a running board over the example loop on 2026-11-19: Stop wrote a line with `loop_sig` and `sig`, the key files had mode 0600 in a 0700 folder, and the example's own helper read the line as signed True. Not seen: a machine that already has an `inbox.key` and inboxes full of lines with `sig` only, and a loop with a helper pasted from the earlier text | After the upgrade earlier answers read as not from the board and a waiting question shows again, or a loop with the earlier helper stops taking a Stop | A board of the new version started on a machine with earlier loops: an earlier answer still reads as the board's (its mark is in the loop's `.earlier` list), and `loopcaptain doctor` passes on a loop with the earlier helper | | the page limits, the open questions, the turn of a sleeping page | Seen on a running board on 2026-11-19: a loop of 75 rounds drawn 30 at a time with links to the rest, two open questions shown one after the other, an open page of a sleeping loop turning to stalled by itself, the example loop started from the board, answered with a button and going on. Not seen: the notice beside Start that a Stop is waiting, the Copy buttons of an empty board, `watch` and `unwatch` on a config a person wrote by hand, a log near 20 MB from a real loop | A wording or a layout reads worse live than in a test; a real config has a shape the line editor does not know and is written anew | Each opened or run once on a real board and a real config | | hiding a loop, the old mark | Seen on a running board on 2026-11-19: `hide` took a waiting loop off an open first page, which reloaded by itself, out of the waiting count and the figures, the `hidden` chip listed it, its page opened with the command that shows it again, `unhide` brought it back; a loop silent for 20 days showed as stalled, marked old, outside the count of loops that need a look. Not seen: a loop hidden from one worktree and read from another, and `hide` on a config a person wrote by hand | A hidden loop comes back when its repository is read from another worktree | A loop hidden in the main checkout stays hidden while a worktree of that repository writes last | +| the waiting count in a background tab | Seen in Chrome on a running board on 2026-11-19, with the tab made to read as hidden and the notification replaced by a recorder: a second loop asked, the title went from (1) to (2) without the page being drawn again, and one notification was made. Not seen: the browser's own permission prompt answered by a person and the notification the system then shows; `status` and `inbox` were run against a real board's loops | The system shows nothing, or shows it for every poll | Notify allowed in the footer, the board's tab put behind another, a loop made to ask: one notification, and a click on it brings the tab forward | +| the site's head and the release notes | The built site carries a title, a sentence, a card picture and, on the first page, the project as data; no page loads a font from another host; a release note prints its commit's bullets. Checked on the built pages and by tests, not on the published site or a real release | A card that does not show when a link is shared; notes that read badly for a squash merge, whose body is the pull request's list of commits | A link to the published site pasted into a chat or a card checker shows the picture; the notes of the next release read well | diff --git a/.agent/FINDINGS.md b/.agent/FINDINGS.md index 04cb8fc..4e396f8 100644 --- a/.agent/FINDINGS.md +++ b/.agent/FINDINGS.md @@ -13,7 +13,6 @@ in the commit that settles it. Proposed: now, later, check, drop. | F15 | An optional exporter that tails `events.jsonl` and sends OTLP along docs/opentelemetry.md: its own process and dependency group, off by default, the first thing that would send data off the machine | open | later: when someone wants loops beside agent traces | docs/ARCHITECTURE.md section 15 | | F17 | The tab title counts what waits; the favicon does not. A count in the icon needs a drawn image per number or script | open | later | src/loopcaptain/board/templates/overview.html | | F18 | A prompt to build a loop, given to a fresh agent, ended with a 302-line loop file for a three-step job; a smaller starting template (one loop.py of 60 lines beside the helper) would make the first loop cheaper | open | later: check with the next acceptance run | the acceptance run of 2026-11-15 | -| F19 | "Door" is used for the two ways a loop writes its files (the MCP server's docstring and so `docs/reference/mcp.md`, `mcp_server/AGENTS.md`, `standard/LOOPS.md` section 5). A reader new to the project does not know what a door is; the architecture heading and picture now say "ways in" and name the script and MCP | open | later: reword with the next change to those files, then `make docs-pages` | `git grep -n -i door`, 2026-11-15 | | F20 | SECURITY.md and the issue template send reporters to private security advisories, but private vulnerability reporting is switched off on the repository, so a reporter has no private way in | open | now: a repository setting, no file change | the repository's `private-vulnerability-reporting` setting read `enabled: false`; SECURITY.md:29-31, .github/ISSUE_TEMPLATE/config.yml | | F26 | The release workflow tags and publishes on a push to main without waiting for CI: 0.3.1 was published 29 seconds after the CI run for the same commit was created | open | now: trigger on a successful CI run, or make the release job need a `make check` job | .github/workflows/release.yml:11-14, :55-66; run and upload times of 2026-11-15 | | F34 | `a helper of 50 lines` is stale in CHANGELOG.md; the helper has 76 | open | later: the file is frozen at 0.1.0, so only if that entry is ever rewritten | CHANGELOG.md; `wc -l standard/loops.py` | @@ -26,12 +25,9 @@ in the commit that settles it. Proposed: now, later, check, drop. | F72 | PyPI holds no provenance attestations for the published files | open | later | PyPI file metadata of 0.3.1; .github/workflows/release.yml | | F73 | `make setup` in a worktree repoints the main checkout's git hooks at the worktree's virtualenv | open | later: skip the install when the git dir is not the common dir, and say so in AGENTS.md section B.1 | Makefile:7-12; the installed hook's `INSTALL_PYTHON` line | | F74 | The repository topics miss the terms people search by (agent loops, human in the loop, dashboard); one topic is shared by six repositories. Topics naming agent products would need a reading of rule 8 | open | check: add `human-in-the-loop`, `agent-monitoring`, `ai-agents`, `coding-agents`, `ralph-loop`, `local-first`, and one of `claude-code` or `agent-protocol`; a repository setting, no file change | repository topics read 2026-11-15 and 2026-11-19 | -| F75 | A shared link shows the code host's generic card, and the docs site has no card image | open | later | repository settings, zensical.toml; review of 2026-11-15 at 7e22640 | | F76 | `How it differs` names no alternative, so a reader cannot place the project against tools they know. Naming other projects bends rule 8 | open | check: a rule change, and a section in docs/ARCHITECTURE.md | README.md `How it differs`; AGENTS.md rule 8 | -| F77 | A release note is one commit subject, and CHANGELOG.md 0.1.0 contradicts itself and the product in places | open | later: bullets from the commit body into the release note | CHANGELOG.md, scripts/release.py; the notes of 0.3.1 | -| F78 | The generated command-line reference has eleven empty descriptions, lower-cases proper names, and does not say that `emit` values parse as JSON | open | later | docs/reference/cli.md, src/loopcaptain/cli.py help texts | +| F77 | CHANGELOG.md 0.1.0 contradicts itself and the product in places (a helper of 50 lines, among others) | open | later: only if that entry is ever rewritten; the file is frozen at the first version | CHANGELOG.md | | F80 | The standard a loop author pastes does not say what only `validate` checks beyond the JSON Schema (paths, rules across lines); a loop and a board that look at different key folders make every answer read as not from the person, with no sign on the board | open | later | standard/LOOPS.md, standard/schema/, docs/setup.md section 5; review of 2026-11-15 at 7e22640 | -| F81 | The docs site loads its fonts from a third-party host, while the board vendors its font | open | check: vendor the font in the site too | zensical.toml; requests of the built site, review of 2026-11-15 at 7e22640 | | F83 | Small stale or author-facing statements across the standard, the site and the nested AGENTS.md files | open | later: with the next change to each file; done on 2026-11-16 for README.md, docs/index.md, docs/get-started.md, docs/installation.md, docs/agents.md and the one line in standard/AGENTS.md | git grep of the review | | F84 | Protocol proposal held back by rule 3: the helper's `inbox()` could drop entries whose `signed` is not `true`, or that are `stale`, by default or behind an opt-in argument; today a loop filters them itself, and a call written against the earlier text must keep returning what it returned | open | later: an opt-in argument fits version 1, a new default is protocol 2 | standard/loops.py `inbox`; docs/ARCHITECTURE.md section 26, Rejected; commit a327458 | | F89 | One loop page walks the watched folders several times per request: `find_loop`, `find_repo` and the repository list each call `find_repos(config())`. Measured on 300 folders, 100 of them with loops: 13 ms a walk, so about 50 ms of a page | open | later: one walk per request, if a board with hundreds of folders feels slow | src/loopcaptain/board/discover.py, board/app.py; measured 2026-11-19 | @@ -46,4 +42,3 @@ in the commit that settles it. Proposed: now, later, check, drop. | F112 | The block-list of key and credential names holds broad patterns (`secrets*`, `*.env`), so ordinary files with such names are refused too | open | check: keep them, or narrow them | src/loopcaptain/board/files.py:61-98 | | F113 | The weekly link check reads the Markdown files only, not the built docs site; about six lines in the workflow would add it | open | check: add it, or skip | .github/workflows/links.yml | | F114 | Discussions are off and the wiki is on with no page, so a question has no place but an issue | open | now: Discussions (Q&A) on, wiki off; a repository setting, no file change | repository settings read 2026-11-19 | -| F115 | The README gives a Ralph loop one line (`emit` once per iteration); no page walks through a worked shell loop that reports to the board | open | later: a "Monitor a Ralph loop" page | README.md:134 | diff --git a/AGENTS.md b/AGENTS.md index c82faee..ce6413f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -87,7 +87,8 @@ Work in the loop's repository, not here, and follow [standard/AGENTS.md](standard/AGENTS.md); propose the smallest change and wait for a yes. Do not add this repository as a dependency of a loop. A loop an agent session drives adds the MCP server, `loopcaptain mcp` over -stdio: `loopcaptain mcp-config ` prints the line for it, +stdio, installed with its extra (`uv tool install 'loopcaptain[mcp]'`): +`loopcaptain mcp-config ` prints the line for it, [docs/agents.md](docs/agents.md) lists every agent. ### What the board does and does not do @@ -142,13 +143,14 @@ stdio: `loopcaptain mcp-config ` prints the line for it, it the major one. A push with only `docs`, `test`, `chore`, `ci` or `refactor` commits makes no release. 3. A release is a tag `vX.Y.Z` and a GitHub release whose notes are the - subjects of those commits, with the wheel attached: built with the + subjects of those commits, each with the bullets of its body below + it, with the wheel attached: built with the tag's version, installed in a clean environment and smoke-tested first. It goes to PyPI once the repository variable `PUBLISH_PYPI` is `true`. 4. Nothing is committed back. `pyproject.toml` says `0.0.0`; a checkout and an install from `main` report that, a released wheel its tag. -5. A commit subject is a line of the release notes, so write it for a - user. `CHANGELOG.md` holds the first version and points to the +5. A commit subject is a line of the release notes and its bullets are + printed below it, so write both for a user. `CHANGELOG.md` holds the first version and points to the releases. 6. The package version is not the protocol number: a release may add optional fields and events, never break a loop written today. diff --git a/README.md b/README.md index 2c045eb..a26a734 100644 --- a/README.md +++ b/README.md @@ -132,7 +132,9 @@ fault and the loop asks you what to do: [standard/LOOPS.md](standard/LOOPS.md) and call it where a round and a step begin and end, or append the JSON lines yourself. 2. **A Ralph loop or any loop around an agent's command line:** the shell - form, `loopcaptain emit key=value`, once per iteration. + form, `loopcaptain emit key=value` once per iteration and + `loopcaptain inbox ` for your stop and notes; a worked `loop.sh` is + in [docs/shell-loop.md](docs/shell-loop.md). 3. **A long-running agent session:** add the MCP server (`loopcaptain mcp-config `), and the session reports its rounds through five tools. @@ -150,6 +152,9 @@ loopcaptain validate # check a repository's .loops folders loopcaptain doctor # does the loop take a stop? loopcaptain mcp-config # how your agent adds the MCP server loopcaptain emit key=value # one event from a shell loop +loopcaptain inbox # what you sent it, for a shell loop to read +loopcaptain status # where every loop stands, in the terminal +loopcaptain hide # one loop off the first page ``` From a checkout, put `uv run` in front, or use the `make` targets in diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 91c1e33..e2e1c2e 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -557,8 +557,8 @@ would still vanish. the line's `event` (`event_tag`); a name not in `EVENT_NAMES` reads as `OtherEvent`, which the fold skips and which still counts as a sign of life. `validate` warns (`unknown_events`). The published schema takes any -other event name with a `ts`. Writing stays strict: both `emit` doors -take known events only. +other event name with a `ts`. Writing stays strict: `emit` on the command +line and `emit` over MCP take known events only. **Why.** Version 1 grows by new events, and the standard tells a board to ignore what it does not know. A reader that refused them would call the @@ -594,13 +594,13 @@ only grows). Raising an error without a key: a loop on a machine where no board has run yet would not start. A new event for the case: boards installed before unknown events were skipped would call it a problem. -## 27. A door refuses an event that would stay a problem, and no more +## 27. A way in refuses an event that would stay a problem, and no more **Decision.** `before_writing` in `protocol/validate.py` holds what the -two doors that write on a loop's behalf check, the MCP `emit` and +two ways in that write on a loop's behalf check, the MCP `emit` and `loopcaptain emit`. `refusals` (the round has started, the step is in `loop.json`, the artifact exists, the verdict agrees with the round's -first) refuses an event: the door writes nothing. An `inbox_read` naming +first) refuses an event: nothing is written. An `inbox_read` naming an entry the models cannot read is written with a warning; where `loop.json` or the log cannot be read (over the size the reader takes, unreadable), the event is written without the checks against the log, @@ -608,7 +608,7 @@ with a warning. The MCP `emit` adds the warning to its answer, `loopcaptain emit` writes it to standard error. Both take `inbox_read`. **Why.** The log is append-only, so a line `validate` refuses is refused -for good; a writer that hears `recorded` never learns it. A door that +for good; a writer that hears `recorded` never learns it. A way in that refuses more than `validate` calls a problem stops a loop for nothing. The standard has a loop append `inbox_read` after acting on entries, and a loop that reads the inbox file itself has no other way to mark them; @@ -619,7 +619,7 @@ loop still has to report. **Rejected.** Writing the line and returning the problems with it: the problem is then permanent, and the caller can only add to it. Refusing -`inbox_read` on both doors: a shell loop would have to write the line by +`inbox_read` on both ways in: a shell loop would have to write the line by hand, without any check of its ids. Refusing an unreadable entry or an unreadable log: the loop could not report at all. Writing such a line silently: the writer would not know its line went unchecked. diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index f6ac1ae..e60653d 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -10,7 +10,3 @@ picked are in the ledgers in `.agent/`. | # | Item | From | Picked | |---|---|---|---| -| 1 | `loopcaptain status`: where every watched loop stands, in a terminal. `load_all` in `board/discover.py` already returns what it would print; nothing in the protocol changes | F64 | 2026-11-19 | -| 2 | `loopcaptain inbox `: read a loop's inbox from a shell, and one worked shell loop in the docs, so the shell route the README promises is whole | F49 | 2026-11-19 | -| 3 | Tell the person a loop waits while the board's tab is in the background: a count in the tab's title and a browser notification, on 127.0.0.1 only, nothing loaded from another origin | F65 | 2026-11-19 | -| 4 | The MCP SDK becomes an extra, `loopcaptain[mcp]`: a plain install pulls in about half as much, `loopcaptain mcp` without the extra says what to install, and the install line for agent sessions in the docs names the extra | F70 | 2026-11-19 | diff --git a/docs/agents.md b/docs/agents.md index f0e864b..6249f5e 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -5,7 +5,8 @@ description: "Use Loopcaptain from Claude Code, Codex, Gemini CLI, Cursor, VS Co # Works with every agent The protocol names no vendor: a loop writes its files, whatever runs it. Around it, each -agent adds the MCP server its own way. The server is `loopcaptain mcp`, over stdio. +agent adds the MCP server its own way. The server is `loopcaptain mcp`, over stdio. It needs +the MCP extra, which a plain install leaves out: `uv tool install 'loopcaptain[mcp]'`. The lines below are for the installed command. From a checkout of the repository the server is `uv run --project loopcaptain mcp`, and `loopcaptain mcp-config `, run diff --git a/docs/assets/social-card.png b/docs/assets/social-card.png new file mode 100644 index 0000000..d7e093c Binary files /dev/null and b/docs/assets/social-card.png differ diff --git a/docs/board.md b/docs/board.md index 200939e..4d7374b 100644 --- a/docs/board.md +++ b/docs/board.md @@ -1,4 +1,5 @@ --- +title: "The board: a local dashboard for agent loops" description: "The local dashboard: its pages, where to look first, how to answer, stop and start a loop, and what each status means." --- diff --git a/docs/connect.md b/docs/connect.md index eac72f6..73c7826 100644 --- a/docs/connect.md +++ b/docs/connect.md @@ -1,4 +1,5 @@ --- +title: "Connect or build an agent loop" description: "Connect an agent loop you already run, or build one that reports: through the pasted helper, the command line or the MCP server." --- diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..eaa79c7 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,89 @@ +--- +title: "Questions about monitoring and steering agent loops" +description: "Short answers: what an agent loop is, how to monitor and stop one, how a human stays in the loop, which agents work, and what leaves the machine." +--- + +# Questions and answers + +## What is an agent loop? + +A program that hands work to an AI agent again and again until a goal is +met or a limit is reached: a plan, the work, a review, a verdict, and then +the next round. A Ralph loop (a shell loop around one prompt), Claude +Code's `/loop`, a research script that calls a model every round and a +long-running agent session are all agent loops. + +## How do I monitor an agent loop that runs for hours? + +Let it write what happens into `.loops//events.jsonl` in its own +repository, one line per event, and open the board. The board shows every +loop on the machine: which round it is in, what each step found, what it +cost, and whether it still moves. A Python loop pastes a helper of under +110 lines, a shell loop calls `loopcaptain emit`, an agent session uses +the MCP server. [Connect or build a loop](connect.md) has the steps. + +## How do I stop or steer a running agent loop? + +Press Stop on the loop's page, answer its question with a button, or type +a note for the next round. The board appends a signed line to the loop's +`inbox.jsonl`; the loop reads it at the start of a round and acts on it. +The signature lets the loop tell your line from one an agent wrote into +the file. See [The board](board.md). + +## How do I keep a human in the loop without watching a chat window? + +A loop asks with a `question` event and either goes on with a default or +stands still until you answer. The board lists what waits for you, counts +it in the tab's title and can notify you through the browser. You answer +when you look, and the loop takes the answer at its next round. + +## How do I monitor a Ralph loop? + +Two commands in the shell loop: `loopcaptain emit` for each round and +step, `loopcaptain inbox` to read your stop and notes. A complete +`loop.sh` is on [Monitor a Ralph loop or any shell loop](shell-loop.md). + +## Which coding agents does it work with? + +Any. The protocol is plain files, so whatever can write a file can +report: Claude Code, Codex, Gemini CLI, Cursor, opencode, Amp, or a +script that calls a model's API. [Works with every agent](agents.md) +lists how each adds the MCP server. + +## Does a loop have to install or import Loopcaptain? + +No. A loop writes three small files; the helper is pasted text that uses +the Python standard library only. The board is installed once per +machine: `uv tool install loopcaptain`. + +## Does anything leave my machine? + +No. The board listens on `127.0.0.1` only, loads nothing from another +origin and sends nothing anywhere. It reads files in the repositories you +tell it to watch and writes only the inbox lines you send. The +[threat model](security.md) says what it reads, runs and writes. + +## How is this different from tracing and observability tools? + +Those record what a model call did, for later analysis, usually in a +hosted service. Loopcaptain shows where a loop stands now, round by +round, and carries your answer back into it; it runs on your laptop and +keeps its data in your repositories. The two fit together: a loop's +events map onto OpenTelemetry, see [OpenTelemetry](opentelemetry.md). + +## What does it cost? + +Nothing. Apache License 2.0, no account, no service. The example loop +that `loopcaptain demo` writes calls no model, so trying it is free too. + +## How do I see every loop without opening a browser? + +`loopcaptain status` prints one line per loop in the terminal: its +status, its round, its last line and what it asks. + +## How do I take a finished or dead loop off the board? + +`loopcaptain hide ` takes one loop off the first page +and out of the figures; `unhide` brings it back. Loops that ended are +folded away by themselves, and one that died weeks ago is marked old and +no longer counts as needing a look. diff --git a/docs/get-started.md b/docs/get-started.md index c74a5fc..e0cfb25 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -1,4 +1,5 @@ --- +title: "Get started: run an agent loop on the board in five minutes" description: "Run the free example loop on the board: no model, no network. Start it, answer its question with a button and watch it finish." --- diff --git a/docs/installation.md b/docs/installation.md index 25d3dfb..a7f13d2 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,4 +1,5 @@ --- +title: "Install Loopcaptain" description: "Install Loopcaptain from PyPI with uv, pipx or pip, run it once through uvx, or install a tagged release from the repository." --- @@ -50,6 +51,14 @@ loopcaptain --version To run it once without installing, `uvx loopcaptain demo` and `uvx loopcaptain serve` do the same from a temporary environment. +A loop that an agent session drives reports through the MCP server, +`loopcaptain mcp`. Its SDK is an extra, since the board, the pasted helper +and the command line need none of it: + +```bash +uv tool install 'loopcaptain[mcp]' # or: pipx install 'loopcaptain[mcp]' +``` + ## Install from the repository A release is also a tag in the repository. Name the tag, so the install diff --git a/docs/llms.txt b/docs/llms.txt index aa98c6c..6b24a36 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -19,6 +19,8 @@ - [LOOPS.md](https://github.com/faviens/loopcaptain/blob/main/standard/LOOPS.md): the protocol, the helper to paste, conformance - [AGENTS.md for a loop](https://github.com/faviens/loopcaptain/blob/main/standard/AGENTS.md): connect a loop, or build one from nothing - [Works with every agent](https://faviens.github.io/loopcaptain/agents/): how each coding agent adds the MCP server +- [Monitor a Ralph or shell loop](https://faviens.github.io/loopcaptain/shell-loop/): a worked loop.sh with `emit` and `inbox` +- [Questions and answers](https://faviens.github.io/loopcaptain/faq/): what a loop is, how to monitor, stop and steer one ## Optional diff --git a/docs/opentelemetry.md b/docs/opentelemetry.md index 9407e38..b2a9d22 100644 --- a/docs/opentelemetry.md +++ b/docs/opentelemetry.md @@ -1,4 +1,5 @@ --- +title: "Agent loops and OpenTelemetry" description: "How a loop's events map onto OpenTelemetry and the GenAI conventions, for loops beside agent traces. Loopcaptain sends no telemetry." --- diff --git a/docs/protocol/index.md b/docs/protocol/index.md index 58c4e27..6d68c0c 100644 --- a/docs/protocol/index.md +++ b/docs/protocol/index.md @@ -1,4 +1,5 @@ --- +title: "The Loops protocol: the files an agent loop writes" description: "The Loops protocol, version 1: the files an agent loop writes and reads, every field and event, and the helper a loop pastes." --- diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 2f2bd2f..fd17303 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -26,30 +26,27 @@ loopcaptain validate [-h] [--strict] repo | Argument | Meaning | |---|---| -| `repo` | | +| `repo` | the repository whose .loops folders are checked | | `--strict` | count warnings as problems | ## `emit` -Append one event: loopcaptain emit key=value .... +Append one event to a loop's log, its fields as key=value pairs, for a loop in shell. ```text -loopcaptain emit [-h] [--repo REPO] - loop - {round_started,step_started,step_finished,finding_closed,round_finished,question,question_closed,check,inbox_read,loop_started,loop_stopped,heartbeat} - [fields ...] +loopcaptain emit [-h] [--repo REPO] loop event [fields ...] ``` | Argument | Meaning | |---|---| -| `loop` | | -| `event` | | +| `loop` | the loop's id, the name of its folder in .loops/ | +| `event` | the event to append, one of: round_started, step_started, step_finished, finding_closed, round_finished, question, question_closed, check, inbox_read, loop_started, loop_stopped, heartbeat | | `fields` | key=value; a value is read as JSON where it parses (round=2, blocks=true, ids='["a"]'), and as text where the field is text (commit=1234567) | -| `--repo` | | +| `--repo` | the repository the loop lives in, default: this folder | ## `schema` -Write the protocol as json schema. +Write the protocol as JSON Schema. ```text loopcaptain schema [-h] target @@ -57,7 +54,7 @@ loopcaptain schema [-h] target | Argument | Meaning | |---|---| -| `target` | | +| `target` | the folder the schema files are written into | ## `doctor` @@ -69,8 +66,8 @@ loopcaptain doctor [-h] [--timeout TIMEOUT] repo loop | Argument | Meaning | |---|---| -| `repo` | | -| `loop` | | +| `repo` | the repository the loop lives in | +| `loop` | the loop's id, the name of its folder in .loops/ | | `--timeout` | seconds to wait, default 600 | ## `watch` @@ -83,7 +80,7 @@ loopcaptain watch [-h] [--root] path | Argument | Meaning | |---|---| -| `path` | | +| `path` | a repository, or with --root a folder of repositories | | `--root` | every sub-folder with .loops/ is a repository | ## `unwatch` @@ -96,7 +93,33 @@ loopcaptain unwatch [-h] path | Argument | Meaning | |---|---| -| `path` | | +| `path` | the folder to take off, however the config spells it | + +## `status` + +Where every watched loop stands, in a terminal. + +```text +loopcaptain status [-h] [--all] +``` + +| Argument | Meaning | +|---|---| +| `--all` | hidden and finished loops too | + +## `inbox` + +What the person sent a loop since the last call, one line each, for a loop in shell. + +```text +loopcaptain inbox [-h] [--repo REPO] [--json] loop +``` + +| Argument | Meaning | +|---|---| +| `loop` | the loop's id, the name of its folder in .loops/ | +| `--repo` | the repository the loop lives in, default: this folder | +| `--json` | every entry as a JSON line, with signed and stale | ## `hide` @@ -108,8 +131,8 @@ loopcaptain hide [-h] repo loop | Argument | Meaning | |---|---| -| `repo` | | -| `loop` | | +| `repo` | the repository the loop lives in | +| `loop` | the loop's id, the name of its folder in .loops/ | ## `unhide` @@ -121,8 +144,8 @@ loopcaptain unhide [-h] repo loop | Argument | Meaning | |---|---| -| `repo` | | -| `loop` | | +| `repo` | the repository the loop lives in | +| `loop` | the loop's id, the name of its folder in .loops/ | ## `demo` @@ -134,12 +157,12 @@ loopcaptain demo [-h] [--target TARGET] [--no-watch] | Argument | Meaning | |---|---| -| `--target` | | +| `--target` | the folder the example loop is written into, default ~/.local/share/loopcaptain/demo | | `--no-watch` | write it, but leave the config alone | ## `mcp-config` -How one coding agent adds the mcp server. +How one coding agent adds the MCP server. ```text loopcaptain mcp-config [-h] [--checkout CHECKOUT] [--markdown] [agent] @@ -153,7 +176,7 @@ loopcaptain mcp-config [-h] [--checkout CHECKOUT] [--markdown] [agent] ## `spec` -Print loops.md, the protocol to paste into a loop. +Print LOOPS.md, the protocol to paste into a loop. ```text loopcaptain spec [-h] @@ -161,7 +184,7 @@ loopcaptain spec [-h] ## `mcp` -Run the mcp server on stdio. +Run the MCP server on stdio. ```text loopcaptain mcp [-h] diff --git a/docs/reference/mcp.md b/docs/reference/mcp.md index f7611cd..94d27d6 100644 --- a/docs/reference/mcp.md +++ b/docs/reference/mcp.md @@ -2,13 +2,14 @@ # The MCP tools -The MCP door: the protocol as five tools, for a loop that an agent session drives. +The MCP server: the protocol as five tools, for a loop that an agent session drives. The tools mirror the helper a script pastes (`register`, `emit`, `inbox`), so there is one -vocabulary on both doors and the tool list stays small in the agent's context. Every tool writes -the same files; the board cannot tell the two doors apart. `repo` is the repository the loop -lives in; left out, it is the folder the server was started in, which is the agent's working folder. -A `repo` outside that folder is refused unless `LOOPCAPTAIN_MCP_ROOTS` names a folder above it. +vocabulary for a script and for a session, and the tool list stays small in the agent's context. +Every tool writes the same files the helper writes; the board cannot tell which of the two wrote +a line. `repo` is the repository the loop lives in; left out, it is the folder the server was +started in, which is the agent's working folder. A `repo` outside that folder is refused unless +`LOOPCAPTAIN_MCP_ROOTS` names a folder above it. ## `protocol` diff --git a/docs/security.md b/docs/security.md index 15d6cc9..2a4173d 100644 --- a/docs/security.md +++ b/docs/security.md @@ -1,4 +1,5 @@ --- +title: "Security and threat model of the local board" description: "What the board reads, runs and writes: how a browser gets in, how an answer reaches a loop signed, and what Start may run." --- diff --git a/docs/setup.md b/docs/setup.md index 12aede8..f2c28b3 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,4 +1,5 @@ --- +title: "Set up the board for your agent loops" description: "Put the repositories that run agent loops on the board, find the loops that already report, and connect the ones that do not." --- diff --git a/docs/shell-loop.md b/docs/shell-loop.md new file mode 100644 index 0000000..48661c9 --- /dev/null +++ b/docs/shell-loop.md @@ -0,0 +1,127 @@ +--- +title: "Monitor and steer a Ralph loop or any shell loop" +description: "Monitor and steer a Ralph loop or any shell loop around a coding agent: report each iteration with one command, read the person's stop and notes with another." +--- + +# Monitor a Ralph loop or any shell loop + +A Ralph loop is a shell loop that hands the same prompt to a coding agent +again and again until a check passes. It needs no Python and no helper to +show up on the board: two commands do it. + +1. `loopcaptain emit key=value ...` appends one event. +2. `loopcaptain inbox ` prints what you sent from the board since + the last call, one line each, and marks it read. + +`loopcaptain status` then says in a terminal where every watched loop +stands, and the board shows the same with its rounds, its cost and a Stop +button. + +## The loop + +Save this as `loop.sh` in the repository the loop works in. Set +`AGENT_CMD` to your agent's command line, one that reads a prompt on +standard input and prints its answer, and `CHECK_CMD` to the command that +says whether the work is done. + +```bash +#!/usr/bin/env bash +# loop.sh: hand PROMPT.md to an agent until the check passes, and report every round. +set -euo pipefail + +LOOP=ralph +AGENT_CMD=${AGENT_CMD:?set AGENT_CMD to your agent command, reading the prompt on standard input} +CHECK_CMD=${CHECK_CMD:-make test} +MAX_ROUNDS=${MAX_ROUNDS:-20} + +mkdir -p ".loops/$LOOP" out +cat > ".loops/$LOOP/loop.json" </dev/null || true) +round=${round:-0} + +while true; do + # What the person sent since the last round: only lines the board signed are printed. + sent=$(loopcaptain inbox "$LOOP") + if grep -q '^stop' <<<"$sent"; then + loopcaptain emit "$LOOP" loop_stopped stop_reason=person summary="Stopped from the board." + exit 0 + fi + notes=$(grep '^reply' <<<"$sent" | cut -f2- || true) + if [ "$round" -ge "$MAX_ROUNDS" ]; then + loopcaptain emit "$LOOP" loop_stopped stop_reason=round_cap summary="Stopped at $MAX_ROUNDS rounds." + exit 0 + fi + + round=$((round + 1)) + loopcaptain emit "$LOOP" round_started round="$round" + + loopcaptain emit "$LOOP" step_started round="$round" step=agent + { + cat PROMPT.md + if [ -n "$notes" ]; then printf '\nFrom the person:\n%s\n' "$notes"; fi + } | bash -c "$AGENT_CMD" > "out/round-$round.md" + loopcaptain emit "$LOOP" step_finished round="$round" step=agent artifact="out/round-$round.md" + + if bash -c "$CHECK_CMD" > "out/check-$round.log" 2>&1; then + loopcaptain emit "$LOOP" step_finished round="$round" step=check passed=true + loopcaptain emit "$LOOP" round_finished round="$round" verdict=done stop_reason=goal_met \ + summary="The check passes." + exit 0 + fi + loopcaptain emit "$LOOP" step_finished round="$round" step=check passed=false \ + artifact="out/check-$round.log" + loopcaptain emit "$LOOP" round_finished round="$round" verdict=continue \ + summary="The check still fails." +done +``` + +## Run it and watch it + +```bash +AGENT_CMD='your-agent --print' bash loop.sh # from the repository +loopcaptain watch . # once: put the repository on the board +loopcaptain status # where it stands, in a terminal +loopcaptain serve # the board; open the address it prints +``` + +On the board the loop shows each round with its two steps, the agent's +output and the check's log as files to open, and a Stop button. Stop is +taken before the next round starts. A note typed on the loop's page is +handed to the agent with the next prompt, under "From the person". + +## What the two commands print + +```console +$ loopcaptain inbox ralph +reply Leave the migration alone, fix the tests first. +stop +$ loopcaptain inbox ralph --json +{"id": "...", "kind": "stop", "signed": true, "stale": false, ...} +``` + +Without `--json`, `inbox` prints only what a loop may act on: lines the +board signed for this loop that answer the present asking, as the kind, a +tab and the text on one line. Anything else in the file (a line an agent +wrote, a reply to a question asked earlier) is counted on standard error +and left out, so a script that reads the lines cannot take a forged stop +by mistake. `--json` prints every entry with `signed` and `stale`. + +A value in `emit` is read as JSON where it parses (`round=2`, +`passed=true`) and as text where the field is text. `loopcaptain validate +.` checks what the loop wrote, and `loopcaptain doctor . ralph` sends a +stop and tells you whether the loop took it. diff --git a/overrides/main.html b/overrides/main.html new file mode 100644 index 0000000..bffaadc --- /dev/null +++ b/overrides/main.html @@ -0,0 +1,42 @@ +{#- What a shared link and a search result show: a title, a sentence and a picture for every page, + and on the first page what the project is, as data a search engine reads. Nothing is loaded + from another origin. -#} +{% extends "base.html" %} + +{% block extrahead %} + {% set named = page and page.meta and page.meta.title is defined and page.meta.title %} + {% set title = page.meta.title if named else (page.title if page and page.title else config.site_name) %} + {% set home = page and page.canonical_url is defined and page.canonical_url == config.site_url %} + {% set shown = title if title == config.site_name else title ~ " - " ~ config.site_name %} + {% set described = page and page.meta and page.meta.description is defined and page.meta.description %} + {% set description = page.meta.description if described else config.site_description %} + {% set card = config.site_url ~ "assets/social-card.png" %} + + + + + + + + + + + + + {% if home %} + + {% endif %} +{% endblock %} diff --git a/pyproject.toml b/pyproject.toml index 198d78e..bfdddcc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,13 +31,17 @@ dependencies = [ "fastapi>=0.115", "jinja2>=3.1", "markdown-it-py>=3.0", - "mcp>=2.0", "pydantic>=2.7", "python-multipart>=0.0.9", "pyyaml>=6.0", "uvicorn>=0.30", ] +# The MCP server, for a loop an agent session drives: `uv tool install 'loopcaptain[mcp]'`. The board, +# the helper and the command line need none of it, and the SDK was about half of a plain install. +[project.optional-dependencies] +mcp = ["mcp>=2.0"] + [project.urls] Documentation = "https://faviens.github.io/loopcaptain/" Repository = "https://github.com/faviens/loopcaptain" @@ -50,6 +54,7 @@ loopcaptain = "loopcaptain.cli:main" [dependency-groups] dev = [ "httpx>=0.27", + "mcp>=2.0", "mypy>=1.11", "pre-commit>=4.0", "pytest>=8", diff --git a/scripts/docs_pages.py b/scripts/docs_pages.py index 735c270..1d6ae6c 100644 --- a/scripts/docs_pages.py +++ b/scripts/docs_pages.py @@ -36,7 +36,9 @@ def cli_page() -> str: subparsers = next(a for a in parser._actions if isinstance(a, argparse._SubParsersAction)) helps = {choice.dest: choice.help for choice in subparsers._choices_actions} for name, sub in subparsers.choices.items(): - lines += [f"## `{name}`", "", f"{(helps.get(name) or '').capitalize()}.", ""] + about = (helps.get(name) or "").rstrip(".") + # The first letter only: `capitalize` would write "Mcp" and "Loops.md". + lines += [f"## `{name}`", "", f"{about[:1].upper()}{about[1:]}.", ""] usage = sub.format_usage().replace("usage: ", "").strip() lines += ["```text", usage, "```", ""] options = [action for action in sub._actions if not isinstance(action, argparse._HelpAction)] @@ -96,6 +98,8 @@ def llms_txt() -> str: f"- [LOOPS.md]({files}/standard/LOOPS.md): the protocol, the helper to paste, conformance", f"- [AGENTS.md for a loop]({files}/standard/AGENTS.md): connect a loop, or build one from nothing", f"- [Works with every agent]({site}/agents/): how each coding agent adds the MCP server", + f"- [Monitor a Ralph or shell loop]({site}/shell-loop/): a worked loop.sh with `emit` and `inbox`", + f"- [Questions and answers]({site}/faq/): what a loop is, how to monitor, stop and steer one", "", "## Optional", "", diff --git a/scripts/release.py b/scripts/release.py index b88fe07..21a9627 100644 --- a/scripts/release.py +++ b/scripts/release.py @@ -62,14 +62,38 @@ def next_tag(last: str | None, bump: str) -> str: return f"v{major}.{minor}.{patch + 1}" +#: A commit says why in bullets; a release note carries at most this many of them per commit. +MOST_BULLETS = 6 + + +def bullets(body: str) -> list[str]: + """The top-level bullets of a commit body, each on one line: what a release note adds below a + subject. Check boxes of a pull request's text and everything that is no bullet are left out.""" + found: list[str] = [] + open_bullet = False + for line in body.splitlines(): + if line.startswith("- ") and not line.startswith("- ["): + found.append(line[2:].strip()) + open_bullet = True + elif open_bullet and line.startswith(" ") and line.strip(): + found[-1] = f"{found[-1]} {line.strip()}" + else: + open_bullet = False + return found[:MOST_BULLETS] + + def notes(commits: list[Commit]) -> str: - """The release notes: each feat, fix and perf subject under its heading, newest first.""" + """The release notes: each feat, fix and perf subject under its heading, newest first, with the + reasons its commit gives below it.""" sections: dict[str, list[str]] = {kind: [] for kind in HEADINGS} for commit in commits: match = SUBJECT.match(commit.subject) if match and match["type"] in sections: scope = f"**{match['scope']}**: " if match["scope"] else "" - sections[match["type"]].append(f"- {scope}{match['text']} ({commit.sha[:7]})") + entry = [f"- {scope}{match['text']} ({commit.sha[:7]})"] + sections[match["type"]].append( + "\n".join(entry + [f" - {text}" for text in bullets(commit.body)]) + ) return "\n\n".join( f"## {HEADINGS[kind]}\n\n" + "\n".join(lines) for kind, lines in sections.items() if lines ) diff --git a/src/loopcaptain/agents.py b/src/loopcaptain/agents.py index 37fb4b2..125a9a7 100644 --- a/src/loopcaptain/agents.py +++ b/src/loopcaptain/agents.py @@ -138,7 +138,8 @@ def markdown(checkout: str = "") -> str: "# Works with every agent", "", "The protocol names no vendor: a loop writes its files, whatever runs it. Around it, each", - "agent adds the MCP server its own way. The server is `loopcaptain mcp`, over stdio.", + "agent adds the MCP server its own way. The server is `loopcaptain mcp`, over stdio. It needs", + "the MCP extra, which a plain install leaves out: `uv tool install 'loopcaptain[mcp]'`.", "", "The lines below are for the installed command. From a checkout of the repository the server", f"is `{' '.join(server_argv(''))}`, and `loopcaptain mcp-config `, run", diff --git a/src/loopcaptain/board/app.py b/src/loopcaptain/board/app.py index 9a552d3..fff64d7 100644 --- a/src/loopcaptain/board/app.py +++ b/src/loopcaptain/board/app.py @@ -261,6 +261,12 @@ def totals() -> dict[str, object] | None: templates.env.globals["totals"] = totals + def waiting_now() -> int: + """How many loops wait for the person: a tab in the background shows it in its title and + says so in a notification, without drawing the page again.""" + figures = totals() + return int(cast(int, figures["waiting"])) if figures else 0 + def overview_fingerprint() -> str: """From file stats alone, in discovery order: the overview polls it every few seconds. Which loops are hidden is part of it: `hide` changes the page and no loop's file.""" @@ -372,7 +378,7 @@ def rank(view: LoopView) -> tuple[int, float]: @app.get("/pulse", name="overview_pulse") def overview_pulse() -> JSONResponse: try: - return JSONResponse({"pulse": overview_fingerprint()}) + return JSONResponse({"pulse": overview_fingerprint(), "waiting": waiting_now()}) except StoreError: return JSONResponse({"pulse": "error"}) @@ -435,7 +441,7 @@ def loop_pulse(repo_key: str, loop_id: str) -> JSONResponse: found = find_loop(config(), repo_key, loop_id) if found is None: raise HTTPException(404, "no such loop on this board") - return JSONResponse({"pulse": pulse_of(found[0], loop_id, steer)}) + return JSONResponse({"pulse": pulse_of(found[0], loop_id, steer), "waiting": waiting_now()}) @app.get("/loop/{repo_key}/{loop_id}/file", response_class=HTMLResponse, name="loop_file") def loop_file(request: Request, repo_key: str, loop_id: str, path: str) -> Response: diff --git a/src/loopcaptain/board/static/board.js b/src/loopcaptain/board/static/board.js index 482d5d3..d5f8ed1 100644 --- a/src/loopcaptain/board/static/board.js +++ b/src/loopcaptain/board/static/board.js @@ -26,8 +26,25 @@ return typed || document.querySelector("table.items details[open]") !== null; } + // A tab in the background is not drawn again, but it still says how many loops wait: in its + // title, and in a notification where the person allowed one. Nothing leaves this machine. + var canNotify = "Notification" in window; + var waiting = Number((document.title.match(/^\((\d+)\) /) || [0, 0])[1]); + + function showWaiting(count) { + if (typeof count !== "number" || count === waiting) return; + document.title = (count ? "(" + count + ") " : "") + document.title.replace(/^\(\d+\) /, ""); + if (count > waiting && canNotify && Notification.permission === "granted") { + var note = new Notification(count === 1 ? "A loop waits for you" : count + " loops wait for you", { + body: "Loopcaptain: open the board to answer.", + tag: "loopcaptain-waiting" + }); + note.onclick = function () { window.focus(); note.close(); }; + } + waiting = count; + } + function poll() { - if (document.hidden) return; fetch(url, { cache: "no-store" }) .then(function (response) { // 401: the board was started again and no longer knows this browser; the reload says so. @@ -35,12 +52,32 @@ return response.ok ? response.json() : null; }) .then(function (data) { - if (data && data.pulse !== seen && !busy()) window.location.reload(); + if (!data) return; + if (document.hidden) showWaiting(data.waiting); + else if (data.pulse !== seen && !busy()) window.location.reload(); }) .catch(function () { /* the board is restarting; the next poll tries again */ }); } - if (url) window.setInterval(poll, POLL_MS); + if (url) { + window.setInterval(poll, POLL_MS); + // Back in front: draw what changed meanwhile at once, not at the next tick. + document.addEventListener("visibilitychange", function () { if (!document.hidden) poll(); }); + } + + // Asking for a notification needs the person's own click; the footer offers it once. + var ask = document.querySelector("[data-notify]"); + var asked = document.querySelector("[data-notify-on]"); + if (ask && canNotify) { + ask.hidden = Notification.permission !== "default"; + asked.hidden = Notification.permission !== "granted"; + ask.addEventListener("click", function () { + Notification.requestPermission().then(function (answer) { + ask.hidden = true; + asked.hidden = answer !== "granted"; + }); + }); + } // A loop that said when it is back turns to stalled when that time passes, and no file changes // then, so the pulse stays as it is. The page names the moment; look again once it has come. diff --git a/src/loopcaptain/board/static/style.css b/src/loopcaptain/board/static/style.css index 1fe3fad..81b08bf 100644 --- a/src/loopcaptain/board/static/style.css +++ b/src/loopcaptain/board/static/style.css @@ -99,6 +99,7 @@ nav.strip a[aria-current] { background: var(--surface); color: var(--text); font the menu at its edges. */ :root { --page: 1560px; } main { width: 100%; max-width: var(--page); margin: 0 auto; padding: var(--s4) var(--s4) var(--s6); flex: 1; } +.foot button.link { min-height: 0; padding: 0; border: 0; background: none; color: var(--accent); font: inherit; text-decoration: underline; text-underline-offset: 3px; cursor: pointer; box-shadow: none; } .foot { width: 100%; max-width: var(--page); margin: 0 auto; padding: var(--s3) var(--s4) var(--s5); color: var(--text-2); font-size: var(--t12); border-top: 1px solid var(--line); } .crumb { font-size: var(--t14); color: var(--text-2); margin: 0; } /* the way back to the list: a link that reads as one and a target as tall as any control */ diff --git a/src/loopcaptain/board/templates/base.html b/src/loopcaptain/board/templates/base.html index 247f047..ce3b1d6 100644 --- a/src/loopcaptain/board/templates/base.html +++ b/src/loopcaptain/board/templates/base.html @@ -32,6 +32,6 @@
{% block main %}{% endblock %}
-
Reads each loop's .loops/ folder on every request. Answers only on this machine.
+
Reads each loop's .loops/ folder on every request. Answers only on this machine.
diff --git a/src/loopcaptain/cli.py b/src/loopcaptain/cli.py index 17a9204..0a815d6 100644 --- a/src/loopcaptain/cli.py +++ b/src/loopcaptain/cli.py @@ -8,6 +8,7 @@ import socket import sys from collections.abc import Callable +from dataclasses import replace from importlib.metadata import version as package_version from pathlib import Path @@ -18,14 +19,19 @@ from loopcaptain.board.discover import ( CONFIG_ENV, Config, + LoopView, as_written, config_in_use, config_target, edit_config, find_repos, + load_all, load_config, + put_aside, survey, ) +from loopcaptain.board.filters import ago +from loopcaptain.board.overview import GROUPS, group_of from loopcaptain.protocol import spec_text, store from loopcaptain.protocol.doctor import examine from loopcaptain.protocol.models import EVENT_NAMES, FOLDER, AnyEvent, InboxEntry, Manifest, now @@ -211,49 +217,73 @@ def build_parser() -> argparse.ArgumentParser: serve.add_argument("--port", type=int, default=8484, help="the port on 127.0.0.1, default 8484") validate = commands.add_parser("validate", help="check a repository's .loops folders") - validate.add_argument("repo", type=Path) + validate.add_argument("repo", type=Path, help="the repository whose .loops folders are checked") validate.add_argument("--strict", action="store_true", help="count warnings as problems") emit_cmd = commands.add_parser( - "emit", help="append one event: loopcaptain emit key=value ..." + "emit", help="append one event to a loop's log, its fields as key=value pairs, for a loop in shell" + ) + emit_cmd.add_argument("loop", help="the loop's id, the name of its folder in .loops/") + emit_cmd.add_argument( + "event", + choices=EVENT_NAMES, + help=f"the event to append, one of: {', '.join(EVENT_NAMES)}", + metavar="event", ) - emit_cmd.add_argument("loop") - emit_cmd.add_argument("event", choices=EVENT_NAMES) emit_cmd.add_argument( "fields", nargs="*", help="key=value; a value is read as JSON where it parses (round=2, blocks=true, " "ids='[\"a\"]'), and as text where the field is text (commit=1234567)", ) - emit_cmd.add_argument("--repo", type=Path, default=Path(".")) + emit_cmd.add_argument( + "--repo", type=Path, default=Path("."), help="the repository the loop lives in, default: this folder" + ) schema = commands.add_parser("schema", help="write the protocol as JSON Schema") - schema.add_argument("target", type=Path) + schema.add_argument("target", type=Path, help="the folder the schema files are written into") doctor = commands.add_parser("doctor", help="send a loop a stop and check that it takes it and ends") - doctor.add_argument("repo", type=Path) - doctor.add_argument("loop") + doctor.add_argument("repo", type=Path, help="the repository the loop lives in") + doctor.add_argument("loop", help="the loop's id, the name of its folder in .loops/") doctor.add_argument("--timeout", type=float, default=600, help="seconds to wait, default 600") watch = commands.add_parser( "watch", help="add a repository, or with --root a folder of them, to the board" ) - watch.add_argument("path", type=Path) + watch.add_argument("path", type=Path, help="a repository, or with --root a folder of repositories") watch.add_argument("--root", action="store_true", help="every sub-folder with .loops/ is a repository") unwatch = commands.add_parser("unwatch", help="take a folder off the board") - unwatch.add_argument("path", type=Path) + unwatch.add_argument("path", type=Path, help="the folder to take off, however the config spells it") + status = commands.add_parser("status", help="where every watched loop stands, in a terminal") + status.add_argument("--all", action="store_true", help="hidden and finished loops too") + inbox = commands.add_parser( + "inbox", help="what the person sent a loop since the last call, one line each, for a loop in shell" + ) + inbox.add_argument("loop", help="the loop's id, the name of its folder in .loops/") + inbox.add_argument( + "--repo", type=Path, default=Path("."), help="the repository the loop lives in, default: this folder" + ) + inbox.add_argument( + "--json", action="store_true", help="every entry as a JSON line, with signed and stale" + ) for name, about in ( ("hide", "take one loop off the board's first page and out of its figures"), ("unhide", "show a hidden loop on the first page again"), ): one_loop = commands.add_parser(name, help=about) - one_loop.add_argument("repo", type=Path) - one_loop.add_argument("loop") + one_loop.add_argument("repo", type=Path, help="the repository the loop lives in") + one_loop.add_argument("loop", help="the loop's id, the name of its folder in .loops/") demo = commands.add_parser( "demo", help="write the example loop into a folder and watch it; costs nothing" ) - demo.add_argument("--target", type=Path, default=Path("~/.local/share/loopcaptain/demo")) + demo.add_argument( + "--target", + type=Path, + default=Path("~/.local/share/loopcaptain/demo"), + help="the folder the example loop is written into, default ~/.local/share/loopcaptain/demo", + ) demo.add_argument("--no-watch", action="store_true", help="write it, but leave the config alone") mcp_config = commands.add_parser("mcp-config", help="how one coding agent adds the MCP server") @@ -350,6 +380,73 @@ def run_unhide(args: argparse.Namespace) -> int: return 0 +def status_lines(views: list[LoopView], *, everything: bool) -> list[str]: + """One line per loop, what needs the person first: status, where, round, last line, what it asks.""" + order = list(GROUPS) + kept = [view for view in views if everything or group_of(view) not in ("hidden", "finished")] + kept.sort(key=lambda view: (order.index(group_of(view)), view.repo.key, view.loop_id)) + width = max((len(f"{view.repo.key}/{view.loop_id}") for view in kept), default=0) + lines = [] + for view in kept: + state, name = view.state, f"{view.repo.key}/{view.loop_id}" + if state is None: + lines.append(f"{'unreadable':10} {name:{width}} {view.error}") + continue + last = state.last_round + told = f"asks: {state.question.text}" if state.question else state.last_line + parts = [ + f"round {last.number}" if last else "no round", + ago(state.last_event), + " ".join(told.split()), + ] + lines.append(f"{state.status:10} {name:{width}} " + " ".join(part for part in parts if part)) + return lines + + +def run_status(args: argparse.Namespace) -> int: + config = load_config() + views = [replace(view, hidden=put_aside(config, view.repo, view.loop_id)) for view in load_all(config)] + lines = status_lines(views, everything=args.all) + waiting = sum(1 for view in views if not view.hidden and view.state and view.state.question) + left_out = len(views) - len(lines) + say(lines or ["no loop to show"]) + say( + [ + f"{waiting} waiting for you" + + (f", {left_out} hidden or finished not shown (--all)" if left_out else "") + ] + ) + return 0 + + +def run_inbox(args: argparse.Namespace) -> int: + """The loop's side of the inbox for a loop that is no Python: what the person sent, marked read. + + Without `--json` only what a loop may act on is printed, `kind`, a tab, the text on one line: + entries the board signed for this loop that answer the present asking. The rest is counted + on standard error, so a script that reads the lines cannot take a forged one by mistake.""" + repo = args.repo.expanduser().resolve() + if args.loop not in store.loop_ids(repo): + raise StoreError(f"no loop {args.loop!r} in {args.repo}") + entries = store.taken(repo, args.loop) + if args.json: + say([json.dumps(entry, ensure_ascii=False) for entry in entries]) + return 0 + good = [entry for entry in entries if entry["signed"] is True and not entry["stale"]] + say([f"{entry['kind']}\t{' '.join(str(entry.get('text', '')).split())}" for entry in good]) + if len(good) < len(entries): + unchecked = any(entry["signed"] is None for entry in entries) + why = ( + "this loop's key cannot be read, so nothing was checked" + if unchecked + else "not from the board, or stale" + ) + sys.stderr.write( + f"loopcaptain: {len(entries) - len(good)} entry(ies) left out: {why}; --json shows them\n" + ) + return 0 + + def run_demo(args: argparse.Namespace) -> int: from loopcaptain.demo import DemoError, write_demo @@ -367,6 +464,10 @@ def run_demo(args: argparse.Namespace) -> int: return 0 +#: How the MCP server gets its SDK, said wherever it is missing or about to be needed. +MCP_EXTRA = "Install with it: `uv tool install 'loopcaptain[mcp]'` (or `pipx install 'loopcaptain[mcp]'`)" + + def run_mcp_config(args: argparse.Namespace) -> int: if args.markdown: sys.stdout.write(markdown()) @@ -379,6 +480,8 @@ def run_mcp_config(args: argparse.Namespace) -> int: except KeyError as error: raise StoreError(str(error.args[0])) from error sys.stdout.write(f"{item.name}\n\n{item.add}\n\nunattended: {item.headless}\n") + if not args.checkout: + sys.stdout.write(f"\nthe server needs the MCP extra. {MCP_EXTRA}\n") return 0 @@ -388,7 +491,12 @@ def run_spec(args: argparse.Namespace) -> int: def run_mcp(args: argparse.Namespace) -> int: - from loopcaptain.mcp_server.server import serve_stdio + try: + from loopcaptain.mcp_server.server import serve_stdio + except ImportError as error: + if (error.name or "").split(".")[0] != "mcp": + raise + raise StoreError(f"the MCP server needs the extra, which is not installed. {MCP_EXTRA}") from error serve_stdio() return 0 @@ -407,6 +515,8 @@ def run_serve(args: argparse.Namespace) -> int: "doctor": run_doctor, "watch": run_watch, "unwatch": run_unwatch, + "status": run_status, + "inbox": run_inbox, "hide": run_hide, "unhide": run_unhide, "demo": run_demo, diff --git a/src/loopcaptain/mcp_server/AGENTS.md b/src/loopcaptain/mcp_server/AGENTS.md index 6bbb1ca..1a809c4 100644 --- a/src/loopcaptain/mcp_server/AGENTS.md +++ b/src/loopcaptain/mcp_server/AGENTS.md @@ -1,4 +1,4 @@ -# mcp_server/: the MCP door +# mcp_server/: the MCP server Read [the root AGENTS.md](../../../AGENTS.md) first. `server.py` exposes the protocol as MCP tools for a loop that an agent session drives without @@ -8,7 +8,7 @@ Rules here: 1. Five tools and no more: `protocol`, `loop_register`, `emit`, `inbox_read`, `loop_status`. They mirror the helper's three verbs, so - a loop reads the same on both doors and the tool list stays short in + a loop reads the same from a script and from a session, and the tool list stays short in an agent's context. A new event is a new value for `emit`, not a tool. 2. A tool writes exactly what the helper in `standard/loops.py` would write. No tool adds state of its own; `tests/test_mcp.py` validates the diff --git a/src/loopcaptain/mcp_server/server.py b/src/loopcaptain/mcp_server/server.py index 28ddd10..7292f1c 100644 --- a/src/loopcaptain/mcp_server/server.py +++ b/src/loopcaptain/mcp_server/server.py @@ -1,10 +1,11 @@ -"""The MCP door: the protocol as five tools, for a loop that an agent session drives. +"""The MCP server: the protocol as five tools, for a loop that an agent session drives. The tools mirror the helper a script pastes (`register`, `emit`, `inbox`), so there is one -vocabulary on both doors and the tool list stays small in the agent's context. Every tool writes -the same files; the board cannot tell the two doors apart. `repo` is the repository the loop -lives in; left out, it is the folder the server was started in, which is the agent's working folder. -A `repo` outside that folder is refused unless `LOOPCAPTAIN_MCP_ROOTS` names a folder above it. +vocabulary for a script and for a session, and the tool list stays small in the agent's context. +Every tool writes the same files the helper writes; the board cannot tell which of the two wrote +a line. `repo` is the repository the loop lives in; left out, it is the folder the server was +started in, which is the agent's working folder. A `repo` outside that folder is refused unless +`LOOPCAPTAIN_MCP_ROOTS` names a folder above it. """ from __future__ import annotations @@ -18,8 +19,8 @@ from pydantic import ValidationError from loopcaptain.protocol import spec_text, store -from loopcaptain.protocol.models import EVENT_NAMES, Manifest, Question, now -from loopcaptain.protocol.signing import is_signed, read_loop_key, unchecked_ids +from loopcaptain.protocol.models import EVENT_NAMES, Manifest, now +from loopcaptain.protocol.signing import unchecked_ids from loopcaptain.protocol.state import fold from loopcaptain.protocol.store import StoreError from loopcaptain.protocol.validate import before_writing @@ -160,18 +161,7 @@ def inbox_read(loop_id: str, repo: str = ".") -> list[dict[str, Any]]: stale: true for a reply that names a question and was written before you last asked that question: it answers an earlier asking, do not take it as the answer now. """ - path = known_loop(repo, loop_id) - key = read_loop_key(store.loop_dir(path, loop_id)) - events, _ = store.read_events(path, loop_id) - asked = {event.id: event.ts for event in events if isinstance(event, Question) and event.id} - return [ - { - **entry.model_dump(mode="json", exclude_none=True), - "signed": is_signed(entry.body(), key, loop_id), - "stale": entry.question in asked and entry.ts < asked[entry.question], - } - for entry in store.take_inbox(path, loop_id) - ] + return store.taken(known_loop(repo, loop_id), loop_id) @server.tool() diff --git a/src/loopcaptain/protocol/store.py b/src/loopcaptain/protocol/store.py index 83e68a7..88c23c4 100644 --- a/src/loopcaptain/protocol/store.py +++ b/src/loopcaptain/protocol/store.py @@ -29,10 +29,11 @@ InboxKind, InboxRead, Manifest, + Question, is_slug, now, ) -from loopcaptain.protocol.signing import BoardKeys, hand_out, marks +from loopcaptain.protocol.signing import BoardKeys, hand_out, is_signed, marks, read_loop_key from loopcaptain.protocol.state import STALE_AFTER #: The most the board reads of one file. A summary log of a long loop is a few hundred kilobytes. @@ -308,6 +309,23 @@ def take_inbox(repo: Path, loop_id: str) -> list[InboxEntry]: return fresh +def taken(repo: Path, loop_id: str) -> list[dict[str, Any]]: + """What the person sent since the last call, as every way in hands it to a loop: each entry + with `signed` (true only for a line the board wrote for this loop, None where the loop's key + cannot be read) and `stale` (a reply to an earlier asking of its question). Marks them read.""" + key = read_loop_key(loop_dir(repo, loop_id)) + events, _ = read_events(repo, loop_id) + asked = {event.id: event.ts for event in events if isinstance(event, Question) and event.id} + return [ + { + **entry.model_dump(mode="json", exclude_none=True), + "signed": is_signed(entry.body(), key, loop_id), + "stale": entry.question in asked and entry.ts < asked[entry.question], + } + for entry in take_inbox(repo, loop_id) + ] + + def fingerprint(repo: Path, loop_id: str) -> str: """Changes whenever any of the loop's files does, and once more when the loop has written nothing for so long that a round under way reads as stalled; the page polls it to know when diff --git a/standard/LOOPS.md b/standard/LOOPS.md index cfc7617..86078db 100644 --- a/standard/LOOPS.md +++ b/standard/LOOPS.md @@ -479,7 +479,8 @@ A loop that an agent session drives, with no script of its own, uses the | `loop_status` | returns where a loop stands, or the loops of a repository | | Five tools on purpose: the same three verbs as the helper, so a loop reads -the same on both doors, and a short tool list in the agent's context. +the same from a script and from a session, and a short tool list in the +agent's context. ## 6. Conformance diff --git a/tests/test_board.py b/tests/test_board.py index 636d649..cc311ef 100644 --- a/tests/test_board.py +++ b/tests/test_board.py @@ -801,6 +801,26 @@ def later(days: int) -> datetime: assert 'class="pill stalled"' in old and 'class="old"' in old +def test_a_tab_in_the_background_learns_how_many_loops_wait_and_may_say_so( + client: TestClient, scan: Path, helper: types.ModuleType +) -> None: + """A tab that is not in front is not drawn again, so its title kept an old count and nothing told the person.""" + before = ( + client.get("/pulse").json()["waiting"], + client.get("/loop/some-repo/scan/pulse").json()["waiting"], + ) + helper.emit("scan", "question", {"id": "seats", "text": "Per seat?"}, scan) + after = client.get("/pulse").json()["waiting"], client.get("/loop/some-repo/scan/pulse").json()["waiting"] + page = client.get("/").text + script = (Path(steer.__file__).parent / "static" / "board.js").read_text(encoding="utf-8") + + assert before == (0, 0) and after == (1, 1) + assert "data-notify hidden" in page and "data-notify-on hidden" in page + assert "if (document.hidden) showWaiting(data.waiting);" in script + assert 'Notification.permission === "granted"' in script and "Notification.requestPermission()" in script + assert "http" not in script.split("new Notification")[1].split("};")[0] # nothing fetched to say it + + def test_every_status_has_a_place_on_the_overview_and_a_meaning() -> None: assert set(get_args(Status)) == set(STATUS_ORDER) == set(STATUS_TEXT) diff --git a/tests/test_cli_board.py b/tests/test_cli_board.py index 2e8432e..19ba856 100644 --- a/tests/test_cli_board.py +++ b/tests/test_cli_board.py @@ -3,6 +3,7 @@ from __future__ import annotations import ast +import json import socket import types from pathlib import Path @@ -17,6 +18,7 @@ from loopcaptain.board.discover import Config, load_config, parse_config from loopcaptain.board.steer import Runner from loopcaptain.cli import main as cli_main +from loopcaptain.protocol import signing, store @pytest.fixture @@ -497,3 +499,71 @@ def test_hide_refuses_a_loop_that_is_not_there( assert "no loop 'ghost'" in capsys.readouterr().err assert not (home / ".config" / "loopcaptain" / "config.yaml").exists() + + +def test_status_says_in_a_terminal_where_every_watched_loop_stands( + scan: Path, + helper: types.ModuleType, + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + """What waits was seen only on the board; a person in a terminal had to open a browser to know.""" + helper.register("asks", {"title": "Asks"}, scan) + helper.emit("asks", "round_started", {"round": 1}, scan) + helper.emit("asks", "question", {"id": "seats", "text": "Per seat\nor per team?"}, scan) + helper.register("over", {"title": "Over"}, scan) + helper.emit("over", "round_started", {"round": 1}, scan) + helper.emit("over", "round_finished", {"round": 1, "verdict": "done"}, scan) + config = tmp_path / "config.yaml" + config.write_text(f"repos:\n - {scan}\nhidden:\n - {scan}/.loops/scan\n") + monkeypatch.setenv("LOOPCAPTAIN_CONFIG", str(config)) + + assert cli_main(["status"]) == 0 + shown = capsys.readouterr().out.splitlines() + assert cli_main(["status", "--all"]) == 0 + everything = capsys.readouterr().out + + assert len(shown) == 2 and shown[0].startswith("running some-repo/asks round 1") + assert shown[0].endswith("asks: Per seat or per team?") + assert shown[1] == "1 waiting for you, 2 hidden or finished not shown (--all)" + assert "some-repo/scan" in everything and "done some-repo/over" in everything + + +def test_inbox_prints_what_a_shell_loop_may_act_on_and_marks_it_read( + scan: Path, capsys: pytest.CaptureFixture[str] +) -> None: + """A loop in shell could write events with `emit` and had no way to read what the person sent.""" + keys = signing.board_keys() + store.append_inbox(scan, "scan", "reply", "Look at\nprices first.", keys=keys) + store.append_inbox(scan, "scan", "stop", keys=keys) + store.append_line( + scan / ".loops" / "scan" / "inbox.jsonl", '{"id": "f1", "ts": "2026-11-15T00:00:00Z", "kind": "stop"}' + ) + + assert cli_main(["inbox", "scan", "--repo", str(scan)]) == 0 + first = capsys.readouterr() + assert cli_main(["inbox", "scan", "--repo", str(scan)]) == 0 + second = capsys.readouterr() + + assert first.out == "reply\tLook at prices first.\nstop\t\n" + assert "1 entry(ies) left out: not from the board, or stale" in first.err + assert second.out == "" and second.err == "" + + +def test_inbox_as_json_shows_every_entry_with_what_was_checked( + scan: Path, capsys: pytest.CaptureFixture[str] +) -> None: + store.append_inbox(scan, "scan", "stop", keys=signing.board_keys()) + store.append_line( + scan / ".loops" / "scan" / "inbox.jsonl", '{"id": "f1", "ts": "2026-11-15T00:00:00Z", "kind": "stop"}' + ) + + assert cli_main(["inbox", "scan", "--repo", str(scan), "--json"]) == 0 + lines = [json.loads(line) for line in capsys.readouterr().out.splitlines()] + + assert [(entry["kind"], entry["signed"], entry["stale"]) for entry in lines] == [ + ("stop", True, False), + ("stop", False, False), + ] + assert cli_main(["inbox", "ghost", "--repo", str(scan)]) == 1 diff --git a/tests/test_docs.py b/tests/test_docs.py index db96949..8e0d103 100644 --- a/tests/test_docs.py +++ b/tests/test_docs.py @@ -5,6 +5,7 @@ import importlib.util import json import re +import struct import sys import tomllib import types @@ -360,3 +361,18 @@ def test_every_written_page_tells_a_search_engine_what_it_is_about_in_its_own_wo assert front_matter(ROOT / "docs" / "index.md").get("title", "Home") != "Home" assert [name for name, text in descriptions.items() if not 40 <= len(text) <= 160] == [] assert len(set(descriptions.values())) == len(descriptions) + + +def test_a_shared_link_and_a_search_result_get_a_title_a_sentence_and_a_picture() -> None: + """The site wrote no card data and loaded its fonts from another host.""" + theme = tomllib.loads((ROOT / "zensical.toml").read_text(encoding="utf-8"))["project"]["theme"] + head = (ROOT / "overrides" / "main.html").read_text(encoding="utf-8") + card = (ROOT / "docs" / "assets" / "social-card.png").read_bytes() + + assert theme["custom_dir"] == "overrides" and theme["font"] is False + for name in ("og:title", "og:description", "og:url", "og:image", "twitter:card", "application/ld+json"): + assert name in head + assert "assets/social-card.png" in head and "http" not in head.replace("https://schema.org", "").replace( + "https://www.apache.org/licenses/LICENSE-2.0", "" + ) + assert card[:8] == b"\x89PNG\r\n\x1a\n" and struct.unpack(">II", card[16:24]) == (1200, 630) diff --git a/tests/test_mcp.py b/tests/test_mcp.py index 1ef530f..0c8dc2e 100644 --- a/tests/test_mcp.py +++ b/tests/test_mcp.py @@ -4,7 +4,9 @@ import asyncio import re +import sys import time +import tomllib from pathlib import Path from typing import Any, get_args @@ -18,6 +20,8 @@ from loopcaptain.protocol.validate import validate_repo from tests.conftest import STEPS +ROOT = Path(__file__).resolve().parents[1] + MANIFEST: dict[str, Any] = { "title": "Planning rounds", "brief": {"goal": "Decide the design."}, @@ -317,3 +321,20 @@ def test_finding_closed_before_its_round_is_written_as_validate_allows(tmp_path: {"ts": "2026-11-16T08:00:00Z", "event": "finding_closed", "round": 3, "step": "a", "id": "f1"} ) assert refusals(tmp_path, manifest, [], event) == [] + + +def test_the_mcp_server_is_an_extra_and_says_so_where_it_is_missing( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + """The SDK was about half of a plain install, and the board and the helper never load it.""" + project = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))["project"] + assert not [name for name in project["dependencies"] if name.startswith("mcp")] + assert project["optional-dependencies"]["mcp"] == ["mcp>=2.0"] + monkeypatch.delitem(sys.modules, "loopcaptain.mcp_server.server", raising=False) + for name in ("mcp", "mcp.server", "mcp.server.mcpserver"): # as on a machine without the extra + monkeypatch.setitem(sys.modules, name, None) + + assert main(["mcp"]) == 1 + assert "uv tool install 'loopcaptain[mcp]'" in capsys.readouterr().err + assert main(["mcp-config", "claude-code", "--checkout", ""]) == 0 + assert "the server needs the MCP extra" in capsys.readouterr().out diff --git a/tests/test_release.py b/tests/test_release.py index be53f5e..1c6bcb9 100644 --- a/tests/test_release.py +++ b/tests/test_release.py @@ -71,6 +71,22 @@ def test_the_notes_list_what_users_notice_under_headings(release: types.ModuleTy assert "keep the table readable" not in text +def test_a_note_carries_the_reasons_its_commit_gives(release: types.ModuleType) -> None: + """A release note was one subject line; why the change was made stayed in the commit.""" + body = ( + "- A reply closed whichever question was asked last,\n whatever it named.\n" + "- Open questions are kept per asking.\n\nNot a bullet.\n- [x] A check box of a pull request.\n" + ) + + text = release.notes([release.Commit("1234567890", "fix(board): keep every open question", body)]) + + assert text == ( + "## Fixed\n\n- **board**: keep every open question (1234567)\n" + " - A reply closed whichever question was asked last, whatever it named.\n" + " - Open questions are kept per asking." + ) + + def test_the_checkout_carries_no_version_of_its_own() -> None: project = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))["project"] diff --git a/tests/test_shell_loop.py b/tests/test_shell_loop.py new file mode 100644 index 0000000..b26c641 --- /dev/null +++ b/tests/test_shell_loop.py @@ -0,0 +1,91 @@ +"""The worked shell loop of the docs runs as printed: it reports, takes a note and a stop, and ends.""" + +from __future__ import annotations + +import os +import re +import subprocess +import sys +from pathlib import Path + +from loopcaptain.protocol import signing, store +from loopcaptain.protocol.models import now +from loopcaptain.protocol.state import LoopState, fold +from loopcaptain.protocol.validate import validate_report + +ROOT = Path(__file__).resolve().parents[1] +#: An agent that needs two runs: the first leaves a mark, the second finishes the work. +AGENT = "cat >> seen-prompt.txt; if [ -f once ]; then touch finished; fi; touch once; echo worked" + + +def loop_script() -> str: + page = (ROOT / "docs" / "shell-loop.md").read_text(encoding="utf-8") + found = re.search(r"```bash\n(#!/usr/bin/env bash\n# loop\.sh.*?)```", page, re.DOTALL) + assert found is not None + return found.group(1) + + +def run(repo: Path, *, agent: str = AGENT) -> None: + # `loopcaptain` as this checkout has it, whatever else of that name is installed on the machine. + shim = repo.parent / "bin" + shim.mkdir(exist_ok=True) + source = ROOT / "src" + (shim / "loopcaptain").write_text( + f'#!/bin/sh\nPYTHONPATH="{source}" exec "{sys.executable}" -m loopcaptain.cli "$@"\n' + ) + (shim / "loopcaptain").chmod(0o755) + env = { + # Without a file a non-interactive bash reads first: on some machines it puts another PATH first. + **{name: value for name, value in os.environ.items() if name not in ("BASH_ENV", "ENV")}, + "PATH": f"{shim}{os.pathsep}{os.environ['PATH']}", + "AGENT_CMD": agent, + "CHECK_CMD": "test -f finished", + "MAX_ROUNDS": "3", + } + subprocess.run(["bash", "loop.sh"], cwd=repo, env=env, check=True, timeout=120) + + +def state_of(repo: Path) -> LoopState: + events, problems = store.read_events(repo, "ralph") + assert problems == [] + return fold(store.read_manifest(repo, "ralph"), events, store.read_inbox(repo, "ralph")[0], now()) + + +def shell_repo(tmp_path: Path) -> Path: + repo = tmp_path / "shell" + repo.mkdir(parents=True) + (repo / "loop.sh").write_text(loop_script(), encoding="utf-8") + (repo / "PROMPT.md").write_text("Make the check pass.\n", encoding="utf-8") + return repo + + +def test_the_shell_loop_of_the_docs_reports_its_rounds_and_ends_done(tmp_path: Path) -> None: + repo = shell_repo(tmp_path) + + run(repo) + + state = state_of(repo) + assert [round_.verdict for round_ in state.rounds] == ["continue", "done"] and state.status == "done" + assert validate_report(repo).problems == [] + assert (repo / "out" / "round-2.md").read_text(encoding="utf-8") == "worked\n" + + +def test_the_shell_loop_hands_a_note_to_the_agent_and_takes_a_stop(tmp_path: Path) -> None: + repo = shell_repo(tmp_path) + run(repo, agent="cat > seen-prompt.txt; echo tried") # never done: it stops at its cap + assert state_of(repo).status != "done" + keys = signing.board_keys() + store.append_inbox(repo, "ralph", "stop", keys=keys) + run(repo) + stopped = state_of(repo) + + fresh = shell_repo(tmp_path / "second") + (fresh / ".loops" / "ralph").mkdir(parents=True) + (fresh / ".loops" / "ralph" / "loop.json").write_text('{"protocol": 1, "id": "ralph"}', encoding="utf-8") + store.append_inbox(fresh, "ralph", "reply", "Leave the migration alone.", keys=keys) + run(fresh) + + assert stopped.ended is not None and stopped.ended.stop_reason == "person" + assert "From the person:\nLeave the migration alone." in (fresh / "seen-prompt.txt").read_text( + encoding="utf-8" + ) diff --git a/uv.lock b/uv.lock index 51dd632..67679c4 100644 --- a/uv.lock +++ b/uv.lock @@ -697,16 +697,21 @@ dependencies = [ { name = "fastapi" }, { name = "jinja2" }, { name = "markdown-it-py" }, - { name = "mcp" }, { name = "pydantic" }, { name = "python-multipart" }, { name = "pyyaml" }, { name = "uvicorn" }, ] +[package.optional-dependencies] +mcp = [ + { name = "mcp" }, +] + [package.dev-dependencies] dev = [ { name = "httpx" }, + { name = "mcp" }, { name = "mypy" }, { name = "pre-commit" }, { name = "pytest" }, @@ -723,16 +728,18 @@ requires-dist = [ { name = "fastapi", specifier = ">=0.115" }, { name = "jinja2", specifier = ">=3.1" }, { name = "markdown-it-py", specifier = ">=3.0" }, - { name = "mcp", specifier = ">=2.0" }, + { name = "mcp", marker = "extra == 'mcp'", specifier = ">=2.0" }, { name = "pydantic", specifier = ">=2.7" }, { name = "python-multipart", specifier = ">=0.0.9" }, { name = "pyyaml", specifier = ">=6.0" }, { name = "uvicorn", specifier = ">=0.30" }, ] +provides-extras = ["mcp"] [package.metadata.requires-dev] dev = [ { name = "httpx", specifier = ">=0.27" }, + { name = "mcp", specifier = ">=2.0" }, { name = "mypy", specifier = ">=1.11" }, { name = "pre-commit", specifier = ">=4.0" }, { name = "pytest", specifier = ">=8" }, diff --git a/zensical.toml b/zensical.toml index c3c5f38..8ec2fa4 100644 --- a/zensical.toml +++ b/zensical.toml @@ -12,6 +12,7 @@ nav = [ { "Get started" = "get-started.md" }, { "Setup" = "setup.md" }, { "Connect or build a loop" = "connect.md" }, + { "Monitor a Ralph or shell loop" = "shell-loop.md" }, { "Works with every agent" = "agents.md" }, { "The board" = "board.md" }, { "The protocol" = "protocol/index.md" }, @@ -20,6 +21,7 @@ nav = [ { "MCP tools" = "reference/mcp.md" }, { "Configuration" = "reference/configuration.md" }, ] }, + { "Questions and answers" = "faq.md" }, { "OpenTelemetry" = "opentelemetry.md" }, { "Security" = "security.md" }, { "Architecture" = "ARCHITECTURE.md" }, @@ -27,6 +29,12 @@ nav = [ { "Contributing" = "contributing.md" }, ] +# The pages load nothing from another host: no web fonts, the reader's own are used. The override +# adds what a shared link and a search result show (overrides/main.html). +[project.theme] +custom_dir = "overrides" +font = false + [[project.theme.palette]] scheme = "default" toggle.icon = "lucide/sun"