204 lines
12 KiB
Markdown
204 lines
12 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
# Answers to the open questions, 2026-11-10
|
|
|
|
**Where settings are set.** `Agents>agents` has a fourth tab, **settings**, which edits the
|
|
chosen agent: role, job title, model, monthly budget, heartbeat. `enter` edits the field in
|
|
place, `esc` cancels, and `p` / `P` / `w` pause, resume and wake. Each save is one
|
|
`PATCH /api/agents/{id}` merged into that agent's existing configuration, so a model change
|
|
never wipes its folder or instructions. `Project>project` shows spend and limits read-only,
|
|
because Paperclip owns them and a second editable copy is how two screens start disagreeing.
|
|
|
|
**Spend.** Read from `cost-summary` per task (`Project>costs`, `Board>board`,
|
|
`Work>work`). The monthly budget is per agent, set in `Agents>agents` settings. There is no
|
|
company-level control on any screen yet.
|
|
|
|
**Skills for sub-agents.** Not in the interface. Paperclip has the endpoints —
|
|
`GET /api/agents/{id}/skills`, `POST /api/agents/{id}/skills/sync` with `add`, `remove` or
|
|
`replace` — so a read-only skills row is cheap and a full editor is a later step. The rule
|
|
worth keeping: an agent gets the skills its job needs and no more, which the `add`/`replace`
|
|
model already expresses.
|
|
|
|
**Where work is added.** `New task>new`, which writes a Paperclip task. A second place to
|
|
write tasks (Tuxedo, a notes file, a card board) would be a second owner for the same fact
|
|
and is exactly the failure the old project had. Personal notes are different from tasks: if
|
|
they are wanted, they belong in the project's own `.harness/NOTES.md`, and Tuxedo can read
|
|
it per project without pretending to be a task board.
|
|
|
|
**`office --host` from another machine.** Not implemented, and the runbook says why:
|
|
session creation needs a real terminal, so a person creates the session
|
|
(`tuios new --host nixos-desktop "new test project"`) and then runs `bin/office <folder>`
|
|
inside it, on the machine that owns the folder. `--host` today only records the host in the
|
|
project file. Driving `bin/office` on `.27` from `.13` would need ssh plus a remote
|
|
`bin/board`, which is a deliberate later step, not an accident.
|
|
|
|
**Seeing and switching projects.** Not built. Paperclip has the list
|
|
(`GET /api/companies/{id}/projects`); what it cannot know is which folder on which machine
|
|
each one lives in. The proposal: a small local registry of adopted projects
|
|
(`~/.config/paperclip-harness/projects.toml`: project id, folder, host, session), filled by
|
|
`bin/office`, and a `Project>projects` tab that lists them and switches by writing the
|
|
project into the current folder's `.harness/harness.toml`. A project on another machine
|
|
can only be switched to if the pane can reach it, so it would be shown as `on .27`, not
|
|
offered.
|
|
|
|
**Artifacts.** Paperclip work products: an uploaded file, a pull request, a preview URL, a
|
|
commit or a branch, attached to a task by an agent. They are inspectable records of what a
|
|
task produced. Nothing shows them yet; the natural home is a `Work>artifacts` tab listing
|
|
them with their links, read from the task's work products.
|
|
|
|
**"Workspaces" in Paperclip.** Paperclip has no workspaces. It has companies, projects,
|
|
issues (tasks), agents and runs. A *workspace* is TUIOS's word for a page; a *pane* is a
|
|
terminal inside it. When Paperclip says workspace it means a project's code folder
|
|
(`currentExecutionWorkspace`), which is the git worktree a task runs in.
|
|
|
|
**Charts.** TUIOS ships `plot` (Go), `loom` and TML. Go is the better fit here because the
|
|
panels are already Go and the data is already in memory: a spend-by-day chart in
|
|
`Project>costs` is a few dozen lines against `tuios.dev/plot`, where a TML surface would be
|
|
a second language and a second round trip. Worth doing once the functional tests pass.
|
|
|
|
**Mouse-1 and Switch.** Still not installed on this machine. Unchanged from the earlier
|
|
note: they would serve cheap repeatable judgement, later, after they are installed and
|
|
measured.
|