Skip to content

feat(cli): Claim Sentry agent handoffs during setup - #2320

Merged
evanpurkhiser merged 1 commit into
mainfrom
git/feat-cli-support-sentry-agent-handoff
Nov 18, 2026
Merged

evanpurkhiser merged 1 commit into
mainfrom
git/feat-cli-support-sentry-agent-handoff

Conversation

@evanpurkhiser

@evanpurkhiser evanpurkhiser commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

The public handoff page launches the installer with SENTRY_HANDOFF. Setup must claim the intended account even when the CLI is already installed or authenticated to another account or Sentry host, and failures need to remain actionable without exposing either short-lived code.

Integrate handoff claiming into the existing sentry cli setup --install path used by the shell and PowerShell installers. The CLI uses the generated claimAgentHandoff operation from @sentry/api 2.8.0, authenticates with the returned setup code, client ID, and Sentry URL while superseding unrelated credentials, and prints flowInstructions only after authentication succeeds.

Structured API errors preserve useful server detail. An IP-pinning mismatch provides explicit recovery guidance using the stable code from getsentry/sentry#131464, while handoff and setup codes remain out of logs, telemetry, persisted configuration, and user-facing errors.

@evanpurkhiser
evanpurkhiser requested a review from BYK November 17, 2026 15:23
@vercel

vercel Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated
sentry-local Skipped Skipped Nov 18, 2026 4:59pm UTC

Request Review

Comment thread packages/cli/src/commands/cli/setup.ts Outdated
});

if (getEnv().SENTRY_SETUP_CODE && !hasStoredAuthCredentials()) {
const handoffCode = getEnv().SENTRY_HANDOFF?.trim();

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
const handoffCode = getEnv().SENTRY_HANDOFF?.trim();
const handoffCode = getEnv().SENTRY_HANDOFF?.trim();
const setupCode = getEnv().SENTRY_SETUPC_ODE?.trim();

should just have both up here then

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done — setup now reads and trims both handoff and setup codes together before branching.

Comment thread packages/cli/src/commands/cli/setup.ts Outdated

if (getEnv().SENTRY_SETUP_CODE && !hasStoredAuthCredentials()) {
const handoffCode = getEnv().SENTRY_HANDOFF?.trim();
let flowInstructions: string | undefined;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A better name might be like

Suggested change
let flowInstructions: string | undefined;
let afterSetupInstructions: string | undefined;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done — renamed this to afterSetupInstructions.

Comment thread packages/cli/src/lib/setup-code.ts Outdated
} = {},
): Promise<BootstrapResult> {
const code = getEnv().SENTRY_SETUP_CODE;
const code = options.code ?? getEnv().SENTRY_SETUP_CODE;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we just make code required and the caller would pass the SENTRY_SETUP_CODE wherever this was called before?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done — bootstrapAuthentication now requires code, and the setup and auth command callers pass SENTRY_SETUP_CODE explicitly while handoff passes the returned setup code.

Comment thread packages/cli/src/lib/agent-handoff.ts Resolved
@evanpurkhiser evanpurkhiser changed the title feat(cli): Support Sentry agent handoff feat(cli): Claim Sentry agent handoffs during setup Nov 17, 2026
@evanpurkhiser
evanpurkhiser force-pushed the git/feat-cli-support-sentry-agent-handoff branch from 9c9cb07 to 058096d Compare November 17, 2026 17:05
@evanpurkhiser
evanpurkhiser marked this pull request as ready for review November 17, 2026 17:05
@github-actions github-actions Bot added the risk: medium PR risk score: medium label Nov 17, 2026
@evanpurkhiser
evanpurkhiser force-pushed the git/feat-cli-support-sentry-agent-handoff branch from 058096d to a751a95 Compare November 17, 2026 17:08
Comment on lines +46 to +51
yield new CommandOutput(
await bootstrapAuthentication({
...flags,
code: getEnv().SENTRY_SETUP_CODE ?? "",
}),
);

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nvm actually I dislike tis lol, move the SENTRY_SETUP_CODE back into the bootstrapAuthentication and make code optional again

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done — bootstrapAuthentication now falls back to SENTRY_SETUP_CODE when code is omitted. The auth bootstrap and setup callers use that fallback again, while handoff still passes its claimed setup code explicitly.

@cursor cursor Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

Comment thread packages/cli/src/lib/agent-handoff.ts Resolved
@evanpurkhiser
evanpurkhiser force-pushed the git/feat-cli-support-sentry-agent-handoff branch from 89984ab to d070421 Compare November 17, 2026 17:25
Comment thread packages/cli/src/lib/agent-handoff.ts Resolved
Comment thread packages/cli/src/commands/cli/setup.ts Resolved
Comment thread packages/cli/src/lib/agent-handoff.ts Resolved
@evanpurkhiser
evanpurkhiser force-pushed the git/feat-cli-support-sentry-agent-handoff branch from d070421 to 2f8c183 Compare November 17, 2026 19:33
@evanpurkhiser
evanpurkhiser force-pushed the git/feat-cli-support-sentry-agent-handoff branch from 2f8c183 to 9a607f5 Compare November 17, 2026 19:40

@cursor cursor Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

clientId: handoff.clientId,
force: true,
url: handoff.sentryUrl,
});

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Handoff client ID not persisted

Medium Severity

Handoff authentication exchanges the setup code with handoff.clientId, but that client ID is not stored on the account. Later refresh still calls getClientId(), which is the env/build default. When those IDs differ, refresh is rejected after the access token expires and the headless session dies.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 9a607f5. Configure here.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tracked separately in #2383. We should persist the issuing OAuth client ID with each stored credential and use it for refresh. This can also affect existing logins if SENTRY_CLIENT_ID changes after login.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 3 total unresolved issues (including 1 from previous review).

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit da5169e. Configure here.

Comment thread packages/cli/src/lib/agent-handoff.ts Resolved
Comment thread packages/cli/src/lib/agent-handoff.ts Resolved

@BYK BYK left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No blockers, just questions

Comment thread packages/cli/src/commands/cli/setup.ts Outdated
if (!flags["no-completions"]) {
await warmCachesAfterLogin();
}
} else if (setupCode && !hasStoredAuthCredentials()) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should't we do this even when there are stored auth credentials? To make sure this account is added to the list as it's not guaranteed to be the same as local credentials?

Comment thread packages/cli/src/commands/cli/setup.ts Resolved
Comment thread packages/cli/src/commands/cli/setup.ts Resolved
Comment thread packages/cli/src/commands/cli/setup.ts Resolved
Comment thread packages/cli/src/lib/agent-handoff.ts Resolved
Comment thread packages/cli/src/lib/agent-handoff.ts Resolved
Comment thread packages/cli/src/lib/oauth.ts Resolved
Web handoffs need setup to claim the intended account even when another login is already stored. Exchange the short-lived handoff during the existing setup path, replace the applicable account, and reveal the returned instructions only after authentication succeeds.
@evanpurkhiser
evanpurkhiser force-pushed the git/feat-cli-support-sentry-agent-handoff branch from f25b90c to 6b06a89 Compare November 18, 2026 16:59
@evanpurkhiser
evanpurkhiser merged commit 3b8eec7 into main Nov 18, 2026
34 checks passed
@evanpurkhiser
evanpurkhiser deleted the git/feat-cli-support-sentry-agent-handoff branch November 18, 2026 17:17
MathurAditya724 pushed a commit that referenced this pull request Nov 18, 2026
…#2354)

Lets Sentry's setup page show one command that installs the CLI and
claims the agent handoff: `curl -fsSL
https://cli.sentry.dev/install/sntryh_… | bash`.

`/install/<code>` returns the normal install script with `export
SENTRY_HANDOFF='<code>'` added after the shebang. `sentry cli setup
--install` then claims the handoff (#2320). Plain
`/install` doesn't change.

The site is deployed as static Vercel build output, so the new route
goes to a small Edge Function. At packaging time, the function gets the
same install script the release ships. It only accepts codes that match
Sentry's format: `sntryh_` followed by 43 base64url chars, the same
regex as `sentry/agent_handoff/views.py`. That keeps anything
shell-unsafe out of the script. Any other code returns 404, and
responses are sent with `Cache-Control: no-store`.

To add a function, packaging had to move out of the inline
`printf`/`zip` in `cli-build.yml` and into
`apps/cli-docs/vercel/build-output.mjs`. The existing `/install` routes
are byte-for-byte unchanged.

**Open questions**
- Vercel's routing to the function hasn't been tried on a real
deployment yet. The function reads the code from either the rewritten
`?code=` or the original `/install/<code>` path, so it works whichever
URL Vercel passes it. Worth trying on a preview deploy before merging.
- The handoff code now appears in request URLs, so it shows up in Vercel
request logs. That seems acceptable for a short-lived, single-use code.
- Only bash for now. `install.ps1/<code>` would be a small follow-up if
we want a Windows one-liner.

<!-- junior-request-attribution:start -->
via @evanpurkhiser.
<!-- junior-request-attribution:end -->

<!-- junior-session-footer:start -->
<!-- junior-conversation-id:slack%3AC0C272JQP44%3A1794959461.634559 -->

--

[View
Session](https://junior-prod.sentry.dev/conversations/slack%3AC0C272JQP44%3A1794959461.634559)
[[Sentry]](https://sentry.sentry.io/explore/conversations/slack%3AC0C272JQP44%3A1794959461.634559/?project=4510944073809921)

<!-- junior-session-footer:end -->

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: Evan Purkhiser <1421724+evanpurkhiser@users.noreply.github.com>
evanpurkhiser added a commit to getsentry/sentry that referenced this pull request Nov 18, 2026
Agent handoffs now claim and authenticate through Sentry CLI, so the
public Markdown page should hand the one-time code to the installer
instead of exchanging it itself.

This updates `agent-handoff.md` with `SENTRY_HANDOFF` install commands
for Unix and PowerShell, removes the legacy Markdown POST, slash alias,
and private credential runbook, and moves the remaining claim tests to
the public JSON API. Claim and setup-code analytics remain on the shared
API path.

Draft until
[getsentry/toolkit#2320](getsentry/toolkit#2320)
lands and its CLI release is available from the stable installer.

---------

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>

This branch was previously deployed

1 inactive deployment
Preview — 6b06a896 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk: medium PR risk score: medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants