Skip to content

fix: hold Connect until the preview answers, and stop calling every refusal expired - #5

Merged
benclarkeio merged 2 commits into
mainfrom
fix/preview-failures
Nov 10, 2026
Merged

benclarkeio merged 2 commits into
mainfrom
fix/preview-failures

Conversation

@benclarkeio

@benclarkeio benclarkeio commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Hold Connect until the preview answers, and when it fails. The page offered the button straight away, against "Slack, Teams, or Copilot", while the preview was in flight, and kept offering it if the preview failed. That lets someone press Connect without being told which chat account they're binding, which is the case preview exists to stop.
  • Only a 400 is an invalid link. previewLinkToken returned null for every non-200 answer and for network failures, and handlePreviewRequest turned all of them into "This link has expired". That included a bad API key (401), an agent the key doesn't own (403), an agent that's gone (404), and Agenta being down. Those now come back as unreachable, and the handler answers 502, matching how redeemLinkToken already maps redeem. A malformed answer is also unreachable, where before response.json() could throw.
  • previewLinkToken returns why it has nothing to show (PreviewResult), not null.
  • No @ for Teams or Copilot. channel-run fills platformUserName from Slack's display name, which Slack writes as @name, and from the Microsoft display name, which Teams and Copilot show without one.
  • platform prop. The page takes the ?platform= Agenta sends, but only to name the app before the preview has answered, never for who is connecting. It's checked against the three surfaces, so ?platform=constructor can't name a function from Object.prototype, and it's kept through sign-in. AGENTS.md already told adopters to wire it up, but the page had no prop for it.
  • Docs. The README says only redeem reports a used link: the preview API reads the token, not the redemption record, so a spent link still previews until it expires. AGENTS.md lists the held button among the things a restyle must keep.

The same in all three

This PR is one of three that make Agenta's own /connect, its example, and Bookable's Connect page behave the same: buildagenta/app#73, buildagenta/connect-example#5, The-Bookings-Group/bookable-app#394. The behaviour follows Agenta's API and channel gateway, read from their source.

Situation What the page does
Preview names the account "Connect your account (you) to Slack (@alice Smith in Acme Corp)", then the button
Teams or Copilot "Teams (Alice Smith)": no @. Slack always gets one, because Agenta sends Slack's display name and Slack writes it with an @
Preview not back yet, or failed No button. A failure says "… could not check this connection. Please try again."
Preview 400 (expired, tampered) "This link has expired", "Return to Teams…" when ?platform=teams
Preview 401, 403, 404, 5xx, no answer Treated as a failure, never "expired": a new link would fail the same way
Link already used The preview still names the account, because Agenta's preview doesn't check redemption. Connect then answers 409, and the page says "This link has already been used"
Redeem fails otherwise Button stays, "… could not connect the account. Please try again."
No token "This link has expired", naming the app from ?platform=
?platform= Names the app only in messages shown before the preview answers. Only slack, teams or copilot count (constructor names all three). Kept through sign-in
A body that isn't application/json 415, before the session is read. A form on another site can't send JSON's header, though a text/plain one can carry a body that parses as JSON. The example didn't check until buildagenta/connect-example#6; Bookable's bearer-header sign-in already stopped forms, and #394 adds the check anyway

Checks

  • bun run check, bun run typecheck and bun test pass: 36 tests. The new preview tests fail on main, and the constructor and toString cases fail on this PR's first commit.
  • The page has no DOM tests here, so I rendered it in Chromium against a stub server. Before and after on the first commit:
Case main This branch
Preview pending Button, "…to Slack, Teams, or Copilot" "Checking this connection…", no button
Preview 502 Button, "…to Slack, Teams, or Copilot" "We could not check this connection. Please try again.", no button
Teams, Alice Smith "Teams (@alice Smith)" "Teams (Alice Smith)"
Preview 400, ?platform=slack "Return to Slack, Teams, or Copilot…" "Return to Slack…"
Connect: 200, 409, 502 Connected / used / retry Same

On the final commit, the same cases as Bookable's proof gave the same results as Bookable. That covers the Slack display name with @, Teams without, ?platform=teams, copilot and constructor, a spent link (named, then "already used" on Connect), a 502 with no button, and sign-in returning to /connect?token=…&platform=teams.

https://claude.ai/code/session_013TYQ7D3Pk6WDSYuhCUvtGN


Generated by Claude Code

…efusal expired

- Map the preview the way redeem is mapped: only a 400 is an invalid link.
  A 401, 403 or 404 (the API key, or an agent it doesn't own or that is
  gone), a 5xx, a network failure or a malformed answer is "unreachable",
  so the person isn't sent for a new link that fails the same way
- Return why there is nothing to show (`PreviewResult`) instead of null,
  and have `handlePreviewRequest` answer 400 or 502 to match
- Offer no Connect button until the preview has named the account, and
  none when it fails. Before, the button showed straight away against
  "Slack, Teams, or Copilot", which is the case `preview` exists to stop
- Write Teams and Copilot names without an "@"; only Slack shows people
  as "@name"
- Take the `?platform=` Agenta sends as an optional prop, for naming the
  app before the preview has answered, as AGENTS.md already describes
- Document that only redeem reports a used link: a spent link still
  previews until it expires

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7D3Pk6WDSYuhCUvtGN
- Compare ?platform= against the three surfaces instead of indexing
  APP_NAMES with it, so "constructor" or "toString" names all three apps
  rather than a function from Object.prototype
- Send `platform` back through sign-in with the token, so the messages
  shown before the preview still name the app

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7D3Pk6WDSYuhCUvtGN
@benclarkeio
benclarkeio merged commit a3cbba7 into main Nov 10, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants