[thiskevinwang]

Description

Implement support for Poppy v0.4 browser session endpoints. See https://personalagentprotocol.org/docs/0.4/guides#company-browsing

We'll support #3 — Signed-in browsing with the account's full access

• poppy:browser-sign-in scope allows everything the account can do.

The rationale: given the browser session endpoint will resolve to a clerk user session, we don't want to conflate that end state with OAuth scopes. This decision is 100% fine by the spec ¹,

The high-level flow:

stateDiagram-v2
    state "1. Discovery" as Discovery
    state "2. OAuth" as OAuth
    state "3. Poppy browser Session endpoint" as BrowserJoin
    state "4. Clerk ticket issued" as Ticket
    state "5. Redeemed for Clerk session" as ClerkSession

    Discovery --> OAuth
    OAuth --> BrowserJoin
    BrowserJoin --> Ticket
    Ticket --> ClerkSession

Loading

Proposed SDK usage guide — Next.js

Important

Proposed SDK usage...

1. Add the Clerk-defined __experimental_poppy option to proxy.ts, alongside normal route protection. Replace https://example.com with the configured application origin.

import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';

const isProtectedRoute = createRouteMatcher(['/account(.*)']);

export default clerkMiddleware(
  async (auth, request) => {
    if (isProtectedRoute(request)) await auth.protect();
  },
  {
    // Clerk preview configuration: serves Poppy discovery and browser session endpoint,
    // and checks current account access on joined-browser requests.
    __experimental_poppy: {
      // The poppy browser session endpoint the application hosts.
      // Poppy-defined  /{J}/authorize & Clerk-defined /{J}/callback path are derived from this URL.
      // where {J} is short for {browser_session_endpoint}
      browserSessionEndpoint: 'https://example.com/poppy/browser-session',
      // Clerk-defined destination after the join (after activation when signed in).
      // Same-origin path or URL; defaults to '/'. 
      redirectTo: '/account',
    },
  },
);

export const config = {
  matcher: [
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    '/(api|trpc)(.*)',
  ],
};

2. Add the Clerk-defined callback at app/poppy/browser-session/callback/page.tsx.

export { PoppyCallbackPage as default } from '@clerk/nextjs/server';

What is this component? ..So, the flow is

1. Agent browser visits GET /{J} ({J} = browser session endpoint)
   • html form, code, cookie returned
2. Agent sends POST /{J}/authorize, application/json
3. Agent submits form POST /{J}, application/x-www-form-urlencoded
4. On success, Clerk will set a ticket in cookies, and 303 redirect to /{J}/callback which is where the PoppyCallbackPage is mounted.
   • The PoppyCallbackPage will read the ticket through normal Clerk sign-in, redeem it, and convert to a signed in session.

3. Read normal Clerk authentication in a Server Component or Route Handler.

At this point, agent auth is readable by the application. ✅

import { auth } from '@clerk/nextjs/server';

const { userId, agent } = await auth();

// Clerk-defined experimental field for the verified Poppy-defined Session ID.
// Different from Clerk's sessionId. Undefined without an authenticated Poppy agent.
const protocolSessionId = agent?.__experimental_poppySessionId;

• userId identifies the Clerk account.
• Clerk-defined agent is present only for an authenticated, agent-attributed Clerk Session. Only present when actually sign-in.
• Other Clerk fields:
  • agent.__experimental_poppyClientId ~ The agents CIMD url
  • agent.__experimental_poppyUserId ~ The agent's pseudonymous user id (not a clerk user id)
  • agent.__experimental_poppySessionId ~ The agent's poppy session id

Checklist

• Backend SDK Node tests and focused edge-runtime tests pass.
• Backend SDK build and declarations pass.
• (If applicable) JSDoc comments have been added or updated for package exports.
• (If applicable) Documentation has been updated.

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Footnotes

1. Personal agents work faster and more reliably through a company agent or APIs than through a website, so start there for the tasks users ask for most. Then choose how much of your website personal agents can use, from least to most ↩

[vercel]

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

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Nov 10, 2026 12:18am UTC
swingset	Ready	Preview	Nov 10, 2026 12:18am UTC

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

[changeset-bot]

🦋 Changeset detected

Latest commit: 528132a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@clerk/backend	Minor
@clerk/nextjs	Minor
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/swingset	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@10702

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@10702

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@10702

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@10702

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@10702

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@10702

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@10702

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@10702

@clerk/expo-biometrics

npm i https://pkg.pr.new/@clerk/expo-biometrics@10702

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@10702

@clerk/expo-native-components

npm i https://pkg.pr.new/@clerk/expo-native-components@10702

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@10702

@clerk/express

npm i https://pkg.pr.new/@clerk/express@10702

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@10702

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@10702

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@10702

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@10702

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@10702

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@10702

@clerk/react

npm i https://pkg.pr.new/@clerk/react@10702

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@10702

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@10702

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@10702

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@10702

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@10702

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@10702

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@10702

commit: 528132a

[thiskevinwang]

💭 If this is meant to be mounted at an already clerk-derived path, eg. {J}/callback ¹, then it feels more appropriate to handle entirely in middleware/proxy.

• [benefit] 1 less component to mount; 1 less path to fat-finger-wrong.

Footnotes

1. {J} = {browser_session_endpoint} ↩

[thiskevinwang]

Update: FAPI interaction, primarily ...

signIn.create({ strategy: 'ticket', ticket })

...needs to happen client side.