diff --git a/.agent/DEFERRED_VERIFICATION.md b/.agent/DEFERRED_VERIFICATION.md index c8944d7..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 | @@ -25,3 +24,4 @@ is named in the commit that closes it. | 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 55c87fc..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 | diff --git a/AGENTS.md b/AGENTS.md index 4f15c20..ce6413f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -143,13 +143,14 @@ stdio, installed with its extra (`uv tool install 'loopcaptain[mcp]'`): 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/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/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 bd14a98..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." --- diff --git a/docs/llms.txt b/docs/llms.txt index 2ec6e3e..6b24a36 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -20,6 +20,7 @@ - [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 f9bc9ee..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,7 @@ loopcaptain unwatch [-h] path | Argument | Meaning | |---|---| -| `path` | | +| `path` | the folder to take off, however the config spells it | ## `status` @@ -120,8 +117,8 @@ loopcaptain inbox [-h] [--repo REPO] [--json] loop | Argument | Meaning | |---|---| -| `loop` | | -| `--repo` | | +| `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` @@ -134,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` @@ -147,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` @@ -160,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] @@ -179,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] @@ -187,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 index 6bf51aa..48661c9 100644 --- a/docs/shell-loop.md +++ b/docs/shell-loop.md @@ -1,4 +1,5 @@ --- +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." --- 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/scripts/docs_pages.py b/scripts/docs_pages.py index ee79bca..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)] @@ -97,6 +99,7 @@ def llms_txt() -> str: 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/cli.py b/src/loopcaptain/cli.py index fd3d47b..0a815d6 100644 --- a/src/loopcaptain/cli.py +++ b/src/loopcaptain/cli.py @@ -217,44 +217,53 @@ 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") - inbox.add_argument("--repo", type=Path, default=Path(".")) + 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" ) @@ -263,13 +272,18 @@ def build_parser() -> argparse.ArgumentParser: ("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") 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 dd33607..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 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_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_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/zensical.toml b/zensical.toml index 8617cd1..8ec2fa4 100644 --- a/zensical.toml +++ b/zensical.toml @@ -21,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" }, @@ -28,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"