diff --git a/bin/harness b/bin/harness index 49753b7..4e29747 100755 Binary files a/bin/harness and b/bin/harness differ diff --git a/bin/lib/__pycache__/tuios.cpython-314.pyc b/bin/lib/__pycache__/tuios.cpython-314.pyc index d0872bd..6160f27 100644 Binary files a/bin/lib/__pycache__/tuios.cpython-314.pyc and b/bin/lib/__pycache__/tuios.cpython-314.pyc differ diff --git a/docs/DOCMAP.md b/docs/DOCMAP.md index ac30bba..9d32cff 100644 --- a/docs/DOCMAP.md +++ b/docs/DOCMAP.md @@ -20,6 +20,7 @@ it is a pointer and should be deleted or replaced. | `docs/FALLBACK-OMA.md` | this project | what OMA provides, kept in case the pivot is reversed | | `docs/WHAT-WE-ARE-BUILDING.md` | this project | the person's own statement of the product | | `docs/UI-LAYOUT.md` | this project | what each page must show, where each fact comes from, and the three candidate layouts | +| `docs/PLAN-INTERFACE.md` | this project | the plan: Paperclip object → screen, what exists, what is missing, and in what order | ## What is not a document of this project diff --git a/docs/PLAN-INTERFACE.md b/docs/PLAN-INTERFACE.md new file mode 100644 index 0000000..1c6d8af --- /dev/null +++ b/docs/PLAN-INTERFACE.md @@ -0,0 +1,141 @@ +# The plan, and how the interface sits on Paperclip + +Written 2026-11-10, after a wrong turn: I split every workspace into three panes without +being asked, and it broke the working layout. It has been reverted. This document says what +exists, what is proposed, and which Paperclip endpoint each thing reads or writes. Nothing +here is invented: every endpoint below was called on this machine and answered. + +## What is on screen today + +Seven workspaces, one pane each: `Shell>shell`, `Board>board`, `Work>work`, `Reply>reply`, +`New task>new`, `Project>project`, `Repair>repair`. Inside a pane the program draws several +panels (Board draws three), and you switch focus with Tab. That is the state that works. + +## Paperclip's objects, and where each one is seen + +| Paperclip object | Endpoint, measured | Where it appears now | +|---|---|---| +| company | `GET /api/companies/{id}` | not shown; the id is in the project file | +| project | `GET /api/companies/{id}/projects` | `Project>project` | +| task | `GET /api/companies/{id}/issues`, `GET /api/issues/{id}` | `Board>board`, `Reply>reply` task panel | +| blockers of a task | `GET /api/issues/{id}/diagnostics/blockers` | `Board>board`, per row | +| comment thread | `GET /api/issues/{id}/comments` | `Reply>reply` | +| runs of a task | `GET /api/issues/{id}/runs` | `Work>work` | +| activity | `GET /api/issues/{id}/activity` | `Board>board` needs-you tab, `Work>work` | +| cost per task | `GET /api/issues/{id}/cost-summary` | `Board>board` detail, `Work>work` facts, `Project>project` costs | +| worktree and branch | the task's `currentExecutionWorkspace` | `Work>work` change and facts | +| agents | `GET /api/companies/{id}/agents` | `Project>project` facts and limits, by name and budget | +| **an agent's runs, company-wide** | `GET /api/companies/{id}/heartbeat-runs` | **nowhere yet** | +| **a run's log** | `GET /api/heartbeat-runs/{runId}/log` — 300 KB of JSON lines for one finished run | **nowhere yet** | +| **a run's events** | `GET /api/heartbeat-runs/{runId}/events` | **nowhere yet** | +| agent pause, resume, wake | `POST /api/agents/{id}/pause`, `/resume`, `/wakeup` | **nowhere yet** | +| agent settings | `PATCH /api/agents/{id}` — accepts `role`, `adapterConfig` (the model), `runtimeConfig` (heartbeat), `budgetMonthlyCents`, `status` | **nowhere yet** | + +So the honest answer to "where do I see the Pi agents working": **you cannot, yet.** The data +is all there and the runs are already recorded — 281 of them on this instance — but no screen +shows them. That is the largest missing piece, and it is the next workspace. + +## Missing: the Agents workspace + +This is the one the person keeps asking for and it does not exist. Proposed as one pane, the +same shape as the others, drawing three panels with tabs: + +``` +Agents>agents +╭─ agents roster runs ╮ +│ Campfire idle +│ ● Builder running AUD-163 started 14:12 1m 20s 1 cent +│ ● Hub idle last run 13:58 +│ ● Documenter idle +╰───────────────────────────╯ +``` + +- **roster** — every agent: name, state (`idle`, `running`, `needs input`, and Paperclip's + own status), current task if any, spend this month, budget. From + `GET /api/companies/{id}/agents`. +- **runs** — the company's run list, newest first: agent, task, state, what woke it, start, + duration, cost. From `GET /api/companies/{id}/heartbeat-runs` (281 today). +- **log** — the tail of the chosen run, from `GET /api/heartbeat-runs/{runId}/log`. This is + the closest thing to "watching Pi work": the log grows while the run is live, and + `lastOutputAt`/`lastOutputBytes` on the run say how fresh it is. + +Actions, all with the user key, all reversible: +- `enter` on a run → its log in the log tab. +- `p` pause, `P` resume an agent (`POST /api/agents/{id}/pause|resume`). +- `w` wake an agent (`POST /api/agents/{id}/wakeup`). +- `e` open its settings (see below). + +## Missing: working on an agent — role, model, cost + +Paperclip owns these, so the interface edits Paperclip, never a local file. One more panel, +`Agents>settings`, or a tab inside `Agents>agents`: + +| Field | Paperclip field | Endpoint | +|---|---|---| +| name and job title | `name`, `title` | `PATCH /api/agents/{id}` | +| role | `role` | same | +| who it reports to | `reportsTo` | same | +| model (the LLM) | `adapterConfig.model` | same, with `replaceAdapterConfig` care | +| heartbeat on/off, concurrency | `runtimeConfig.heartbeat` | same | +| monthly budget | `budgetMonthlyCents` | same | +| pause / resume | `POST /api/agents/{id}/pause`, `/resume` | separate calls | + +Two rules that fall out of this and are not negotiable: a change to a model applies to that +agent's **next** run, never to one in flight; and a budget change is recorded with who +changed it, because Paperclip's audit trail is the only record we have. + +## Tool panels: Lazygit, Hunk, a shell, the review + +Both are installed on this machine and I verified the paths: +`/run/current-system/sw/bin/lazygit` and `/etc/profiles/per-user/sam/bin/hunk`. + +They are **not** to be reimplemented. The proposal is one key in `Work>work`: + +- `t` opens a chooser: `shell · lazygit · hunk · git log · ocr`. +- The chosen tool opens as a pane **in the current workspace**, beside the panel you were + reading, and takes focus. +- `q` or `esc` closes it and focus returns exactly where it was. +- Nothing is created until you ask, so the layout stays as it is today. + +This is the answer to "I thought we had Lazygit and Hunk": they are installed, they are not +wired in, and wiring them in is one pane-opener plus a key. + +## The review: ocr is installed and has already run + +`ocr` is at `/home/sam/.local/bin/ocr`, version `open-code-review v1.13.6`. It is in the +project's `bin/merge` and `bin/review`, and it has blocked a real merge: on `AUD-165` it +reported a critical finding (`rm -rf "$HOME/tmp"` deleting `/tmp` when `HOME` is empty) and +the merge was refused. The Repair screen once said "not on the path" because a pane started +by TUIOS gets a smaller PATH than a shell; that was fixed by looking in the usual places. + +Where it belongs in the interface: a **review panel inside `Work>work`**, showing the last +verdict for the chosen task, its findings, and the blocking ones in red. The merge stays a +command (`bin/merge`), because a merge is a decision with a lock, not a keystroke. + +## Mouse-1 and Switch + +Measured just now: **not installed** — no `mouse`, `mouse1` or `switch` binary on this +machine, and nothing obviously serving them locally. So nothing can be built on them yet +without adding software first. + +Where they would fit if added: Mouse-1 is a small probability model that answers typed +questions; Switch turns a state into those questions. The honest use in this factory is +**routing and judgement that must be cheap and repeatable** — "is this task ready", "does +this comment answer the question", "which agent should take this" — rather than prose +generation. That is a later milestone, after agents and the review panel, and it needs a +decision about installing both, plus a measurement of whether they are better than the +existing cheap model already configured for agents (`omni/deepseek/deepseek-v4-flash`). + +## The order I propose + +1. **Agents workspace** — roster, runs, log. This is the missing view of Pi working, and it + is read-only, so it cannot break anything. +2. **Agent settings** — role, model, budget, pause/resume. First write surface aimed at + agents rather than tasks. +3. **Tool panels** — `t` opens Lazygit, Hunk, a shell, `ocr` in the current workspace. +4. **Review panel** in `Work>work` — the last verdict and its findings, beside the diff. +5. **Mouse-1 / Switch** — only after the above, and only after they are installed and + measured. + +Each of the first four is one pane, one program, no change to the working layout. Nothing in +this list requires splitting workspaces again.