Paperclip facade adapters (Phantom Agent) — consolidated package

One published npm package implementing all four Phantom-facade runtimes Paperclip can install, each as its own exports subpath:

| Runtime | Adapter type | Subpath | |---------|-------------|---------| | Claude Code (Phantom Agent) | claude_code_phantom_agent | ./claude-code | | Codex (Phantom Agent) | codex_phantom_agent | ./codex | | Cursor (Phantom Agent) | cursor_phantom_agent | ./cursor | | Hermes (Phantom Agent) | hermes_phantom_agent | ./hermes |

Each subpath is a thin, ~11-line facade — all real execution/receipt/billing/error-handling logic lives in @phantomagent/adapter-core, shared across all four. This package replaces the previously separate adapter-paperclip-cursor, adapter-paperclip-codex, adapter-paperclip-claude-code, and adapter-paperclip-hermes packages. None of those names are on npm anymore (adapter-paperclip-cursor and adapter-paperclip-hermes were unpublished; -codex and -claude-code never had a successful publish). Existing installs pointing at an old name migrate automatically to this package on their next capabilities sync via LEGACY_ADAPTER_PACKAGE_ALIASES in plugin-paperclip.

Install in Paperclip

Use the Phantom Agent plugin's sync flow from Settings → Plugins:

1. Plugin: @phantomagent/plugin-paperclip
2. Sync capabilities — surfaces each available runtime, resolved to this package + its matching subpath
3. Install the runtime(s) you want from the dropdown — Paperclip resolves packageName + exportPath automatically

Local path (development)

cd integrations
npm install
npm run build -w @phantomagent/adapter-paperclip-facade

Paperclip → Settings → Adapters → Install External Adapter — local path to packages/adapter-paperclip-facade, with exportPath set to e.g. ./claude-code for the runtime you're iterating on.

Adapter config (same ApplicationClient credentials as the plugin):

| Field | Value | |-------|-------| | Phantom API URL | https://api.phantomagent.io | | Application client ID | e.g. paperclip-proxy | | Application client secret | from Phantom Applications → Credentials |

Adding a new runtime

Every current runtime is a static, hand-written subpath — this package never discovers or generates entry points from Phantom's live catalog at runtime. Phantom's runtime catalog and AgentRuntimePolicy remain the sole authority on which runtimes exist and are allowed to execute; this package only provides known Paperclip entry points for runtimes that already have one.

To add one:

1. Add a new src/<runtime>/index.ts calling createPhantomFacadeExports({...}) with its config (same pattern as the four above)
2. Add matching ./​<runtime> and ./<runtime>/server entries to package.json's exports
3. Register the new subpath + packageName in Phantom's PAPERCLIP_FACADE_REGISTRY (api/src/agent-catalog/paperclip-facade-registry.ts)
4. Bump this package's version and publish

Verify

One wake → Phantom Executions shows a new run_id, log contains:

[phantom-agent] delegating heartbeat to Phantom (runtime=<slug>, auth=application_jwt, no local agent spawn)

No vendor API key in Paperclip config — resolved server-side by Phantom via the customer's integration, never seen by Paperclip.

See TASK_PHANTOM_RUNTIME_FACADE_V1.md.