docs: tell agents to run acp configure themselves instead of asking the human#25
Open
psmiratisu wants to merge 5 commits into
Open
docs: tell agents to run acp configure themselves instead of asking the human#25psmiratisu wants to merge 5 commits into
acp configure themselves instead of asking the human#25psmiratisu wants to merge 5 commits into
Conversation
Agent harnesses (Perplexity, Claude, Grok, etc.) often refuse to run
`acp configure` because the name and behavior read as "interactive
human setup" — they punt to the user instead of executing it and
relaying the URL.
Add a sibling `acp auth` namespace that decouples URL emission from
polling:
- `acp auth url` returns {url, requestId} and exits immediately. No
browser opens, no polling — safe for agents to call directly.
- `acp auth complete --request-id <id>` finalizes after the human
signs in. Polls (up to 5 min) and saves tokens.
`acp configure` is untouched for humans on a workstation and for the
non-interactive --token / env-var flow.
Rewrite the SKILL.md Setup section to make the agent recipe explicit
("you, the agent, run these — do not punt to the human") and update
the NOT_AUTHENTICATED recovery hint and file map accordingly.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit ea13532. Configure here.
Previously `complete` polled internally for up to 5 minutes, which
reintroduces the same problem `acp auth` was meant to solve — long
blocking calls trip agent-harness timeouts.
Make `acp auth complete` a single non-blocking probe instead. Returns
`{done: false}` when the human hasn't signed in yet, or
`{done: true, walletAddress}` once tokens are saved. Agents poll it
every few seconds (same pattern as `acp card signup-poll` and the OTP
recipe). Cap retries at ~5 min on the caller side; re-run `acp auth url`
if it expires.
Drop the internal `waitForToken` helper since we no longer block. Update
SKILL.md recipe and the `NOT_AUTHENTICATED` recovery hint.
`acp auth url` + `acp auth complete` duplicated the auth surface that `acp configure` already covers. The real problem is behavioral, not a missing command: agent harnesses were pushing `acp configure` back to the human instead of running it themselves. Drop the auth.ts file and its registration. Reshape the SKILL.md Setup section around `acp configure --json` directly: the URL prints on stdout almost immediately, the command then waits up to 5 min, and runtimes that can't tolerate long-running commands can stream stdout to relay the URL the moment it lands. Update the NOT_AUTHENTICATED recovery hint and file map.
psmiratisu
changed the title
acp auth url + acp auth complete)acp configure themselves instead of asking the human
Zuhwa
approved these changes
May 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Agent harnesses (Perplexity, Claude, Grok, etc.) frequently refuse to execute
acp configurethemselves and instead tell the human "please runacp configure." That's a behavioral / docs problem, not a missing-command problem —acp configurealready prints the URL on stdout almost immediately and exits cleanly once the human signs in.This PR fixes it in SKILL.md only:
acp configureyourself — do not punt to the human" recipe.acp configure --jsonshape: URL JSON line arrives early, final auth JSON arrives after the human signs in.NOT_AUTHENTICATEDrecovery hint in the error table to push agents toward running it themselves.No code changes —
acp configureis unchanged. Earlier commits in this branch experimented with a separateacp authnamespace and were reverted in990f3d1as overengineered.Test plan
acp configureinstead of asking the humanNote
Low Risk
Documentation-only changes to SKILL.md with no runtime or auth code modifications.
Overview
Setup now tells harness agents to run
acp configurethemselves instead of asking the human to run it; the human only needs to open the OAuth URL you relay.The doc spells out
acp configure --json: first stdout line is{"url":"..."}, then after sign-in (up to ~5 min) the finalmessage/walletAddressJSON. It adds a line-by-line stdout tip for runtimes that can't keep a long-lived process open.The
NOT_AUTHENTICATEDrecovery row matches that flow (agent runs configure, human clicks the URL). No CLI behavior changes.Reviewed by Cursor Bugbot for commit 76f0320. Bugbot is set up for automated code reviews on this repo. Configure here.