ake/paperclip
1
0
Fork 0
mirror of https://github.com/alkimake/paperclip.git synced 2026-06-16 19:00:38 +09:00
Code Issues Projects Releases Packages Wiki Activity

feat(adapters): external adapter plugin system with dynamic UI parser

Browse source 
- Plugin loader: install/reload/remove/reinstall external adapters
  from npm packages or local directories
- Plugin store persisted at ~/.paperclip/adapter-plugins.json
- Self-healing UI parser resolution with version caching
- UI: Adapter Manager page, dynamic loader, display registry
  with humanized names for unknown adapter types
- Dev watch: exclude adapter-plugins dir from tsx watcher
  to prevent mid-request server restarts during reinstall
- All consumer fallbacks use getAdapterLabel() for consistent display
- AdapterTypeDropdown uses controlled open state for proper close behavior
- Remove hermes-local from built-in UI (externalized to plugin)
- Add docs for external adapters and UI parser contract
This commit is contained in:
HenkDz 2026-03-31 20:21:13 +01:00
parent f8452a4520
commit 14d59da316
72 changed files with 4102 additions and 585 deletions
Download patch file Download diff file Expand all files Collapse all files

54
docs/adapters/overview.md
View file

@ -22,43 +22,67 @@ When a heartbeat fires, Paperclip:
| [Codex Local](/adapters/codex-local) | `codex_local` | Runs OpenAI Codex CLI locally |
| [Gemini Local](/adapters/gemini-local) | `gemini_local` | Runs Gemini CLI locally (experimental — adapter package exists, not yet in stable type enum) |
| OpenCode Local | `opencode_local` | Runs OpenCode CLI locally (multi-provider `provider/model`) |
| Hermes Local | `hermes_local` | Runs Hermes CLI locally |
| Cursor | `cursor` | Runs Cursor in background mode |
| Pi Local | `pi_local` | Runs an embedded Pi agent locally |
| OpenClaw Gateway | `openclaw_gateway` | Connects to an OpenClaw gateway endpoint |
| [Process](/adapters/process) | `process` | Executes arbitrary shell commands |
| [HTTP](/adapters/http) | `http` | Sends webhooks to external agents |
### External (plugin) adapters
These adapters ship as standalone npm packages and are installed via the plugin system:
| Adapter | Package | Type Key | Description |
|---------|---------|----------|-------------|
| Droid Local | `@henkey/droid-paperclip-adapter` | `droid_local` | Runs Factory Droid locally |
| Hermes Local | `@henkey/hermes-paperclip-adapter` | `hermes_local` | Runs Hermes CLI locally |
## External Adapters
You can build and distribute adapters as standalone packages — no changes to Paperclip's source code required. External adapters are loaded at startup via the plugin system.
```sh
# Install from npm via API
curl -X POST http://localhost:3102/api/adapters \
-d '{"packageName": "my-paperclip-adapter"}'
# Or link from a local directory
curl -X POST http://localhost:3102/api/adapters \
-d '{"localPath": "/home/user/my-adapter"}'
```
See [External Adapters](/adapters/external-adapters) for the full guide.
## Adapter Architecture
Each adapter is a package with three modules:
Each adapter is a package with modules consumed by three registries:
```
packages/adapters/<name>/
my-adapter/
src/
index.ts # Shared metadata (type, label, models)
server/
execute.ts # Core execution logic
parse.ts # Output parsing
test.ts # Environment diagnostics
ui/
parse-stdout.ts # Stdout -> transcript entries for run viewer
build-config.ts # Form values -> adapterConfig JSON
ui-parser.ts # Self-contained UI transcript parser (for external adapters)
cli/
format-event.ts # Terminal output for `paperclipai run --watch`
```
Three registries consume these modules:
| Registry | What it does |
|----------|-------------|
| **Server** | Executes agents, captures results |
| **UI** | Renders run transcripts, provides config forms |
| **CLI** | Formats terminal output for live watching |
| Registry | What it does | Source |
|----------|-------------|--------|
| **Server** | Executes agents, captures results | `createServerAdapter()` from package root |
| **UI** | Renders run transcripts, provides config forms | `ui-parser.js` (dynamic) or static import (built-in) |
| **CLI** | Formats terminal output for live watching | Static import |
## Choosing an Adapter
- **Need a coding agent?** Use `claude_local`, `codex_local`, `opencode_local`, or `hermes_local`
- **Need a coding agent?** Use `claude_local`, `codex_local`, `opencode_local`, or install `droid_local` / `hermes_local` as external plugins
- **Need to run a script or command?** Use `process`
- **Need to call an external service?** Use `http`
- **Need something custom?** [Create your own adapter](/adapters/creating-an-adapter)
- **Need something custom?** [Create your own adapter](/adapters/creating-an-adapter) or [build an external adapter plugin](/adapters/external-adapters)
## UI Parser Contract
External adapters can ship a self-contained UI parser that tells the Paperclip web UI how to render their stdout. Without it, the UI uses a generic shell parser. See the [UI Parser Contract](/adapters/adapter-ui-parser) for details.