136 lines
6.4 KiB
Markdown
136 lines
6.4 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.
|