277 lines
13 KiB
Markdown
277 lines
13 KiB
Markdown
# Paperclip API — read-only probe, 2026-11-09
|
||
|
||
Probe only: no writes, no task created, nothing in the existing projects touched. All
|
||
requests were `GET` with `Authorization: Bearer $PAPERCLIP_API_KEY` read from the
|
||
environment; the key is never printed here.
|
||
|
||
## Where it runs
|
||
|
||
- Local server: `http://127.0.0.1:3100`, pid 1588, started 2026-11-05.
|
||
From `~/.paperclip/instances/default/runtime-info.json`.
|
||
- Public URL: `https://paperclip.lab.audasmedia.com.au`.
|
||
- Postgres: `postgres://paperclip@127.0.0.1:5433/paperclip` (embedded, local).
|
||
- CLI: `paperclipai` 2026.916.1, managed install under `~/.paperclip/cli/installs`.
|
||
|
||
## Endpoints that answered
|
||
|
||
| Request | Result |
|
||
|---|---|
|
||
| `GET /api/health` | 200, 899 bytes |
|
||
| `GET /api/openapi.json` | 200, 1.1 MB — **685 paths** |
|
||
| `GET /api/agents/me` | 200 — identity, company, adapter |
|
||
| `GET /api/companies/{companyId}/issues?limit=200` | 200 — 145 issues |
|
||
| `GET /api/issues/{id}` | 200 |
|
||
| `GET /api/issues/{id}/comments` | 200 |
|
||
| `GET /api/issues/{id}/activity` | 200 |
|
||
| `GET /api/issues/{id}/cost-summary` | 200 |
|
||
| `GET /api/issues?limit=5` | 400 — "Missing companyId in path" |
|
||
|
||
## The identity the API answered as
|
||
|
||
`name: Hub`, `role: general`, `status: idle`, `adapterType: **pi_local**`,
|
||
model `omni/deepseek/deepseek-v4-flash`. So **Pi is the installed worker adapter**, not
|
||
something we must write.
|
||
|
||
## What already exists in this instance
|
||
|
||
- 10 projects, 145 issues: 139 `done`, 2 `blocked`, 2 `in_progress`, 1 `todo`, 1 `backlog`.
|
||
- Every status the four-screen TUI needs is already a first-class value.
|
||
|
||
## Endpoints the TUI and the executor will need (from the 685 in the spec)
|
||
|
||
- Read: `/api/companies/{companyId}/issues`, `/api/issues/{id}`,
|
||
`/api/issues/{id}/comments`, `/api/issues/{id}/activity`,
|
||
`/api/issues/{id}/children`, `/api/issues/{id}/diagnostics/blockers`,
|
||
`/api/issues/{id}/cost-summary`, `/api/issues/{id}/runs`,
|
||
`/api/issues/{id}/heartbeat-context`, `/api/agents/me/inbox-lite`.
|
||
- Write (later, not in this probe): `/api/issues`, `/api/issues/{id}/comments`,
|
||
`/api/issues/{id}/checkout`, `/api/issues/{id}/release`,
|
||
`/api/approvals/{id}/approve|reject|request-revision`,
|
||
`/api/cases/{caseId}/blockers`, `/api/issues/{id}/interactions/{interactionId}/respond`.
|
||
- Trees and holds: `/api/issues/{id}/tree-control/state|preview`,
|
||
`/api/issues/{id}/tree-holds`, `/api/issues/{id}/diagnostics/subtree`.
|
||
|
||
## Hypotheses
|
||
|
||
- **H1 — the control plane answers.** PASS. Health, identity, 145 issues.
|
||
- **H2 — task with a blocker via API.** NOT TESTED (a write; out of scope for a
|
||
read-only probe). Note: the two blocked issues returned `blockedByIssueIds: None`, so
|
||
the blocker relation may live in `/api/cases/{caseId}/blockers` or
|
||
`/api/issues/{id}/diagnostics/blockers` rather than on the issue row. This must be
|
||
established before trusting screen 1.
|
||
- **H3 — a comment wakes an agent.** NOT TESTED. The wake plumbing is visible in the
|
||
spec (`heartbeat-context`, `inbox-lite`, `queued-comments/steer`,
|
||
`diagnostics/wakes`), and agents run on heartbeats, so the shape is right. Unproven.
|
||
- **H4 — Pi can be a worker.** Likely PASS: `adapterType: pi_local` is the identity's
|
||
own adapter, and `Pi` is listed as a supported runtime upstream.
|
||
- **H5 — cost and run history readable.** PASS. `/api/issues/{id}/cost-summary` returns
|
||
`costCents`, `inputTokens`, `cachedInputTokens`, `outputTokens`, `runCount`.
|
||
|
||
## What this changes
|
||
|
||
The premise holds: there is a live control plane, with the statuses, threads, activity,
|
||
cost and blocker diagnostics a four-screen TUI needs, and Pi is already the adapter. The
|
||
work that remains is small and specific: prove a blocker edge by API, prove a comment
|
||
wakes an agent, and write the executor that puts a task into a git worktree, runs it and
|
||
reports back.
|
||
|
||
## Sandbox writes, 2026-11-09 (approved in advance)
|
||
|
||
Sandbox created: project **spike-2026-11-09** (`9e3f61f6-cce9-49b1-8083-3130345a04a5`),
|
||
status `backlog`, workspace `git_repo` at `/tmp/pc-sandbox` (a throwaway repo with one
|
||
commit). It is safe to delete.
|
||
|
||
Two issues created by API, status `todo`:
|
||
- `AUD-157` Spike T1 — write a file (`2ce09ea8-…`)
|
||
- `AUD-158` Spike T2 — read that file (`abc5d318-…`)
|
||
|
||
### The permission rule, learned the hard way
|
||
|
||
With `PAPERCLIP_API_KEY` (the agent `Hub`), **every write returned 403**:
|
||
|
||
> "Cross-issue writes need a run to attribute them to (Heartbeat run context). Every
|
||
> agent comment and task update is attributed to a heartbeat run so the cross-issue cap
|
||
> can be counted and the audit trail can name who acted for whom."
|
||
|
||
So an agent key is only usable **inside a heartbeat run**, with `X-Paperclip-Run-Id`.
|
||
A cockpit acting for the person must use the **user** credential
|
||
(`PAPERCLIP_BOARD_KEY`), not the agent key. That is a design fact, not an obstacle: the
|
||
TUI is the person's surface, and the audit trail correctly refuses anonymous agent
|
||
writes.
|
||
|
||
### H2 — a task with a blocker: PASS
|
||
|
||
`PATCH /api/issues/{id}` with `{"blockedByIssueIds":["<t1>"]}` → 200, and the edge reads
|
||
back. `GET /api/issues/{id}/diagnostics/blockers` returns:
|
||
|
||
```
|
||
readiness: { allBlockersDone: false, isDependencyReady: false, unresolvedBlockerCount: 1 }
|
||
blockers: [ "Spike T1 — write a file" ]
|
||
```
|
||
|
||
Note: the blocker edge is **not** on the issue list rows (`blockedByIssueIds: 0` there).
|
||
A tree view must read `diagnostics/blockers` (or the single-issue GET) per task, not the
|
||
list. That is the one place screen 1 could have lied to us.
|
||
|
||
### H3 — a comment lands on a blocked task: PASS
|
||
|
||
`POST /api/issues/{id}/comments` with the user key → 201, `authorType: user`, and the
|
||
comment is on the thread of the blocked task. What this does **not** yet prove is that a
|
||
comment *wakes* an agent: that requires a real agent on the task and a heartbeat. The
|
||
wake plumbing is present in the spec (`heartbeat-context`, `inbox-lite`,
|
||
`queued-comments/steer`, `diagnostics/wakes`); the wake itself is unproven.
|
||
|
||
### Updated verdict
|
||
|
||
H1 pass, H2 pass, H3 partly (comment lands; wake unproven), H4 likely (Pi is the
|
||
adapter), H5 pass. The remaining proof is one real agent doing one task, which is
|
||
Milestone 1 of `plan/92-paperclip-spike.md`, not a probe.
|
||
|
||
### One more thing worth knowing
|
||
|
||
A project can be created with an `executionWorkspacePolicy` whose `workspaceStrategy.type`
|
||
is `git_worktree`, with `baseRef`, `branchTemplate`, `worktreeParentDir`, provision and
|
||
teardown commands. **Paperclip may already do the worktrees we assumed we would build.**
|
||
That deserves its own probe before any executor is written.
|
||
|
||
---
|
||
|
||
# Milestone 1 measured, 2026-11-10 (writes, sandbox only)
|
||
|
||
Everything below was run with the **user key** (`PAPERCLIP_BOARD_KEY`). The key is never
|
||
printed. The sandbox is `spike-2026-11-10` and its scratch repository
|
||
`/tmp/pc-sandbox-2026-11-10`. Both are safe to delete.
|
||
|
||
## The order that works
|
||
|
||
The board guide's rule holds: never create a task and assign it in the same action. The
|
||
four calls, in order, with the result each one returned:
|
||
|
||
| Call | Result |
|
||
|---|---|
|
||
| `POST /api/companies/{company}/projects` | 201, project `17adbb47-f966-4a82-a8ef-e48c941443ea`, workspace `4d4eb32a-08a8-4e3e-88c9-2a8cedfc288b` |
|
||
| `POST /api/companies/{company}/issues` ×2 | 201, `AUD-159` `34abf83f-…`, `AUD-160` `21d1f49e-…`, both `todo`, unassigned |
|
||
| `PATCH /api/issues/AUD-160` `{"blockedByIssueIds":["34abf83f-…"]}` | 200, echoed `blockedBy` with `AUD-159`; diagnostics then said `unresolvedBlockerCount: 1` |
|
||
| `PATCH /api/issues/AUD-159` `{"assigneeAgentId":"403de1f7-…"}` | 200, `todo` |
|
||
|
||
The activity record of the assignment names the person, not an agent:
|
||
`actorType: "user"`, `authorizationReason: "allow_board_actor"`. That is the audit trail
|
||
the user key exists for.
|
||
|
||
## The wake, timed
|
||
|
||
```
|
||
00:01:24.891Z PATCH assigneeAgentId -> 200
|
||
00:01:24.937Z wake requested source=assignment reason=issue_assigned status=claimed
|
||
00:01:25.036Z run aae77e89-7059-43b4-9154-972282770212 started, issue -> in_progress
|
||
00:01:51.351Z comment posted by agent 403de1f7-…
|
||
00:01:53.153Z issue -> done
|
||
00:01:59.377Z run -> succeeded (resultJson.stopReason = "completed")
|
||
```
|
||
|
||
`GET /api/issues/AUD-159/diagnostics/wakes` returned that single wake request and the
|
||
plain-English line *"The most recent wake for AUD-159 is currently claimed for
|
||
issue_assigned."* This endpoint answers the question we used to have to guess at: it names
|
||
each wake, the run it produced, and why a wake did not happen.
|
||
|
||
H3 is now **PASS**: a real agent woke on assignment, worked, commented and closed the task
|
||
with no person in the loop and no timer.
|
||
|
||
## What the agent reported
|
||
|
||
Comment `822f2924-dd2f-4f26-9046-c7801f2196a9`, author `agent`, id `403de1f7-…`:
|
||
|
||
> Created `hello.txt` … Commit hash `b093301148b62ab0f2a34bec4f31d97a26a212e9` … Working
|
||
> directory (absolute path): `/tmp/pc-sandbox-2026-11-10` … Branch: `main`.
|
||
|
||
Checked on disk: `git log --oneline` shows `b093301 add hello.txt` on `main`, the file
|
||
holds the expected line, and `git status` is clean.
|
||
|
||
## Cost, read back
|
||
|
||
`GET /api/issues/AUD-159/cost-summary` →
|
||
`costCents: 1`, `inputTokens: 101002`, `outputTokens: 1515`, `runCount: 1`,
|
||
`runtimeMs: 34341`. The run's own `usageJson` says `costUsd: 0.00749434`.
|
||
|
||
## No worktree was created, and why
|
||
|
||
The task's `executionWorkspaceId` and `currentExecutionWorkspace` are `null`. The run
|
||
worked in the project folder on `main`, so a second task would collide rather than work on
|
||
its own copy.
|
||
|
||
Cause, measured: `GET /api/instance/settings/experimental` returns
|
||
`enableIsolatedWorkspaces: false` and `enableWorktreeRunExecution: false`. With the first
|
||
flag off, Paperclip throws away the task's workspace settings before dispatch, so the mode
|
||
resolves to the shared project folder even though the project asked for `git_worktree`.
|
||
|
||
The supporting code is in the installed server:
|
||
`dist/services/heartbeat.js` sets `issueExecutionWorkspaceSettings = null` when the flag is
|
||
off, and `dist/services/workspace-runtime.js` is where `git worktree add` would run.
|
||
Default worktree location is `<repo>/.paperclip/worktrees/<branch>`; default branch
|
||
template is `{{issue.identifier}}-{{slug}}`.
|
||
|
||
**Consequence for the plan.** The "Paperclip makes the worktree for us" assumption is
|
||
true only with an experimental instance setting switched on. Until a person turns it on,
|
||
every task shares one folder and merges happen on `main` with no branch and no review
|
||
step. That is a decision to put to the person, not a bug to work around.
|
||
|
||
## Second task left where it is
|
||
|
||
`AUD-160` stayed `todo`, unassigned, blocked by a task that is now `done`. Nothing woke,
|
||
because no agent is assigned to it. Whether the `issue_blockers_resolved` wake fires for an
|
||
assigned dependent task is still unmeasured.
|
||
|
||
---
|
||
|
||
# Worktrees switched on, measured, 2026-11-10
|
||
|
||
The first worktree attempt proved the flags, not the strategy: with
|
||
`enableIsolatedWorkspaces: false` the project's `git_worktree` policy was discarded before
|
||
dispatch. That is recorded above and is worth keeping, because it is what an operator will
|
||
see on any fresh instance.
|
||
|
||
After switching on `enableIsolatedWorkspaces` and `enableWorktreeRunExecution` (and leaving
|
||
`enableIsolatedWorkspacesByDefault` off, so the other projects are untouched), the same
|
||
project produced a real worktree on the next task:
|
||
|
||
| Fact | Value |
|
||
|---|---|
|
||
| Task | `AUD-160`, run `11a94551-dd12-4b13-92fe-835ea63d7753` |
|
||
| Workspace id | `7900dbf1-692c-4217-aebb-5d539c30aa98` |
|
||
| Mode / strategy | `isolated_workspace` / `git_worktree` |
|
||
| Branch | `AUD-160-milestone-1-t2-read-hello-txt` |
|
||
| Path | `/tmp/pc-sandbox-2026-11-10/.paperclip/worktrees/AUD-160-milestone-1-t2-read-hello-txt` |
|
||
| Base | `main` at `b093301` |
|
||
| Delivery state | `merged_by_ancestry` (the task made no commit) |
|
||
|
||
Paperclip wrote its own comment on the task, titled **Workspace Ready**, naming the
|
||
strategy, the branch and the working directory. `git worktree list` shows the new path, and
|
||
`git branch` shows the new branch. The file `hello.txt` from the first task was present in
|
||
the worktree, so the branch really was cut from the finished work.
|
||
|
||
Two consequences worth remembering:
|
||
|
||
- **Name the branch with a template.** The default is `{{issue.identifier}}-{{slug}}`;
|
||
usable placeholders include `{{issue.identifier}}`, `{{slug}}`, and the project and agent.
|
||
Without a template every worktree of the same task would land on the same name.
|
||
- **`merged_by_ancestry` is not a merge.** A task that changes nothing leaves its branch at
|
||
the base commit, and Paperclip marks it delivered because the branch adds nothing. A task
|
||
that does commit will stay `unmerged` until something merges it. That is the state the
|
||
review gate will read.
|
||
|
||
## Budgets as they stand
|
||
|
||
Read from `GET /api/companies/{companyId}/agents`:
|
||
|
||
| Agent | Monthly budget (cents) | Spent (cents) |
|
||
|---|---|---|
|
||
| Builder | 5000 | 2 |
|
||
| Chief of Staff | 5000 | 0 |
|
||
| System | 3000 | 0 |
|
||
| researcher | 2000 | 0 |
|
||
| Documenter | 2000 | 0 |
|
||
| Hub | 0 | 1 |
|
||
|
||
The company's `budgetMonthlyCents` is 0. There is no currency field anywhere in the payload:
|
||
Paperclip counts cents and does not name a currency, so "5000" is a number, not "$50 AUD".
|