RomanNum3ral
/
paperclip
mirror of https://github.com/paperclipai/paperclip.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
paperclip/doc/testing/new-agent-prerequisites.md

3.4 KiB
Raw Permalink Blame History

New-agent setup prerequisites

Reviewed against the adapter builders, runtime probes, and provider documentation on 2026-09-08.

Adapter Setup connection/prerequisites Model and effort in setup
Claude Code / Codex Existing subscription/API connection step Searchable model; supported effort options
Paperclip Runner The selected Codex, Claude ACPX, or OpenCode connection Provider model; no generic effort setting
Cursor CLI CURSOR_API_KEY, existing organization secret, or host agent login Model; no generic effort (Cursor uses modes)
Cursor Cloud Enter a new CURSOR_API_KEY and repository URL; optional starting branch/ref. The key is saved as a new organization secret; setup does not reuse existing keys. Account-default model; no generic effort
Gemini CLI GEMINI_API_KEY, existing organization secret, or supported host login Model; no effort control
Kimi Code Host login, or KIMI_MODEL_API_KEY plus KIMI_MODEL_NAME; optional protocol/base URL Existing model alias for host login; API model name for API auth; no effort on default ACP lane
Grok Build Host grok login Model and reasoning effort
Hermes Provider API key or existing host configuration Model; keep optional CLI tuning in full configuration
Hermes Gateway API base URL and API_SERVER_KEY Model is controlled by the gateway; no effort control
OpenCode / Pi Provider/model ID and optional provider key/organization secret Model; Pi thinking levels; OpenCode-specific variants remain in full configuration

Contracts and regression coverage

  • Cursor Cloud sends repoUrl and repoStartingRef, matching its SDK adapter. It never sends the old, ignored repository/branch properties.
  • New runtime keys are stored as distinct organization secrets when setup completes. They do not rotate existing keys. Existing Claude/Codex connection flows retain their user-specific credential behavior.
  • A draft key goes only into the allowlisted testCredentials request field during testing. It does not pass through persistence normalization. Hermes Gateway's one-shot key maps to its top-level apiKey only after normalization.
  • Failed tests and abandoned forms do not create secrets. A failed hire removes the newly created secret; cleanup errors remain visible.
  • Kimi API mode omits config.model: passing --model would override the model synthesized from KIMI_MODEL_* variables.
  • ui/src/pages/NewAgent.test.tsx covers field visibility, request payloads, secret reuse/storage, failure cleanup, and Kimi/Hermes mappings. server/src/__tests__/agent-test-environment-routes.test.ts verifies transient credential handling and rejects arbitrary environment variables.

UI and mocked contract tests do not prove a provider account can run a task. Successful live authentication requires the user's credential and, for Cursor Cloud, a repository connected to that Cursor account. The live invalid-key browser check verifies that a populated repository no longer produces the missing-repository diagnostic.

Provider references