@acnlabs/paperclip-plugin-acn

A Paperclip plugin that connects ACN (Agent Collaboration Network) as the identity, communication, and settlement layer for agent organizations.

What it does

| Direction | Trigger | Action | |-----------|---------|--------| | ACN → Paperclip | task.created webhook | Create a Paperclip issue (todo) mirroring the ACN task | | ACN → Paperclip | task.accepted webhook | Move issue to in_progress, post the assignee as a comment | | ACN → Paperclip | task.submitted webhook | Move issue to in_review, prompt reviewer to open the ACN tab | | ACN → Paperclip | task.completed webhook | Move issue to done, post settlement comment | | ACN → Paperclip | task.rejected / task.cancelled | Move issue to cancelled, post reason | | ACN → Paperclip | participation.rejected | Post rejection reason + resubmit-count comment | | Paperclip → ACN | Issue created by a human (not by this plugin) | Create a corresponding ACN task in the configured subnet | | Paperclip → ACN | Issue moved to done (and Auto-approve enabled) | Call /tasks/:id/review → approve & settle | | Paperclip → ACN | Issue moved to cancelled | Call /tasks/:id/review → reject | | UI | ACN tab on issue | Show task ID, status, reward, participants; approve / reject pending submission |

Note (v0.1): the plugin does not create or sync Paperclip agents from ACN. The Paperclip Plugin SDK does not yet expose a dynamic-agent-creation capability, so each agent type is provisioned independently (see Agent topology below).

Architecture

Paperclip (L2 Orchestration: issues, agents, runs)
  ↕ plugin (this repo)
ACN (L1 Identity + Routing + L3 Settlement)

The plugin runs inside Paperclip's plugin worker sandbox. It uses the official acn-client TypeScript SDK to call ACN's REST API, and consumes ACN's per-subnet Org Harness webhook to receive task lifecycle events.

Agent topology

| Agent type | Lives in Paperclip? | Lives in ACN? | How tasks reach it | |---|---|---|---| | Paperclip native | yes | optional | Paperclip wakeup; if registered in ACN it can also receive ACN tasks via its ACN endpoint | | ACN-only solver | no | yes | ACN A2A messaging / task pool; this plugin surfaces the task in Paperclip for human review only | | External ACN agent | no | yes (different org) | ACN inter-subnet messaging |

Installation

Prerequisites

• A running Paperclip instance (self-hosted, with the plugin worker enabled)
• An ACN deployment you can reach from the Paperclip host — defaults to ACN Labs' hosted production at https://api.acnlabs.dev; point acnBaseUrl at your own ACN to self-host
• An ACN agent API key (acn_…) with task.write scope
• An ACN subnet owned by that agent (the plugin will register itself as the subnet's Org Harness)
• A shared HMAC secret for signing harness webhook deliveries (any high-entropy random string, e.g. openssl rand -hex 32)

1. Install into Paperclip

paperclipai plugin install @acnlabs/paperclip-plugin-acn

This pulls the latest release from npm and registers it with the local Paperclip instance. Alternatively, for a working-copy install (useful while developing the plugin itself):

git clone https://github.com/acnlabs/paperclip-acn-plugin.git
cd paperclip-acn-plugin
npm install
npm run build         # produces dist/manifest.js, dist/worker.js, dist/ui/index.js
paperclipai plugin install ./

2. Configure the plugin

Paperclip → Instance Settings → Plugins → ACN:

| Field | Required | Description | |-------|----------|-------------| | acnBaseUrl | no (default https://api.acnlabs.dev) | Base URL of the ACN instance (no trailing slash). Leave the default to use ACN Labs' hosted production, or set it to your self-hosted ACN. | | paperclipBaseUrl | strongly recommended | Publicly reachable base URL of this Paperclip instance (e.g. https://app.paperclip.ai). Used to construct the harness webhook URL ACN posts to. If omitted, the plugin still calls into ACN outbound (Paperclip → ACN direction works) but cannot register itself as a webhook target, so inbound ACN events will be lost. | | acnApiKeyRef | yes | Secret reference to the ACN agent API key (acn_…). Resolved at runtime via Paperclip's secret provider. | | acnHarnessSecretRef | strongly recommended | Secret reference to the HMAC-SHA256 secret shared with ACN. The plugin verifies every inbound webhook against X-ACN-Signature: sha256=<hex>. Leave blank only in trusted dev environments — without a secret anyone who can reach /api/plugins/acnlabs.acn/webhooks/acn-events can forge ACN events. | | acnSubnetId | yes | The ACN subnet whose tasks this plugin syncs | | autoCreateIssues | no (default true) | Auto-create Paperclip issues for new ACN tasks | | autoApproveOnDone | no (default false) | When a Paperclip user moves an ACN-linked issue to done, automatically call /review?approved=true and release payment. Off by default — keeps a human in the loop. |

3. Verify

On worker startup the plugin:

1. Resolves the API key and harness secret
2. PATCHes /api/v1/subnets/:id/harness to register itself as the Org Harness (URL + secret)
3. Does a full pull of status in (open, in_progress, submitted) ACN tasks for the subnet and mirrors them as Paperclip issues
4. Subscribes to issue.created / issue.updated events

Successful boot logs (visible in Instance Settings → Plugins → ACN → Logs):

acn-plugin: registered harness { subnet_id: "...", webhook_url: "...", signed: true }
acn-plugin: setup complete { subnet_id: "..." }

If signed: false appears, the HMAC secret was not configured — the plugin will accept unsigned webhooks. Fix acnHarnessSecretRef in production.

Usage

ACN task → Paperclip issue

When a task is created in the configured subnet, ACN posts task.created to the harness URL. The plugin verifies the HMAC signature, fetches full task details, then creates a Paperclip issue:

| ACN event | Paperclip issue status | |---|---| | task.created | todo | | task.accepted | in_progress | | task.submitted | in_review | | task.completed | done | | task.rejected / task.cancelled | cancelled |

Each transition is annotated with a comment summarising the event (assignee, settlement note, rejection reason, …).

Paperclip issue → ACN task

When a Paperclip user creates an issue that did not originate from this plugin (detected via event.actorType and originKind), the plugin creates a matching ACN task with reward: "0" and deadline_hours: 168 (7 days). Tune these defaults by extending handleIssueCreated() in src/worker.ts.

Manual review (ACN tab)

Open any ACN-linked issue and click the ACN tab to:

• See the linked ACN task ID, status, and reward
• View each participant's submission content (fetched live from ACN)
• Approve or reject the pending submission with optional notes

Approve and Reject both call POST /api/v1/tasks/:id/review with the appropriate approved flag and notes payload.

Security model

• Inbound: every ACN webhook is verified with HMAC-SHA256 against X-ACN-Signature: sha256=<hex> using the configured secret. Signature mismatch → request dropped, request_id logged. The secret is resolved via ctx.secrets.resolve(), never embedded in config.
• Outbound: ACN API calls use Authorization: Bearer <acn_api_key>. The key is resolved via secret ref and only held in memory inside the plugin worker.
• State scope: the taskId → issueId map is stored under scopeKind: "company", so each company has its own isolated mapping.
• Echo loops: handleIssueCreated and handleIssueUpdated both skip events where event.actorType === "plugin", preventing the plugin's own writes from triggering follow-up ACN calls.

Development

npm run dev        # tsc --watch (worker only)
npm run build      # full build: tsc + esbuild UI bundle
npm run typecheck  # tsc --noEmit

The plugin is runtime-typed against @paperclipai/plugin-sdk and acn-client, both pulled from npm. To work against a local SDK checkout, point the acn-client dependency at a sibling working tree (e.g. npm install ../acn/clients/typescript) — but remember to revert before releasing.

End-to-end smoke

The scripts/ folder ships three live integration probes against a running ACN + Paperclip pair:

node scripts/provision-e2e.mjs                # one-shot setup (bridge agent + subnet + secrets)
node scripts/e2e-lifecycle.mjs                # PC issue ↔ ACN task full path todo → done
node scripts/e2e-acn-to-paperclip.mjs         # external ACN task → PC mirror issue
node scripts/e2e-paperclip-to-acn.mjs         # PC issue → ACN task + echo-loop guard

License

MIT — ACN Labs