paperclip-plugin-toapis

Paperclip adapter plugin for ToAPIs — run agents with an OpenAI-compatible POST /v1/chat/completions gateway at https://toapis.com/v1, multi-turn tool calling against Paperclip’s HTTP API, and a paperclip.plugin.json manifest.

Features

• Multi-turn function-calling loop against ToAPIs (tools + tool_choice)
• Paperclip REST tools (issues, comments, status, hire, approvals) via ctx.authToken
• Issue checkout and status transitions (in_progress → done / blocked)
• Skills loaded from ~/.toapis-adapter/skills (or SKILL.md per folder), configurable via skillsDir / PAPERCLIP_SKILLS_DIR
• Usage aggregated from usage on each completion; costUsd is 0 in the adapter result (no per-request USD in the public Chat Completions payload — budgets use token counts)
• Environment test (testEnvironment) with optional GET /v1/models and static fallback list

Not supported

• Models marked Responses only in the ToAPIs model list — use Chat Completions–capable models only.
• Accurate USD cost in AdapterExecutionResult from ToAPIs (not exposed like OpenRouter’s generation endpoint).

Quick start

1. Get an API key from ToAPIs console.
2. Add this package to your Paperclip monorepo (or depend on paperclip-plugin-toapis from npm if published).
3. Register the adapter on the server and UI (see REGISTRY_PATCHES.md) and adapter-plugin.md.
4. Set env (optional) for the Paperclip server process:

export TOAPIS_API_KEY="sk-..."
export TOAPIS_BASE_URL="https://toapis.com/v1"
export PAPERCLIP_AGENT_JWT_SECRET="$(openssl rand -hex 32)"
export PAPERCLIP_API_URL="http://localhost:3100"

5. Create an agent with adapterType: "toapis" and adapterConfig similar to:

{
  "model": "claude-sonnet-4-6",
  "apiKey": "sk-...",
  "temperature": 0.3,
  "maxTokens": 4096,
  "maxTurns": 25
}

Configuration

| Field | Description | |--------|-------------| | model | ToAPIs model id (e.g. claude-sonnet-4-6, gpt-5). See docs. | | apiKey | ToAPIs API key; falls back to TOAPIS_API_KEY. | | baseUrl | Gateway base URL (default https://toapis.com/v1 or TOAPIS_BASE_URL). | | systemPrompt, temperature, maxTokens, topP | Standard chat parameters. | | maxTurns | Max tool-loop iterations (default 25). | | autoApprove | Skip approval gates for hire/approval tools (default false). | | skillsDir | Override skills root (default ~/.toapis-adapter/skills). |

Development

pnpm install
pnpm typecheck
pnpm build

Requires @paperclipai/adapter-utils (published from Paperclip; see package.json). For a Paperclip monorepo, you can switch the dependency to "workspace:*" and add this package to pnpm-workspace.yaml.

License

MIT