Add testnet agent invite URLs

[neekolas]

Summary

Adds testnet-aware agent invite URL construction.

• Maps XMTP_ENV=production to popup.convos.org.
• Maps XMTP_ENV=testnet to testnet.convos.org.
• Keeps dev and local on dev.convos.org.
• Keeps forced agent error simulation enabled for dev-like environments only.

Verification

• bun check
• bun test tests/agent-join.test.ts tests/config-environment.test.ts

Note

Add testnet domain support to buildInviteUrl for agent invite URLs

• Replaces the binary production/non-production domain logic in buildInviteUrl with an explicit per-environment map: production → popup.convos.org, testnet → testnet.convos.org, dev/local → dev.convos.org.
• Adds shouldAllowForcedErrors to gate forced error simulation in the join handler, replacing a direct XMTP_ENV !== 'production' check with shouldUseDevBehavior.
• Adds tests in agent-join.test.ts covering domain selection, slug encoding, and forced error gating across all environments.

^{Macroscope summarized 5550f93.}

[coderabbitai]

Warning

Rate limit exceeded

@neekolas has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 46 minutes and 11 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 46 minutes and 11 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 346bc3e0-0955-4a60-96bd-a9f5f3a88cab

📥 Commits

Reviewing files that changed from the base of the PR and between e2145e4 and 5550f93.

📒 Files selected for processing (2)

• src/api/v2/agents/handlers/join.ts
• tests/agent-join.test.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch testnet-agent-invite-url

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Claude finished @neekolas's task —— View job

---

Code Review Complete ✅

• Read and analyze changed files
• Review code quality and best practices
• Check for potential bugs or issues
• Assess test coverage
• Provide comprehensive feedback

---

Summary

This PR successfully adds testnet-aware agent invite URL construction with clean separation of concerns and good test coverage. The implementation is solid with only minor suggestions for improvement.

✅ Strengths

Code Quality

• Clean, focused changes with good separation of concerns
• Excellent use of type safety with XmtpEnv and Record<XmtpEnv, string>
• Proper URL encoding with encodeURIComponent() in buildInviteUrl (line 47)
• Clear function extraction with shouldAllowForcedErrors() improving readability

Test Coverage

• Comprehensive test coverage for all environments (production, testnet, dev, local)
• Tests slug encoding edge cases (spaces, slashes, question marks)
• Tests forced error behavior across environments
• Integration with existing config tests validates the complete behavior chain

Security

• No security concerns identified
• Forced error simulation properly gated to non-production environments

🔍 Observations & Minor Suggestions

1. Testnet Behavior Documentation (Minor)

Location: src/api/v2/agents/handlers/join.ts:50-52

The shouldAllowForcedErrors() function delegates to shouldUseDevBehavior(), which treats testnet as dev-like behavior. This means testnet allows forced error simulation via X-Force-Error headers.

Consideration: Is this intentional for testnet? Since testnet gets its own dedicated domain (testnet.convos.org), you might want to consider whether it should behave more like production (disabling forced errors) or continue with dev-like behavior.

Currently:

• ✅ Production: forced errors disabled
• ⚠️ Testnet: forced errors enabled (dev-like)
• ✅ Dev/Local: forced errors enabled

If testnet should mirror production behavior, you could add a helper like:

export function shouldAllowForcedErrors(xmtpEnv: XmtpEnv = XMTP_ENV): boolean {
  return xmtpEnv === "dev" || xmtpEnv === "local";
}

However, if testnet is meant for integration testing with error simulation, the current implementation is correct.

2. Test Description (Cosmetic)

Location: tests/agent-join.test.ts:35

The test description "allows forced errors in dev-like environments only" is placed inside the buildInviteUrl describe block, but it's actually testing shouldAllowForcedErrors(). Consider moving it to a separate describe block or renaming it to clarify scope:

describe("shouldAllowForcedErrors", () => {
  test("allows forced errors in dev-like environments only", () => {
    expect(shouldAllowForcedErrors("dev")).toBe(true);
    expect(shouldAllowForcedErrors("testnet")).toBe(true);
    expect(shouldAllowForcedErrors("local")).toBe(true);
    expect(shouldAllowForcedErrors("production")).toBe(false);
  });
});

3. Domain Mapping Centralization (Optional Enhancement)

Location: src/api/v2/agents/handlers/join.ts:40-45

The domain mapping is currently local to buildInviteUrl(). If this mapping is needed elsewhere in the codebase (e.g., for generating URLs in other contexts), consider extracting it to a shared constant in src/config.ts:

export const XMTP_ENV_DOMAINS: Record<XmtpEnv, string> = {
  production: "popup.convos.org",
  testnet: "testnet.convos.org",
  dev: "dev.convos.org",
  local: "dev.convos.org",
} as const;

This is only worth doing if the mapping will be reused elsewhere.

📊 Performance & Other Considerations

Performance: ✅ No concerns

• Simple object lookup with no performance impact
• URL encoding is appropriate and efficient

Bugs: ✅ None identified

• Type safety prevents invalid environments
• URL encoding handles special characters correctly
• Error simulation is properly gated

Best Practices: ✅ Followed

• Functions are pure and testable
• Good use of TypeScript types
• Consistent with existing codebase patterns
• Clear, self-documenting code

Recommendation

Approve with optional considerations: The code is production-ready as-is. The suggestions above are minor refinements around testnet behavior clarification and test organization, not blockers.

Great work on the clean implementation and thorough testing! 🎉

---

[neekolas]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• Add OTR testnet deployment workflow #189
• Add testnet agent invite URLs #188 👈 (View in Graphite)
• Validate and centralize XMTP environment handling #187
• Fix CI test and format baseline #186
• otr-dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[macroscopeapp]

Approvability

Verdict: Approved

Adds testnet environment support for agent invite URL generation by mapping 'testnet' to 'testnet.convos.org'. The logic change for forced errors is a pure refactor to use an existing helper - functionally identical. Simple, additive change with comprehensive unit tests.

^{You can customize Macroscope's approvability policy. Learn more.}