f85d369bfc
- feat(FN-2706): complete Step 6 — document Paperclip REST runtime behavior - test(FN-2706): cover getAgentIdentity success and request payload assertions - fix(FN-2706): align promptWithFallback signature with runtime contract - fix(FN-2706): add session dispose compatibility for engine callers - fix(FN-2706): refine Paperclip API client error and config handling - test(FN-2706): complete Step 4 — cover paperclip api client and adapter flow - feat(FN-2706): complete Step 3 — wire plugin settings and remove engine guard - feat(FN-2706): complete Step 2 — rewrite paperclip runtime adapter - fix(FN-2706): restore compatibility exports during runtime migration - feat(FN-2706): complete Step 1 — add Paperclip REST client
76 lines
2.4 KiB
Markdown
76 lines
2.4 KiB
Markdown
# Paperclip Runtime Plugin
|
|
|
|
`fusion-plugin-paperclip-runtime` provides the `paperclip` runtime for Fusion agents by calling a running **Paperclip REST API** instance.
|
|
|
|
> This plugin no longer delegates to Fusion's internal `@fusion/engine` pi runtime.
|
|
|
|
## Runtime Identity
|
|
|
|
- **Plugin ID:** `fusion-plugin-paperclip-runtime`
|
|
- **Runtime ID:** `paperclip`
|
|
- **Runtime Name:** `Paperclip Runtime`
|
|
|
|
## Prerequisites
|
|
|
|
1. Paperclip is installed and running (default URL: `http://localhost:3100`)
|
|
2. Fusion plugin installed:
|
|
|
|
```bash
|
|
fn plugin install ./plugins/fusion-plugin-paperclip-runtime
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The runtime resolves configuration in this priority order:
|
|
|
|
1. Plugin settings (`ctx.settings`)
|
|
2. Environment variables
|
|
3. Defaults
|
|
|
|
| Setting | Env Var | Required | Default |
|
|
|---|---|---:|---|
|
|
| `apiUrl` | `PAPERCLIP_API_URL` | No | `http://localhost:3100` |
|
|
| `apiKey` | `PAPERCLIP_API_KEY` | No | `undefined` |
|
|
| `agentId` | `PAPERCLIP_AGENT_ID` | Yes (for session create) | `undefined` |
|
|
| `companyId` | `PAPERCLIP_COMPANY_ID` | Yes (for session create) | `undefined` |
|
|
|
|
### Authentication Modes
|
|
|
|
- **Bearer token mode:** set `apiKey` / `PAPERCLIP_API_KEY` and requests include `Authorization: Bearer <token>`
|
|
- **Local trusted mode:** leave `apiKey` unset; plugin probes `/api/health` without auth and proceeds when allowed by Paperclip deployment mode
|
|
|
|
## How Runtime Execution Works
|
|
|
|
For each prompt, the runtime adapter performs:
|
|
|
|
1. `POST /api/companies/{companyId}/issues` (creates issue in `backlog`, assigned to `agentId`)
|
|
2. `POST /api/issues/{issueId}/checkout` (atomic claim; 409 conflicts are logged and execution continues)
|
|
3. `POST /api/agents/{agentId}/heartbeat/invoke` (async agent execution)
|
|
4. Polls `GET /api/issues/{issueId}` with exponential backoff (2s → 4s → 8s → 10s cap, 120s timeout)
|
|
5. Reads output from `GET /api/issues/{issueId}/comments`
|
|
6. Emits text/thinking/tool callbacks back to Fusion runtime consumers
|
|
|
|
The runtime uses Paperclip as the orchestration engine; Fusion receives summarized output via issue comments.
|
|
|
|
## Runtime Selection in Fusion
|
|
|
|
Configure an agent with runtime hint `paperclip`:
|
|
|
|
```json
|
|
{
|
|
"runtimeConfig": {
|
|
"runtimeHint": "paperclip"
|
|
}
|
|
}
|
|
```
|
|
|
|
Fusion runtime resolution still falls back to default `pi` runtime if plugin runtime resolution fails.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
cd plugins/fusion-plugin-paperclip-runtime
|
|
pnpm test
|
|
pnpm build
|
|
```
|