mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-06 10:48:12 +02:00
Devin FoleyandPaperclip
bf982c8c83
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Adapter names are part of the board-facing agent setup and management experience. > - The product now treats adapters as harnesses, while execution environments are modeled separately. > - Several built-in adapter labels still carried legacy local wording from the older harness-by-environment model. > - That wording makes the UI noisier and implies a distinction users no longer need to reason about. > - This pull request normalizes adapter display labels while keeping persisted adapter type identifiers unchanged. > - The benefit is clearer adapter selection and management copy without a database migration. ## Linked Issues or Issue Description No public GitHub issue was found for this exact cleanup. Related public PRs: - Supersedes #8910, an earlier branch for the same cleanup that did not include the later docs/gateway/Cursor alignment. - Refs #8819, which is related display-registry work for external multi-segment adapter labels, but not a duplicate of this built-in label cleanup. Feature request details: - Subsystem affected: Cross-cutting (`ui/`, `packages/adapters`, and docs). - Problem or motivation: user-facing adapter names include legacy local qualifiers even though adapters map to harnesses and environments are first-class elsewhere. - Proposed solution: remove the legacy local wording from built-in display labels, keep machine-readable adapter type ids unchanged, and keep gateway disambiguation where it is useful. - Alternatives considered: changing persisted adapter type ids was ruled out because it would create migration and compatibility risk; one-off UI replacements were ruled out because the display registry is already the correct central label boundary. - Roadmap alignment: this is small adapter UX polish, not a new roadmap-level core feature. ## What Changed - Updated the adapter display registry so known adapter labels are final and no built-in local adapter renders a legacy local suffix. - Preserved clean derived labels for unknown plugin local types while keeping gateway disambiguation for unknown gateway types. - Updated `AdapterManager` to prefer registry labels when the server reports raw adapter type ids for built-ins. - Removed legacy local wording from built-in adapter metadata labels in UI and adapter packages. - Aligned Cursor adapter metadata with the central display registry label. - Updated adapter docs and Storybook fixtures to match the new display names. - Added focused registry coverage for built-in labels and unknown plugin suffix behavior. ## Verification - `pnpm check:tokens` - `git diff --check origin/master...fix/adapter-display-labels` - Patch-addition scan for added secrets, private paths, and internal links: no matches. - GitHub duplicate search for open adapter-label/local-suffix issues and PRs; #8910 was identified as the older superseded public PR. - `pnpm exec vitest run ui/src/adapters/adapter-display-registry.test.ts` - `pnpm --filter @paperclipai/ui typecheck` - Stale-label scan found no remaining user-facing display-label suffixes; remaining local wording is operational/test terminology such as adapter ids, docs about running locally, and test descriptions. ## Risks Low risk. The change is display-label and documentation focused, and adapter type ids remain unchanged. The main risk is ambiguous gateway naming, mitigated by keeping explicit gateway labels where variants need disambiguation. ## Model Used OpenAI GPT-5 via Codex, tool-enabled coding agent in a local repository workspace. Context window size is not exposed by this environment. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing>
2.6 KiB
2.6 KiB
title, summary
| title | summary |
|---|---|
| Environment Variables | Full environment variable reference |
All environment variables that Paperclip uses for server configuration.
Server Configuration
| Variable | Default | Description |
|---|---|---|
PORT |
3100 |
Server port |
PAPERCLIP_BIND |
loopback |
Reachability preset: loopback, lan, tailnet, or custom |
PAPERCLIP_BIND_HOST |
(unset) | Required when PAPERCLIP_BIND=custom |
HOST |
127.0.0.1 |
Legacy host override; prefer PAPERCLIP_BIND for new setups |
DATABASE_URL |
(embedded) | PostgreSQL connection string |
PAPERCLIP_HOME |
~/.paperclip |
Base directory for all Paperclip data |
PAPERCLIP_INSTANCE_ID |
default |
Instance identifier (for multiple local instances) |
PAPERCLIP_DEPLOYMENT_MODE |
local_trusted |
Runtime mode override |
PAPERCLIP_DEPLOYMENT_EXPOSURE |
private |
Exposure policy when deployment mode is authenticated |
PAPERCLIP_API_URL |
(auto-derived) | Paperclip API base URL. When set externally (e.g., via Kubernetes ConfigMap, load balancer, or reverse proxy), the server preserves the value instead of deriving it from the listen host and port. Useful for deployments where the public-facing URL differs from the local bind address. |
Secrets
| Variable | Default | Description |
|---|---|---|
PAPERCLIP_SECRETS_MASTER_KEY |
(from file) | 32-byte encryption key (base64/hex/raw) |
PAPERCLIP_SECRETS_MASTER_KEY_FILE |
~/.paperclip/.../secrets/master.key |
Path to key file |
PAPERCLIP_SECRETS_STRICT_MODE |
false |
Require secret refs for sensitive env vars |
Agent Runtime (Injected into agent processes)
These are set automatically by the server when invoking agents:
| Variable | Description |
|---|---|
PAPERCLIP_AGENT_ID |
Agent's unique ID |
PAPERCLIP_COMPANY_ID |
Company ID |
PAPERCLIP_API_URL |
Paperclip API base URL (inherits the server-level value; see Server Configuration above) |
PAPERCLIP_API_KEY |
Short-lived JWT for API auth |
PAPERCLIP_RUN_ID |
Current heartbeat run ID |
PAPERCLIP_TASK_ID |
Issue that triggered this wake |
PAPERCLIP_WAKE_REASON |
Wake trigger reason |
PAPERCLIP_WAKE_COMMENT_ID |
Comment that triggered this wake |
PAPERCLIP_APPROVAL_ID |
Resolved approval ID |
PAPERCLIP_APPROVAL_STATUS |
Approval decision |
PAPERCLIP_LINKED_ISSUE_IDS |
Comma-separated linked issue IDs |
LLM Provider Keys (for adapters)
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY |
Anthropic API key (for Claude Code adapter) |
OPENAI_API_KEY |
OpenAI API key (for Codex adapter) |