diff --git a/AGENTS.md b/AGENTS.md index f94bbf4..298f9c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,14 +61,17 @@ this per task. `docs/PAPERCLIP-API-NOTES.md` has the measured response. Only the first item of `CHECKLIST.md`. One task, really run, with no interface. -1. The sandbox project `spike-2026-11-09` already has two tasks: `AUD-157` and `AUD-158`, - the second blocked by the first. Safe to use or delete. -2. Assign the first task to the Pi agent and see whether a heartbeat picks it up. **This - is unproven.** If assignment does not wake an agent, write down exactly what happened; - do not build a workaround yet. -3. Watch the status change, read the comment the agent writes, read the cost, and find the +1. Read `docs/ENVIRONMENT-FACTS.md` first. It has the company id, the agent ids, the fact + that Go is not installed, and the sandbox project's state. +2. Make a fresh sandbox project with the payload in `docs/PAPERCLIP-API-NOTES.md`, or reuse + the archived one. Assign one task to `Builder` (`403de1f7-…`). +3. Trigger the wake with `POST /api/agents/{id}/heartbeat/invoke`, then read + `GET /api/issues/{id}/runs` and `.../activity`. **Whether a heartbeat wakes Pi is + unproven.** If no run starts, write down what the API said and stop; do not build a + workaround. +4. Watch the status change, read the comment the agent writes, read the cost, and find the worktree Paperclip created. -4. Report what you saw, with the commands and the responses. +5. Report what you saw, with the commands and the responses. Do not start the Go program until that passes. diff --git a/CHECKLIST.md b/CHECKLIST.md index b34a1af..c643fee 100644 --- a/CHECKLIST.md +++ b/CHECKLIST.md @@ -10,8 +10,9 @@ Tick each line. Nothing after the first unchecked line should be started early. ## Milestone 1 — one task, really run (no interface) -- [ ] Read the sandbox from `docs/PAPERCLIP-API-NOTES.md`; it has two tasks, the second blocked by the first. -- [ ] Give the first task to the Pi agent on the task (assign it) and let a heartbeat run it. +- [ ] Read `docs/ENVIRONMENT-FACTS.md` for the company id, agent ids and toolchain facts. +- [ ] Make a sandbox project (payload in `docs/PAPERCLIP-API-NOTES.md`) with two tasks, the second blocked by the first. +- [ ] Assign the first task to `Builder` and force a wake with `POST /api/agents/{id}/heartbeat/invoke`. **Unproven** — if no run appears, record the response and stop. - [ ] Watch: the task goes `todo` → `in_progress` → `done`. - [ ] Confirm a comment written by Pi holds what it did. - [ ] Confirm the cost appears: `GET /api/issues/{id}/cost-summary`. diff --git a/README.md b/README.md index 50cc0b2..8efc4c0 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ If you are the person: read these in order: 2. `docs/PLAN.md` — the plan: the four screens, the milestones, what is Paperclip's job and what is ours. 3. `docs/PAPERCLIP-API-NOTES.md` — what we measured against your running Paperclip, with the endpoint and the response. 4. `CHECKLIST.md` — the exact steps for the next session, in order, with boxes to tick. +5. `docs/ENVIRONMENT-FACTS.md` — the ids, the installed tools, and the one step that is + still unproven. ## The one-line version @@ -23,7 +25,8 @@ Nothing else. - Paperclip server running locally on `http://127.0.0.1:3100` (it is; 685 endpoints). - `PAPERCLIP_BOARD_KEY` in the environment — the **user** key. The terminal program uses this one. An agent key cannot write outside a heartbeat run. -- Go toolchain, for the terminal program. +- Go toolchain — **not installed yet**; add `go` to `/etc/nixos/configuration.nix` before + Milestone 2. See `docs/ENVIRONMENT-FACTS.md`. - Pi, which is already the worker adapter on your Paperclip agent. ## Rules for this project diff --git a/docs/ENVIRONMENT-FACTS.md b/docs/ENVIRONMENT-FACTS.md new file mode 100644 index 0000000..b82c9a0 --- /dev/null +++ b/docs/ENVIRONMENT-FACTS.md @@ -0,0 +1,62 @@ +# Facts about this machine, checked 2026-11-09 + +Everything here was measured with a command. Anything not measured is marked unproven. + +## Paperclip + +- Running locally: `http://127.0.0.1:3100`. Public UI: `https://paperclip.lab.audasmedia.com.au`. +- Company: `d4921013-e5da-4d88-8016-57d5746e2d03` +- Agents, all running the Pi adapter (`pi_local`), all idle: + - `Hub` — `108c6220-c9e1-4b62-9e0a-6a763e0d28fd` (this is the identity of `PAPERCLIP_API_KEY`) + - `Builder` — `403de1f7-645c-4d35-bc7e-19b01d77bacc` + - `Chief of Staff` — `232f1f9e-bac0-4185-8a0e-eddbead33e04` + - `Documenter` — `706ffc88-120f-46c4-a5d9-ffa12e2ad5f0` + - `researcher` — `a6a2c0ee-570e-4f89-a977-83136b534a2f` + - `System` — `fe7a1881-1df9-481b-af74-87292fef288c` +- Writes need the user key: `PAPERCLIP_BOARD_KEY`. The agent key `PAPERCLIP_API_KEY` is + refused with 403 outside a heartbeat run. +- Blockers live at `GET /api/issues/{id}/diagnostics/blockers`, **not** on the task list. + +## The sandbox project + +- `spike-2026-11-09` is **archived**: status `cancelled`, renamed + `spike-2026-11-09 (deleted)`, id `9e3f61f6-cce9-49b1-8083-3130345a04a5`. +- `DELETE /api/projects/{id}` returned 500, so it was archived instead. Its two tasks + (`AUD-157`, `AUD-158`) remain inside the archived project. **Deleting an archived project + is still untested.** +- Its scratch repo `/tmp/pc-sandbox` was removed. +- To make a fresh sandbox, use the payload recorded in `PAPERCLIP-API-NOTES.md`: + `POST /api/companies/{companyId}/projects` with `name`, `status: "backlog"` and + `workspace: { name, sourceType: "git_repo", cwd, isPrimary: true }`. + +## The unproven step: does a heartbeat wake an agent? + +Measured: a task can be created, given a blocker, and commented on. **Not** measured: that +assigning a task causes Pi to wake and work. + +The endpoint that should start it exists: + +``` +POST /api/agents/{id}/heartbeat/invoke (empty body) +``` + +Test in this order, and write down the response at each step: + +1. Assign a task: `PATCH /api/issues/{id}` with `{"assigneeAgentId":""}`. +2. Either wait for a scheduled heartbeat, or force one: + `POST /api/agents/{agentId}/heartbeat/invoke`. +3. Read `GET /api/issues/{id}/runs` and `GET /api/issues/{id}/activity` to see whether a + run started. +4. If no run appears, the wake needs something we have not configured (a routine, a + schedule, or a wake trigger). Record the facts; do not build a workaround. + +## Toolchain + +- **Go is not installed on this machine.** `go version` → not found. The terminal program + needs it. Under Nix, add `go` to `/etc/nixos/configuration.nix` and rebuild; do not + install it by hand. + +## The new repository + +- Local git repo only, one commit, no remote. It is not on Gitea. Push it somewhere before + relying on it, or accept that only this machine has it.