normal-sugar/paperclip-captcha-solver-skill

Controlled CAPTCHA Recovery for Paperclip Agents

Paperclip coordinates the issue, budget, approval state, and agent heartbeat. The underlying agent runtime owns browser or MCP configuration. This skill does not add an MCP server to the Paperclip control plane.

When to use

• The current Paperclip issue identifies an owned, simulated, or explicitly authorized target.
• The runtime reports a typed CAPTCHA interruption rather than guessing from page text.
• The caller has checked the task object against the official CapSolver API documentation.
• One recovery attempt and at most five result polls fit the approved task budget.

When not to use

• Login, SSO, MFA, identity confirmation, payment, account creation, or another human-only checkpoint.
• Private or restricted data, an unknown target, or a task without written authorization.
• An unsupported or ambiguous challenge signal.
• A retry after this recovery context has already been consumed.

Procedure

1. Read PAPERCLIP_TASK_ID, PAPERCLIP_RUN_ID, and the assigned task purpose from the runtime context. Never log PAPERCLIP_API_KEY or CAPSOLVER_API_KEY.
2. Confirm authorization and record issueId, runId, and purpose in the recovery input.
3. Require challenge.detected=true and challenge.supported=true. Otherwise return not_applicable or human_handoff.
4. Supply a task object verified against the official createTask request contract. Do not invent a task type or field.
5. Call the recovery helper exactly once. Enforce maxAttempts=1, maxPolls<=5, and timeoutMs<=60000.
6. Accept only processing or ready from the official getTaskResult lifecycle. A ready result must contain a structured solution object.
7. Resume the authorized task only after application-level validation. Every timeout, malformed result, exhausted budget, unknown status, or duplicate context goes to human review.

Run the offline example

npm test
npm run smoke
node examples/run-fixture.js

The fixture makes no network request and uses no real key. For a live authorized integration, construct CapSolverClient from src/capsolver-client.js and pass a documented task object at runtime.

Expected states

Status	Meaning	Next action
not_applicable	No typed challenge was detected	Continue without recovery
ready	Structured solution passed transport validation	Validate against the owned application, then resume once
stopped	Policy or input gate failed	Stop the run
human_handoff	Runtime, budget, timeout, or result problem	Move the Paperclip issue to review

Responsible Use

Use only for public data, owned systems, simulated fixtures, or targets covered by explicit written authorization. Respect terms, access policies, rate limits, data minimization, retention rules, and human-only checkpoints. Never use this skill for credentials, sensitive personal data, unlimited collection, or unauthorized access.