sam/paperclip-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Advice: how Pi agent configuration actually resolves under Paperclip, and what history is available

Browse Source
This commit is contained in:
Sam
2026-11-11 08:03:00 +11:00
parent 3e90ca82ab
commit 77014d035b
4 changed files with 400 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
.pi/memory-vault/packs/paperclip-harness/20-context/ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt.md Normal file
View File

@@ -0,0 +1,103 @@
---
type: context
id: context.paperclip-harness.ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt
title: ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-10
tags:
- pack/paperclip-harness
- agent-memory/context
- autolearn
- rich-discovery
- repo/ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt
---
# ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt
## Rich discovery update (2026-11-10 10:48:39)
Ready for tomorrow's tests. Everything is running and rebuilt.
## `t` in Board>board — it was genuinely broken
Two separate faults. First, the earlier build had failed silently (a syntax error I introduced in `groupHeading`), so the pane you looked at was an old binary. Second, and the real one: the key handler set the flag but **the view never drew the chooser** — my patch missed because `Board>board` had no single-panel view to anchor to. Your keypress opened a chooser that was never rendered, so it looked dead.
Fixed and verified:
```
╭─ open a tool pane here ──────────────────────────────·focus· ╮
│ ▸ shell a prompt in the project folder │
│ lazygit branches, commits, staging, history │
│ hunk a change read as a review │
│ yazi files │
│ nvim editing one file │
│ fzf picking anything │
│ ocr the review of the current change │
```
One thing to know: TUIOS also binds `t` in **window management mode** (toggle tiling, new window). It reaches the program only while the pane is in terminal mode — which it is whenever you are typing in it. If `t` ever seems dead, press `i` or Enter to enter terminal mode.
## What Shell>shell is for
It is not a screen of the factory. Three reasons it exists:
1. Some things are faster typed than clicked, and a prompt in the project folder is the shortest path to any of them.
2. **Every workspace needs one pane that never exits.** TUIOS deletes a workspace whose last pane closes and renumbers the rest — the failure that lost the previous project's layout twice. Shell is that pane.
3. It is where you go when a panel does not cover what you need, without leaving the project.
Nothing in it but your shell, in the project folder, so it can never be a second copy of a fact.
## Project>project overview — delivered
New first tab, from `GET /api/companies/{id}/dashboard` (1.8 KB, one call):
```
AGENTS────────────────────────────────────────────────────────────
6 active 0 running 0 paused 0 error
TASKS─────────────────────────────────────────────────────────────
8 open 0 in progress 4 blocked 147 done
MONEY, THIS MONTH──────────────────────────────────────────────────
11 cents spent no company budget set
0 pending approvals
RUNS, LAST TWO WEEKS──────────────────────────────────────────────
▅▅▁▁▁▁▁▁▁▁▁▁▁█
2026-10-28 → 2026-11-10 one bar per day, taller is more runs
```
The sparkline is drawn in Go with block characters — no chart library, no second language. Budget incidents appear only when there are any.
## Docs updated
- `docs/WORKSPACES.md` — a section explaining Shell honestly, and `Project>project` now described as overview · facts · costs · settings.
- `README.md` — the tab list, the Shell line, and the note about `t` in window mode.
- `docs/PLAN-INTERFACE.md` — yesterday's findings: per-agent skills API, the three memory systems, the MOUSE-1 policy from the old project, the old `office` scaffold gap, and the dashboard endpoint.
## State for tomorrow
```
Shell 1 · Board 1 · Work 1 · Agents 1 · Reply 1 · New task 1 · Project 1 · Repair 1
```
All seven programs drawing, `Work>work` and `Reply>reply` following `AUD-165`, `Agents>agents` showing the roster. Committed as `3e90ca8`.
The functional test list I proposed is in the previous message — create, assign, watch in `Agents>agents`, read the diff, merge, `R` rebuild, change a model. `R` in `Repair>repair` rebuilds everything if a pane looks wrong after the rebuilds I did tonight.
## Evidence
- Confidence: 84%
- Reason: Update component/repository context with detailed discovered structure and configuration
## Related
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
## Related learned memories <!-- same-turn-2026-11-10 10:48:39 -->
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-ready-for-tomorrow-s-tests-everything-is-runn|Rich discovery: ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt 2026-11-10 10:48:39]]
- context: [[packs/paperclip-harness/20-context/ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt|ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt repository structure and configuration patterns]]

87
.pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md
View File

@@ -1489,3 +1489,90 @@ I am ready for the task you are about to deliver; nothing in the tree is half-ch
- context: [[packs/paperclip-harness/20-context/paperclip-tuios-harness-sam-s-coding-harness-office-board-wo|Paperclip-TUIOS harness (sam's coding harness: office/board/work screens)]]
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-paperclipai-2026-11-10-10-01-16|Rich discovery: paperclipai 2026-11-10 10:01:16]]
- context: [[packs/paperclip-harness/20-context/home|paperclipai]]
---
## Update (2026-11-10 10:48:39)
## Structural/configuration observations (2026-11-10 10:48:39)
Ready for tomorrow's tests. Everything is running and rebuilt.
## `t` in Board>board — it was genuinely broken
Two separate faults. First, the earlier build had failed silently (a syntax error I introduced in `groupHeading`), so the pane you looked at was an old binary. Second, and the real one: the key handler set the flag but **the view never drew the chooser** — my patch missed because `Board>board` had no single-panel view to anchor to. Your keypress opened a chooser that was never rendered, so it looked dead.
Fixed and verified:
```
╭─ open a tool pane here ──────────────────────────────·focus· ╮
│ ▸ shell a prompt in the project folder │
│ lazygit branches, commits, staging, history │
│ hunk a change read as a review │
│ yazi files │
│ nvim editing one file │
│ fzf picking anything │
│ ocr the review of the current change │
```
One thing to know: TUIOS also binds `t` in **window management mode** (toggle tiling, new window). It reaches the program only while the pane is in terminal mode — which it is whenever you are typing in it. If `t` ever seems dead, press `i` or Enter to enter terminal mode.
## What Shell>shell is for
It is not a screen of the factory. Three reasons it exists:
1. Some things are faster typed than clicked, and a prompt in the project folder is the shortest path to any of them.
2. **Every workspace needs one pane that never exits.** TUIOS deletes a workspace whose last pane closes and renumbers the rest — the failure that lost the previous project's layout twice. Shell is that pane.
3. It is where you go when a panel does not cover what you need, without leaving the project.
Nothing in it but your shell, in the project folder, so it can never be a second copy of a fact.
## Project>project overview — delivered
New first tab, from `GET /api/companies/{id}/dashboard` (1.8 KB, one call):
```
AGENTS────────────────────────────────────────────────────────────
6 active 0 running 0 paused 0 error
TASKS─────────────────────────────────────────────────────────────
8 open 0 in progress 4 blocked 147 done
MONEY, THIS MONTH──────────────────────────────────────────────────
11 cents spent no company budget set
0 pending approvals
RUNS, LAST TWO WEEKS──────────────────────────────────────────────
▅▅▁▁▁▁▁▁▁▁▁▁▁█
2026-10-28 → 2026-11-10 one bar per day, taller is more runs
```
The sparkline is drawn in Go with block characters — no chart library, no second language. Budget incidents appear only when there are any.
## Docs updated
- `docs/WORKSPACES.md` — a section explaining Shell honestly, and `Project>project` now described as overview · facts · costs · settings.
- `README.md` — the tab list, the Shell line, and the note about `t` in window mode.
- `docs/PLAN-INTERFACE.md` — yesterday's findings: per-agent skills API, the three memory systems, the MOUSE-1 policy from the old project, the old `office` scaffold gap, and the dashboard endpoint.
## State for tomorrow
```
Shell 1 · Board 1 · Work 1 · Agents 1 · Reply 1 · New task 1 · Project 1 · Repair 1
```
All seven programs drawing, `Work>work` and `Reply>reply` following `AUD-165`, `Agents>agents` showing the roster. Committed as `3e90ca8`.
The functional test list I proposed is in the previous message — create, assign, watch in `Agents>agents`, read the diff, merge, `R` rebuild, change a model. `R` in `Repair>repair` rebuilds everything if a pane looks wrong after the rebuilds I did tonight.
## Evidence
- Confidence: 82%
- Reason: Captured factual repo structure/configuration patterns from rich discovery
## Related learned memories <!-- same-turn-2026-11-10 10:48:39 -->
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-ready-for-tomorrow-s-tests-everything-is-runn|Rich discovery: ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt 2026-11-10 10:48:39]]
- context: [[packs/paperclip-harness/20-context/ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt|ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt repository structure and configuration patterns]]

106
.pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-ready-for-tomorrow-s-tests-everything-is-runn.md Normal file
View File

@@ -0,0 +1,106 @@
---
type: session
id: session.paperclip-harness.rich-discovery-ready-for-tomorrow-s-tests-everything-is-runn
title: Rich discovery: ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt 2026-11-10 10:48:39
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-10
tags:
- pack/paperclip-harness
- agent-memory/session
- autolearn
- rich-discovery
- repo/ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt
---
# Rich discovery: ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt 2026-11-10 10:48:39
Sanitized rich discovery snapshot captured automatically from the completed turn.
## Final answer snapshot
Ready for tomorrow's tests. Everything is running and rebuilt.
## `t` in Board>board — it was genuinely broken
Two separate faults. First, the earlier build had failed silently (a syntax error I introduced in `groupHeading`), so the pane you looked at was an old binary. Second, and the real one: the key handler set the flag but **the view never drew the chooser** — my patch missed because `Board>board` had no single-panel view to anchor to. Your keypress opened a chooser that was never rendered, so it looked dead.
Fixed and verified:
```
╭─ open a tool pane here ──────────────────────────────·focus· ╮
│ ▸ shell a prompt in the project folder │
│ lazygit branches, commits, staging, history │
│ hunk a change read as a review │
│ yazi files │
│ nvim editing one file │
│ fzf picking anything │
│ ocr the review of the current change │
```
One thing to know: TUIOS also binds `t` in **window management mode** (toggle tiling, new window). It reaches the program only while the pane is in terminal mode — which it is whenever you are typing in it. If `t` ever seems dead, press `i` or Enter to enter terminal mode.
## What Shell>shell is for
It is not a screen of the factory. Three reasons it exists:
1. Some things are faster typed than clicked, and a prompt in the project folder is the shortest path to any of them.
2. **Every workspace needs one pane that never exits.** TUIOS deletes a workspace whose last pane closes and renumbers the rest — the failure that lost the previous project's layout twice. Shell is that pane.
3. It is where you go when a panel does not cover what you need, without leaving the project.
Nothing in it but your shell, in the project folder, so it can never be a second copy of a fact.
## Project>project overview — delivered
New first tab, from `GET /api/companies/{id}/dashboard` (1.8 KB, one call):
```
AGENTS────────────────────────────────────────────────────────────
6 active 0 running 0 paused 0 error
TASKS─────────────────────────────────────────────────────────────
8 open 0 in progress 4 blocked 147 done
MONEY, THIS MONTH──────────────────────────────────────────────────
11 cents spent no company budget set
0 pending approvals
RUNS, LAST TWO WEEKS──────────────────────────────────────────────
▅▅▁▁▁▁▁▁▁▁▁▁▁█
2026-10-28 → 2026-11-10 one bar per day, taller is more runs
```
The sparkline is drawn in Go with block characters — no chart library, no second language. Budget incidents appear only when there are any.
## Docs updated
- `docs/WORKSPACES.md` — a section explaining Shell honestly, and `Project>project` now described as overview · facts · costs · settings.
- `README.md` — the tab list, the Shell line, and the note about `t` in window mode.
- `docs/PLAN-INTERFACE.md` — yesterday's findings: per-agent skills API, the three memory systems, the MOUSE-1 policy from the old project, the old `office` scaffold gap, and the dashboard endpoint.
## State for tomorrow
```
Shell 1 · Board 1 · Work 1 · Agents 1 · Reply 1 · New task 1 · Project 1 · Repair 1
```
All seven programs drawing, `Work>work` and `Reply>reply` following `AUD-165`, `Agents>agents` showing the roster. Committed as `3e90ca8`.
The functional test list I proposed is in the previous message — create, assign, watch in `Agents>agents`, read the diff, merge, `R` rebuild, change a model. `R` in `Repair>repair` rebuilds everything if a pane looks wrong after the rebuilds I did tonight.
## Evidence
- Confidence: 86%
- Reason: Preserve full sanitized discovery detail from a rich investigation turn
## Related
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
## Related learned memories <!-- same-turn-2026-11-10 10:48:39 -->
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-ready-for-tomorrow-s-tests-everything-is-runn|Rich discovery: ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt 2026-11-10 10:48:39]]
- context: [[packs/paperclip-harness/20-context/ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt|ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|ready-for-tomorrow-s-tests-everything-is-running-and-rebuilt repository structure and configuration patterns]]

104
docs/PLAN-INTERFACE.md
View File

@@ -310,3 +310,107 @@ Go with `tuios.dev/plot` rather than embedding Paperclip's web dashboard.
## Not doing
Artifacts, as instructed. Nothing about them will be added.
---
# Pi agents: how their configuration actually resolves
Advice only — nothing here was built. Every fact below was read from the installed code, the
config files, or the API on this machine.
## Your picker, and what it really writes
`pi-config` is an extension with five commands: `/config-add`, `/config-remove`,
`/config-list`, `/config-show`, `/config-setup`. `picker.ts` is the overlay — a filtered list
of `~/.agents/skills` and `~/.agents/extensions` showing which are active in the project and
which are active globally. The commands write **JSON**, at:
```
<project>/.pi/settings.json ← project settings (the picker's "-l" mode)
~/.pi/agent/settings.json ← global settings
```
and the shape they manipulate is a `packages` array of sources and filters:
```json
{"packages": [
"npm:pi-memctx",
{"source": "git:https://gitea.lab.audasmedia.com.au/sam/pi-config",
"extensions": ["extensions/pi-config/index.ts", "extensions/tavily-search/index.ts"]},
{"source": "/home/sam/.agents", "skills": ["nixos-workflow"], "extensions": []}
]}
```
So yes: this is a stable JSON contract, and anything that can write a file can formulate an
agent's context the way the picker does. The question is not *whether* it can be written, but
*which one Pi actually reads on a Paperclip run*.
## What Pi reads, in order
From Pi's own documentation:
- global: `~/.pi/agent/skills/`, `~/.agents/skills/`
- **project, only after the project is trusted**: `.pi/skills/`, `.agents/skills/` in the
working directory and its ancestors up to the git root
- packages and the settings `skills` array
- command line: `--skill <path>`, additive even with `--no-skills`
Settings merge the same way: user settings, then `<cwd>/.pi/settings.json`.
## What Paperclip actually runs
From `@paperclipai/adapter-pi-local`, a run is:
```
pi --mode json
--append-system-prompt <rendered system prompt>
--provider <p> --model <m> --thinking <t>
--tools read,bash,edit,write,grep,find,ls
--session /home/sam/.pi/paperclips/<timestamp>-<agentId>.jsonl
--skill <a directory Paperclip builds from that agent's desired skills>
```
and before the run it symlinks the agent's desired skills into `~/.pi/agent/skills/<runtimeName>`.
Four consequences, and they matter:
1. **Skills are already per agent** — `desiredSkills` plus `POST /api/agents/{id}/skills/sync`.
That is the supported lever, and it is what the `--skill` directory is built from.
2. **The isolation is not complete.** Injected skills are symlinked into the *shared* global
directory and are not removed when another agent runs, and Paperclip does not pass
`--no-skills`. So a skill an agent once had can remain visible to another agent.
3. **The tool list is fixed** at `read,bash,edit,write,grep,find,ls`. An agent cannot gain a
tool by being given an extension unless the adapter is changed.
4. **Project-local `.pi/settings.json` is unlikely to be honoured for Paperclip runs.** Pi only
loads project settings from a trusted path. `~/.pi/agent/trust.json` holds 14 entries and none
of them is a Paperclip worktree or `~/paperclip-agents`. Worse, a worktree path changes with
every task (`…/worktrees/AUD-165-…`), so there is nothing stable to trust.
## So what is the honest advice
- **Agent identity, instructions, model, budget, and skills: Paperclip.** Those are per-agent
already and they are what a run uses. The instructions bundle at
`~/.paperclip/instances/default/companies/<co>/agents/<id>/instructions/AGENTS.md` is the
real per-agent context control, and it is editable through the API.
- **Extensions: one global set, not per agent.** There is no per-agent extension mechanism in
this adapter. Pretending otherwise would produce agents whose behaviour depends on which one
ran last.
- **Folder-level cleverness: keep out of the critical path.** Writing `.pi/settings.json` into a
project is useful for *you* when you open Pi in that folder by hand; it is not reliable
inside a Paperclip run, because of trust and because worktrees are new paths each time.
- **If per-agent extensions are genuinely wanted**, the change is in the adapter: pass a
per-agent config directory or `--no-skills` plus an explicit set, and remove stale links.
That is a Paperclip feature, not something our terminal can arrange from outside.
## History: yes, and it is richer than the run log
- `~/.pi/paperclips/*.jsonl` — **178 files** on this machine, one per run, named
`<timestamp>-<agentId>.jsonl`, and each is the full conversation (session start, model
changes, messages).
- `GET /api/agents/{id}/task-sessions` — maps a task to its session file and working directory.
- `GET /api/heartbeat-runs/{runId}/log` — the run log already shown in `Agents>agents`.
- `GET /api/agents/{id}/runtime-state` — the agent's current runtime state.
A history panel is therefore feasible without new plumbing: list an agent's sessions from
`task-sessions`, open one, and render the JSONL transcript. That is the natural next panel
after the functional tests, and it is read-only.