pi-superagent 0.1.0 → 0.1.1

package/ADAPTATION.md

@@ -1,13 +1,18 @@
 # Adaptation ledger
 
-The engine in `src/core/` is DeepSeek's, copied from upstream without a single change. This file is the
-record that keeps that true: the commit it was copied from, how to prove the copy is exact, and where
-everything that is *not* upstream plugs in.
+If you follow a request from GitHub into the code, you’ll cross a boundary at `src/core/`.
+DeepSeek’s dsh-superagent-prototype supplies the rules for opening a ticket, assigning a worker
+and recording the outcome. This project supplies the pieces that talk to GitHub, run pi and keep
+the worker’s terminal open in herdr.
+
+That split gives maintainers a place to start. For a question about what a *ready* report means,
+look in the engine. For a question about how that report becomes a GitHub comment, look in
+`src/pi/`. The tables below identify the upstream files and the local code on either side.
 
 ## The baseline
 
-Upstream commit `8c32a9dc5d72c033816c6a8110b37f40cf94fba4`, also recorded in
-`vendor/dsh-superagent/UPSTREAM_SHA`. At that commit these are byte-identical:
+The files below match upstream commit `8c32a9dc5d72c033816c6a8110b37f40cf94fba4` byte for byte.
+The pinned revision is recorded in `vendor/dsh-superagent/UPSTREAM_SHA`.
 
 | Here | Upstream |
 | --- | --- |
@@ -16,7 +21,7 @@ Upstream commit `8c32a9dc5d72c033816c6a8110b37f40cf94fba4`, also recorded in
 | `vendor/dsh-superagent/docs/` | `docs/` |
 | `vendor/dsh-superagent/LICENSE` | `LICENSE` |
 
-To prove it, compare against a fresh clone. Every `diff` should print nothing:
+Run these comparisons from the repository root. Each `diff` exits successfully for an exact match.
 
 ```sh
 git clone https://github.com/deepseek-ai/dsh-superagent-prototype /tmp/upstream
@@ -24,50 +29,43 @@ git -C /tmp/upstream checkout "$(cat vendor/dsh-superagent/UPSTREAM_SHA)"
 diff -r /tmp/upstream/src/core src/core
 diff /tmp/upstream/tests/core-engine.spec.ts test/core-engine.spec.ts
 diff -r /tmp/upstream/docs vendor/dsh-superagent/docs
+diff /tmp/upstream/LICENSE vendor/dsh-superagent/LICENSE
 ```
 
 ## Deviations
 
-None. If one is ever unavoidable, list it here with the file, the upstream commit it was measured
-against, what changed and why, so that the next upstream fix can still be merged by hand.
+There are currently no local deviations. Record any future change here with the affected file, upstream
+revision and reason. Maintainers will need that history when they apply the next upstream fix.
 
-## Where this repository plugs in
+## Local adapters
 
-The engine is synchronous and does no I/O of its own. Everything that touches a process, the network or
-a model reaches it through an interface in `src/core/ports.ts`, and every binding of those interfaces
-lives in `src/pi/`:
+The engine is synchronous and does no I/O of its own. The interfaces in `src/core/ports.ts` connect it to storage, processes and
+models. Their implementations live in `src/pi/`.
 
 | Port | Bound in | How |
 | --- | --- | --- |
 | `Repositories` | `store.ts` | synchronous `node:sqlite` in WAL mode with `synchronous=FULL`, one transaction per engine command |
 | `Policy` | `router.ts` (`policyOf`) | admits a trigger only from a person who is not on the bot list |
-| `SourceScope` | `extension.ts` | every thread is listened to |
+| `SourceScope` | `router.ts` (`scopeOf`) | filters incoming authors by GitHub association or the configured login list |
 | `Assessor` | `assessor.ts`, `judge.ts` | candidates go one at a time to a headless pi judge, which answers with `ticket_decide` |
 | `Executor` | `executor.ts`, `herdr-workers.ts` | one pi session per assignment, in its own herdr tab, reached through files that outlive the router |
 | `Outbox` | `outbox.ts` | GitHub comments, queued once per id and marked sent only once GitHub accepts them |
 
-Sources are not a port upstream; the engine simply receives Triggers. `source-github.ts` produces them
-from issues, comments and reviews, with read positions kept in the same SQLite file as the engine's state.
-
-Upstream ships its own executor, Feishu and GitHub sources, panel and SQLite store. None of them are
-vendored: this repository replaces them with pi sessions in herdr, the GitHub source above, the panel in
-`server.ts`, and the store in `store.ts`.
-
-Two of upstream's rules carry through every binding:
+The engine accepts triggers directly. `source-github.ts` converts issues, comments and reviews
+into triggers and saves its read positions in the engine’s SQLite database. Upstream also ships a
+Feishu source, an executor, a panel and a store. This project supplies its own GitHub integration,
+herdr workers, panel (`server.ts`) and storage adapter (`store.ts`).
 
-- **A report is a tool call, not prose.** A worker's `ticket_report` call sets the state of its
-  assignment; a question in a *blocked* report becomes the ticket's request for a person.
-- **Only the engine writes a ticket.** A worker that could edit its own ticket could mark its own work
-  done.
+Only the engine writes a ticket. The worker submits its assignment outcome through
+`ticket_report`. A *blocked* report carries the question that the router posts for the requester.
 
 ## Tests
 
-`test/core-engine.spec.ts` is upstream's engine suite, unchanged. `test/sqlite-engine.spec.ts` runs the
-same 113 cases against the SQLite store, with one line changed, because durability can only be tested
-against a store that survives the process.
+`test/core-engine.spec.ts` is the upstream engine suite. `test/sqlite-engine.spec.ts` runs the
+same 113 cases against the local SQLite adapter, exercising the same transitions with persistent storage.
 
 ## Taking an upstream change
 
-Copy upstream's `src/core/`, `tests/core-engine.spec.ts` and `docs/` over their counterparts here, update
-`UPSTREAM_SHA`, and run `npm run check` and `scripts/check-formal`. If a ticket transition changed,
-change `formal/Ticket.tla` to match before trusting the result.
+Copy the files listed in the baseline table to their corresponding local paths and update
+`vendor/dsh-superagent/UPSTREAM_SHA`. If a ticket transition changed, update `formal/Ticket.tla`.
+Run `npm run check` and `scripts/check-formal` against the new baseline.

package/README.md

@@ -1,67 +1,21 @@
 # pi-superagent
 
-**Open a GitHub issue. An agent does the work and answers you there.**
-
-pi-superagent watches one GitHub repository. When someone opens an issue, comments on one, or reviews a
-pull request, a judge reads it and decides whether a person has asked for something concrete. If one has,
-a ticket opens and a worker starts: a full [pi](https://github.com/earendil-works/pi) session in its own
-tab of herdr, a terminal multiplexer for coding agents, where you can watch it work, type into it, or take
-over. The worker finishes by calling a report tool, and the result arrives on the issue as a reply. Work
-that changes a repository arrives as a pull request, and the ticket stays open until it is merged.
-
-There are no labels to learn and no board to tend. The issue is the request, a comment is a follow-up,
-and closing the issue is the stop.
-
-The ticket engine underneath is DeepSeek's
-[dsh-superagent-prototype](https://github.com/deepseek-ai/dsh-superagent-prototype), vendored
-byte-for-byte. This repository binds it to pi, herdr and GitHub.
-
-## How a request travels
-
-1. **Trigger.** A new issue is a request; so is a comment on an issue or a pull request, and so is a
-   submitted review. Only people with write access to the repository are heard: on a public repository
-   anyone can open an issue, and a request starts a worker with a shell on your machine. On its first
-   look at a repository the router records what is already there and fires none of it.
-2. **Judgement.** The judge, a headless pi session, reads the request with its link and answers through
-   a tool: *accept*, *ignore* (chatter, a note to a colleague, a thread that already has a ticket) or
-   *stop*.
-3. **Work.** An accept opens a ticket and posts the judge's acknowledgement on the issue. A worker starts
-   in a workspace of its own, briefed with the ticket's mandate. Every later comment a person writes on
-   the thread goes straight to that worker.
-4. **Report.** The worker ends every run by calling `ticket_report`, and the router posts the report on
-   the issue. A *blocked* report asks you a question there, and your reply goes straight back to the
-   worker. A run that ends without a report, a worker that crashes, and a launch that fails are posted
-   too, each with what you can do next. A crashed worker is replaced once, without anyone asking.
-5. **Pull request.** Work that changes a repository, in any repository, goes out as a pull request the
-   worker opens and names in its report. The ticket then waits for review: comments and reviews on the
-   pull request go to the same worker. The merge ends the ticket, and the issue hears it is done; closing
-   the pull request unmerged ends it too. Work that changes no repository, such as an answer, an
-   investigation or a deployment, ends with its report.
-
-Closing the issue stops its ticket and says so on the thread. Reopening the issue starts the request again.
-
-## Why it is built this way
-
-pi-superagent grew out of a setup where agents polled markdown cards, prompts were typed into terminal
-panes, and a classifier guessed from prose whether a person had answered. Every failure there was the
-same defect in a different hat: **state recorded as text, transitions guessed by readers.** Three rules
-answer it:
-
-- **A worker reports through a tool call, never in prose.** "Done" in a chat message changes nothing.
-- **Only the engine writes a ticket.** A worker that could edit its own ticket could mark its own work done.
-- **A restart loses nothing and repeats nothing.** A read position commits only once the engine holds
-  what it produced, every trigger carries an id the engine accepts once, and every outgoing message
-  carries an id the outbox posts once.
-
-The ticket lifecycle, the GitHub intake and the worker sweep are specified in TLA+ and checked
-exhaustively, 1.5 million distinct states in all, by one command.
+Open a GitHub issue and tell pi-superagent what you’d like to change. A coding agent works on it
+in a checkout on your machine and opens a pull request for you to review. If you ask for a
+revision, the same agent picks it up.
+
+You can follow the conversation on GitHub or open the agent’s terminal to see what it’s trying
+and lend a hand.
 
 ## Install
 
-Use macOS or Linux with Git, Node 22.19 or later, [pi](https://github.com/earendil-works/pi),
-[herdr](https://herdr.dev), and the [GitHub CLI](https://cli.github.com).
-Sign into a model provider in pi and confirm your model appears in `pi --list-models`.
-Use a GitHub account with write access to the repository you want to watch.
+You’ll need Git, Node 22.19 or later, and three tools on a Mac or Linux machine. Pi runs the coding
+sessions. Herdr gives each session a terminal tab. The GitHub CLI (`gh`) lets the agent read issues
+and open pull requests using your account. [pi](https://github.com/earendil-works/pi) ·
+[herdr](https://herdr.dev) · [GitHub CLI](https://cli.github.com)
+
+Sign in to a model provider in pi and check that your model appears in `pi --list-models`. Then
+sign in to GitHub with an account that can write to the repository you want to use.
 
 ```sh
 gh auth login
@@ -70,83 +24,76 @@ pi install npm:pi-superagent
 npm install -g pi-superagent
 ```
 
-Pi loads the extension in router and worker sessions. The global npm install puts the
-`superagent` command on your PATH. Use the same package version for both.
+The first install gives pi the extension. The second gives you the `superagent` command to start,
+stop and check on it. Keep the two at the same version when you update.
 
-## Run your first ticket
+## Try it on one issue
 
-Substitute the GitHub repository you want the worker to change. `init` checks the local tools
-and your GitHub access, then saves the repository in `~/.pi/superagent/config.env`.
+Choose a repository and open herdr in your terminal.
 
 ```sh
 superagent init your-org/your-repo
-herdr                      # keep it open, then use another terminal
+herdr
+```
+
+Leave herdr open. In a second terminal, start the **router**, the background session that watches
+your repository and sends work to the right agent.
+
+```sh
 superagent start
 superagent status
 ```
 
-Wait for the first GitHub poll in the **engine log** tab, then open a new issue asking for a small
-change. The first poll records existing issues as the starting point. Watch for the acknowledgement
-on your issue. The worker clones the watched repository into its own directory, switches to a ticket
-branch, and posts the pull request on the issue. Request a change on the PR to send it back to the
-worker. Merge when you are satisfied.
-
-To supply your own workspace setup, set `PI_SUPERAGENT_PREPARE`. A replacement worker keeps the same
-ticket directory. To narrow who can start work or give the router its own GitHub identity, see
-[`config.example.env`](config.example.env). Stop the router with `superagent stop`.
-
-## Watching it
-
-Everything happens in the herdr workspace `superagent`:
-
-| Tab | What it shows |
-| --- | --- |
-| `engine log` | the router's log as it happens: every poll, judgement, launch and receipt |
-| `engine` | the router itself, a pi session that stays quiet while its loop runs in the background |
-| one per ticket | that ticket's worker, live, labelled `#141 · <issue title>` |
-
-The panel at <http://127.0.0.1:8788/> answers three questions at a glance: does anything need me, what
-is running, and what did the judge decide.
-
-## Documentation
-
-| Read | When you want |
-| --- | --- |
-| [Operator guide](docs/operator-guide.md) | to ask for work, watch it, and fix what goes wrong |
-| [Architecture](docs/architecture.md) | the map: what runs, in what order, and which file owns each rule |
-| [Design decisions](docs/design-decisions.md) | the reasons, each with the failure that taught it |
-| [Formal verification](docs/formal-verification.md) | what the TLA+ specifications prove, and what they do not |
-| [Adaptation ledger](ADAPTATION.md) | how the vendored engine is bound, and how to prove it unmodified |
-
-## Repository layout
-
-| Path | What it holds |
-| --- | --- |
-| `src/core/` | the vendored engine: tickets, evaluations, assignments, the outbox queue |
-| `src/pi/extension.ts` | the router: wires the parts together and runs the loop |
-| `src/pi/source-github.ts`, `gh-api.ts` | GitHub in: issues, comments and reviews become triggers |
-| `src/pi/pulls.ts` | pull requests: bound to their ticket, followed until merged or closed |
-| `src/pi/assessor.ts`, `judge.ts` | the judge: one candidate at a time, answered through `ticket_decide` |
-| `src/pi/executor.ts`, `herdr-workers.ts` | workers: pi sessions in herdr tabs, and records that outlive the router |
-| `src/pi/worker-role.ts`, `report-tool.ts`, `workspace.ts` | inside a worker: the report tool, the guard, the workspace |
-| `src/pi/outbox.ts`, `receipts.ts` | GitHub out: what each ending says, each message posted once |
-| `src/pi/store.ts` | the engine's SQLite store |
-| `src/pi/server.ts` | the panel and its local API |
-| `scripts/superagent` | start, stop, restart and status, with exit codes a health check can read |
-| `formal/` | the TLA+ specifications |
+In herdr, find the `superagent` workspace and wait for the first GitHub poll in the **engine log**
+tab. That first look records the issues already open. Now open a new issue with a small request.
+For example, “Show the keyboard shortcut next to Export in the Help menu.”
+
+When the router accepts the request, it replies on the issue and opens a **ticket**, its record of
+the work. A **worker** is the pi session assigned to that ticket. It gets its own checkout and a
+tab labeled with the issue number. You can type into the tab, though usually a comment on the
+issue is enough. If the worker needs a decision, it asks there.
+
+A code change comes back as a pull request. Review the diff as usual. The ticket stays open while
+you discuss the change and ends when you merge or close the PR. You can also ask a question, such
+as where the shortcut is defined. For that, an answer on the issue can finish the job.
+
+## While the worker runs
+
+- **On GitHub**, reply on the issue to add a detail, or on the pull request to request a revision.
+  To stop work before there’s a PR, close the issue. Reopening it makes a fresh request.
+- **In herdr**, open the tab with the issue number to see the worker’s commands and output. The
+  **engine log** tab shows what the router picked up and which requests it accepted.
+- **In the local panel**, look under *Needs a person* to see who’s waiting for an answer. You can
+  also see running workers, queued work and recent decisions. [Open the panel](http://127.0.0.1:8788/)
+
+By default, the router listens to authors GitHub identifies as owners, organization members or
+collaborators. You can choose particular logins, give the router its own GitHub account, or supply
+a custom workspace setup. Run `superagent stop` when you want to stop the router.
+[Operator guide](docs/operator-guide.md) · [Configuration examples](config.example.env)
+
+## How it works
+
+A separate pi session called the **judge** reads a new request and decides whether there’s work to
+do. Once a ticket is open, follow-up comments go straight to its worker. The worker reports the
+outcome through a tool call, which lets the router distinguish a finished run from a question or
+a crash. The router stores the ticket on disk, so after a restart it can find the worker and pick
+up the conversation. [Architecture](docs/architecture.md) · [Design decisions](docs/design-decisions.md)
+
+The ticket engine comes from DeepSeek’s dsh-superagent-prototype. Three TLA+ models check how
+tickets, incoming messages and worker tabs behave when events arrive in different orders.
+[Upstream project](https://github.com/deepseek-ai/dsh-superagent-prototype) ·
+[Adaptation ledger](ADAPTATION.md) · [Formal verification](docs/formal-verification.md)
 
 ## Development
 
 ```sh
 npm install
-npm run check            # typecheck and the full suite: no model calls, no network
-npm run check:packed     # pack, install globally into a temporary prefix, run both halves from there
-scripts/check-formal     # model-check all three specifications (about five minutes; needs a JDK)
+npm run check            # Type-check and run the test suite
+npm run check:packed     # Install the tarball and exercise both the CLI and the pi extension
+scripts/check-formal     # Check all three models (about five minutes with a JDK)
 ```
 
-`npm publish` runs the first two first and stops on a failure.
-
-The suite clears every `PI_SUPERAGENT_*` variable before it runs (`test/setup.ts`), so no test can reach a
-live router.
+The test suite clears `PI_SUPERAGENT_*` settings to isolate its router from yours.
+Publishing runs both npm checks before uploading the package.
 
-MIT licensed. The vendored engine is MIT licensed too; see [NOTICE](NOTICE).
+Both projects use the MIT license. [Upstream attribution](NOTICE)