papercliped 2.7.0 → 2.7.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.7.0",
+  "version": "2.7.1",
   "description": "Run your Paperclip from Claude: control agents, sync with them and get reports, at the access level you choose.",
   "author": {
     "name": "KpnWorld"

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## v2.7.1 — works with Paperclip 2026.1023.0
+
+- **Works with Paperclip 2026.1023.0.** Checked against a real instance: sign-in, key renewal, every tool and the plugin install. "Wake agent now" now uses Paperclip's current wake route (the old one still works there, but is a legacy alias), and the Papercliped plugin is built against the 2026.1023.0 plugin SDK. A new test pins the list of Paperclip routes the tools call, so a Paperclip release that removes one fails CI instead of failing for you.
+- **Docs:** which Paperclip versions are supported, and which Paperclip role you need (Viewer for Read only, Operator for Full control), in `docs/PAPERCLIP-COMPATIBILITY.md` and the permissions page.
+
 ## v2.7.0 — Ed25519-signed Connect account claims
 
 - **Connect claims can be signed with an Ed25519 key.** Set `CONNECT_CLAIM_ED25519_PRIVATE_KEY` (PKCS#8 PEM; `node scripts/gen-claim-key.mjs <file>` makes a pair) and optionally `CONNECT_CLAIM_KEY_ID`; Connect then verifies with the public key only and can no longer forge claims. The shared `CONNECT_CLAIM_SIGNING_KEY` still works for one more release. Nothing to do unless you run Connect claims; they stay off by default.

package/dist/tools.js

@@ -74,7 +74,8 @@ export const tools = [
         description: "Manually trigger a heartbeat so the agent starts working immediately.",
         access: "write",
         schema: z.object({ agentId: id("Agent") }),
-        run: (c, i) => c.post(`/agents/${i.agentId}/heartbeat/invoke`),
+        // /wakeup is Paperclip's current route (in every release since 2026.318); /heartbeat/invoke is its legacy alias. /wakeup needs a JSON body.
+        run: (c, i) => c.post(`/agents/${i.agentId}/wakeup`, { source: "on_demand", triggerDetail: "manual" }),
     }),
     tool({
         name: "paperclip_set_agent_budget",

package/docs/PAPERCLIP-COMPATIBILITY.md

@@ -0,0 +1,50 @@
+# Paperclip compatibility
+
+Papercliped talks to a Paperclip it does not ship, over Paperclip's REST API and its plugin system. This page says which Paperclip versions that has been checked against, how, and what to do when a new one comes out.
+
+## Supported versions
+
+| Paperclip (`paperclipai`) | Status | Checked how |
+| --- | --- | --- |
+| **2026.1023.0** (latest stable at the time of writing) | Supported, certified | A real instance (Node 24.21, embedded Postgres) ran the login flow, key renewal, every route the tools call, the plugin install and the role checks below. `test/paperclip-contract.test.ts` pins its route list. |
+| 2026.1005.0 | Supported, not run live | The same contract test passes against its OpenAPI document: every route the bridge calls exists there. |
+| 2026.1012.0 | Expected to work, not checked | Between the two above. |
+| 2026.318.0 to 2026.1001.0 | Best effort | `/agents/:id/wakeup` and `/board-api-keys` exist from 2026.318 on. Older keys never expire, so renewal is skipped. |
+| Nightly, canary, beta | Not supported | They change without notice. |
+
+Paperclip needs Node 24.11 or later (`engines` of the package). Papercliped itself does not run Paperclip, so this only matters for the person who hosts it.
+
+## What Papercliped calls
+
+- **Login:** `POST /cli-auth/challenges`, the person approves in Paperclip's own page, `GET /cli-auth/challenges/:id`, then `GET /cli-auth/me`.
+- **Key renewal:** `GET /board-api-keys` (to read this key's expiry), `POST /board-api-keys` with the old key (a new key for the same user, 30-day expiry), `POST /cli-auth/revoke-current` with the old key. Checked live on 2026.1023.0: the new key works, the old one answers 401 once revoked.
+- **Tools:** the routes in `src/tools.ts`. `paperclip_wake_agent` uses `POST /agents/:id/wakeup` with `{ source: "on_demand", triggerDetail: "manual" }`. Paperclip also serves a legacy `POST /agents/:id/heartbeat/invoke` (empty body allowed), kept only for old callers; `/wakeup` rejects a request with no JSON body with a 400.
+- **Plugin:** `GET /plugins`, `POST /plugins/install` (instance admins only, anyone else gets 403, reported as "denied"). The plugin is built against `@paperclipai/plugin-sdk` 2026.1023.0, plugin API version 1, and its manifest passes `pluginManifestV1Schema`; it was installed into a running 2026.1023.0 and reached `ready`.
+
+## Which Paperclip role the connected person needs
+
+The key Papercliped holds is the Paperclip user's own board key: it can do what that user can do in their companies, nothing is narrowed on Paperclip's side. So the role is the person's company membership. Measured on 2026.1023.0 with one key per role:
+
+| Tool | Viewer | Operator | Admin |
+| --- | --- | --- | --- |
+| List companies, agents, issues, costs, activity, approvals | yes | yes | yes |
+| Create or update issues, comment, create goals | **no (403)** | yes | yes |
+| Pause, resume, wake, set budget, terminate an agent | **no (403)** | yes | yes |
+| Install the Papercliped plugin into Paperclip | no | no | no (instance admin only) |
+
+- **Read only** access in Papercliped needs only **Viewer**.
+- **Full control** needs **Operator**. Owner and Admin add nothing the tools use (they add inviting people, approving join requests and managing permissions), so use Operator as the least-privilege role.
+- Since 2026.1023 an Operator holds 14 permission grants (it held 1): create and configure agents, create skills, manage environments, invite users, assign tasks, pipelines, and the tool grants. Papercliped's tools use none of the extra ones. If that is more than you want, narrow the member in Paperclip (`PATCH /companies/:id/members/:memberId/permissions`) or give the person Viewer and accept read only.
+- The one-click plugin install needs an **instance admin**. Anyone else installs the plugin from Paperclip's own plugin page.
+
+## Key expiry
+
+Paperclip's board keys expire after 30 days. Papercliped renews each key about a week before (see `docs/SECURITY.md` and the changelog for 2.5.1). Renewal uses the old key, so a key that has already expired (401) cannot be renewed: the person connects again. Keys on Paperclip versions that list no expiry are treated as expiring 30 days after they were issued until the first renewal check reads the real date.
+
+## When a new Paperclip comes out
+
+1. Start a throwaway instance of it (loopback, its own `PAPERCLIP_HOME`), sign up, claim the instance.
+2. `node scripts/paperclip-routes.mjs http://127.0.0.1:<port> <version>` rewrites `test/fixtures/paperclip-routes.json`.
+3. `npm test`. A failure in `test/paperclip-contract.test.ts` names the call that no longer exists.
+4. Bump `@paperclipai/plugin-sdk` in `plugin/package.json`, run the plugin's typecheck, tests and build, and install the built plugin into the instance.
+5. Update the table above and add a changelog entry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.7.0",
+  "version": "2.7.1",
   "description": "Papercliped — connect Claude, ChatGPT and any MCP app to your Paperclip: control agents, sync, report. MCP server + hosted multi-tenant OAuth bridge + public stats API.",
   "license": "MIT",
   "type": "module",

package/site/docs/permissions.md

@@ -22,6 +22,9 @@ These only ever narrow what a level allows; they never grant more than the level
 - Apps that still ask for the old "admin" level get Full control.
 - To change a level, use the [Paperclip plugin](/docs/paperclip-plugin), or disconnect the app and connect it again.
 
+## Which Paperclip role you need
+Papercliped uses your own Paperclip account, so what it can do also depends on your role in the company. **Viewer** is enough for Read only. **Operator** is enough for Full control (create and update issues, pause, resume, wake and terminate agents, set budgets). Owner and Admin add nothing Papercliped uses. Installing the plugin with one click needs an instance admin; anyone else can install it from Paperclip's plugin page. Papercliped works with Paperclip 2026.1023.0, the latest stable release, and with the releases from 2026.1005.0 on that it has been checked against.
+
 ## Disconnecting
 - Remove the connector in Claude or ChatGPT.
 - To cut access immediately, revoke the key in your Paperclip (it is named like "… (via bridge) (board)").