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

Project	Deployment	Actions	Updated (UTC)
agents-api	Ready	Preview, Comment	Mar 31, 2026 1:28pm
agents-docs	Ready	Preview, Comment	Mar 31, 2026 1:28pm
agents-manage-ui	Ready	Preview, Comment	Mar 31, 2026 1:28pm

🦋 Changeset detected

Latest commit: 72eb253

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

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

TL;DR — Introduces a generic, extensible org entitlement system that enforces per-role seat limits (seat:admin, seat:member) and resource quotas (quota:project). Limits are opt-in — no entitlement rows means no cap — making this safe for self-hosted deployments while enabling cloud billing controls. The full stack is wired: schema, DAL, better-auth hooks, API middleware, OpenAPI metadata, manage UI feedback, and a new Billing page. All quota checks are serialized via SELECT ... FOR UPDATE to prevent TOCTOU races under concurrent requests.

Key changes

• Add org_entitlement table with colon-namespaced resource types — normalized schema with a CHECK constraint enforcing the ^[a-z]+:[a-z][a-z0-9_]*$ naming convention, unique per (organizationId, resourceType)
• Implement entitlement resolution and seat-counting DAL — new data-access/runtime/entitlements.ts with functions for resolving limits, counting members by role bucket (excluding service accounts), and summing seat entitlements
• Enforce seat limits in better-auth organization hooks — beforeCreateInvitation, beforeAddMember, beforeAcceptInvitation, and beforeUpdateMemberRole all call enforcePerRoleSeatLimit; replaces hardcoded membershipLimit: 300 with a dynamic callback via resolveTotalMembershipLimit
• Run SpiceDB role changes inside the entitlement lock — beforeUpdateMemberRole now wraps the SpiceDB changeOrgRole call inside enforcePerRoleSeatLimit via an onceVerified callback, ensuring the role mutation and the limit check are atomic under the same SELECT ... FOR UPDATE lock
• Add withEntitlementLock for TOCTOU-safe quota enforcement — wraps entitlement resolution + count check in a transaction with SELECT ... FOR UPDATE on the entitlement row, serializing concurrent quota checks
• Add requireEntitlement middleware for API route-level quota enforcement — generic middleware that acquires the entitlement lock, runs a caller-supplied countFn, and returns 402 with structured error body; wired to project creation routes via quota:project
• Guard PUT /project-full upsert create path with withEntitlementLock — the PUT upsert's inline create branch now wraps the entire flow in the entitlement lock, closing a bypass where PUT could create projects without quota checks
• Extend createProtectedRoute with x-entitlement OpenAPI extension — entitlement-gated routes now emit metadata in the OpenAPI spec via entitlement-meta.ts WeakMap pattern
• Add GET /manage/tenants/:tenantId/entitlements API endpoint — lists all entitlement rows for an org, exposed in OpenAPI under the new Entitlements tag
• Add payment_required (402) error code and forward extensions in error handler — new variant in ErrorCode enum; errorHandler now spreads extension fields (resourceType, current, limit) into the 402 response body
• Surface seat limits in invite dialog, role selector, members table, and project form — ENTITLEMENT_LIMIT_REACHED errors show contextual messages with links to the billing page for admins; project creation errors with payment_required also surface a "See usage" action
• Add Billing & Usage page with error/empty states — new /{tenantId}/billing route showing progress bars for seat and project usage; renders an informative card when no entitlements are configured; conditionally visible in the sidebar only when entitlements exist
• Refactor accept-invitation page into component modules — extracted AcceptDecline, AuthMethodPicker, ExternalAuthButtons, LoginForm, SignupForm, InvitationLayout, and InvitationSuccess from the monolithic page; AcceptDecline disables the accept button when seat limit is reached
• Return seatLimitReached and userExists from invitation verify endpoint — the verify route now returns these fields so the accept-invitation UI can proactively disable accept and route to the correct auth flow
• Fix sidebar entitlements fetch race condition — the useEffect in AppSidebar now uses a cancellation flag and cleanup function to prevent state updates on unmounted components
• Replace all hardcoded membersLimit: 300 with DEFAULT_MEMBERSHIP_LIMIT — UI pages and auth config now reference the shared constant
• Remove stale migration file — deleted superseded 0028_condemned_agent_zero.sql in favor of 0029_burly_satana.sql
• Add unit tests for entitlement functions and middleware — covers resolveEntitlement, countSeatsByRole, enforcePerRoleSeatLimit, resolveTotalMembershipLimit, roleMatchesAdminBucket, and 5 requireEntitlement middleware tests

_{Summary ｜ 55 files ｜ 26 commits ｜ base: main ← feat/max-seats}

org_entitlement table and data access layer

Before: No concept of per-org resource limits; membership capped at a hardcoded 300.
After: A normalized org_entitlement table stores (organizationId, resourceType, maxValue) tuples with a regex CHECK constraint on resource_type. A full DAL layer provides dalResolveEntitlement, dalCountMembersByRoleBucket, and dalSumSeatEntitlements.

The colon-namespaced resource type convention (seat:admin, seat:member, quota:project) allows querying by category with LIKE 'seat:%' while keeping the table flat. No entitlement row = no limit enforced, so self-hosted deployments remain uncapped by default.

How does seat counting handle service accounts?

Service accounts (identified via organization.serviceAccountUserId) are excluded from member counts in dalCountMembersByRoleBucket and added back as +1 to the total membership limit in resolveTotalMembershipLimit.

runtime-schema.ts · entitlements.ts (DAL) · entitlement-constants.ts · 0029_burly_satana.sql

TOCTOU-safe quota enforcement with withEntitlementLock

Before: Quota checks used a read-then-check pattern — two concurrent requests could both pass the limit check before either committed, allowing over-provisioning.
After: withEntitlementLock opens a transaction, acquires a row-level lock via SELECT ... FOR UPDATE on the entitlement row, then runs the caller's check+action callback. Concurrent callers block until the lock is released.

This lock is used in three places: the requireEntitlement middleware (for quota:project on POST /projects), the projectFull.ts PUT upsert create path (which wraps the entire create transaction inside the lock), and enforcePerRoleSeatLimit in the better-auth hooks (for seat:admin / seat:member).

entitlement-lock.ts · requireEntitlement.ts · projectFull.ts · entitlements.ts (core)

Per-role seat enforcement in better-auth hooks

Before: Organization hooks only synced SpiceDB state on member/invitation events; membership capped at a static 300.
After: enforcePerRoleSeatLimit is called in beforeCreateInvitation, beforeAddMember, beforeAcceptInvitation, and beforeUpdateMemberRole (only when the role bucket changes). The membershipLimit callback now dynamically sums seat:* entitlements via resolveTotalMembershipLimit, falling back to DEFAULT_MEMBERSHIP_LIMIT (300) when no entitlements are configured.

Enforcement throws APIError('PAYMENT_REQUIRED') with structured code, resourceType, current, limit fields. The beforeUpdateMemberRole hook now passes the SpiceDB changeOrgRole call as an onceVerified callback to enforcePerRoleSeatLimit, so the role mutation executes atomically inside the same SELECT ... FOR UPDATE lock — preventing a race where a concurrent role change could slip in between the limit check and the actual mutation. The invitation verify endpoint now also returns seatLimitReached and userExists so the accept-invitation UI can proactively block acceptance and route to the correct auth flow.

auth.ts · entitlements.ts (core) · invitations.ts

requireEntitlement middleware and quota:project

Before: No generic mechanism for route-level resource quota enforcement.
After: requireEntitlement({ resourceType, countFn, label }) creates Hono middleware that acquires the entitlement lock, calls the count function, and returns 402 if at capacity. Wired to POST /projects, POST /project-full, and the PUT upsert create path in projectFull.ts.

The middleware registers x-entitlement metadata on the route via registerEntitlementMeta, which createProtectedRoute picks up and injects into the OpenAPI spec. The errorHandler now destructures known fields and spreads remaining extensions into the response body, ensuring resourceType, current, and limit reach the client in the 402 response.

How does the error handler preserve entitlement fields?

The errorHandler destructures known fields (code, title, status, detail, instance, error) and spreads the rest into the response body. This ensures extension fields like resourceType, current, and limit from createApiError({ extensions: {...} }) are forwarded to the client in the 402 response.

requireEntitlement.ts · errorHandler.ts · projects.ts · create-protected-route.ts

Manage UI: seat-aware feedback and Billing page

Before: No visibility into seat usage or entitlement limits in the UI.
After: The invite dialog, role selector, members table, and project form all surface ENTITLEMENT_LIMIT_REACHED / payment_required errors with "See usage" links (admins) or "Contact your admin" messages. A new /billing page renders progress bars for seat:admin, seat:member, and quota:project usage with proper error/forbidden/empty states. The sidebar conditionally shows the Billing nav item only when entitlements exist, with a proper cleanup function on the fetch effect to prevent state updates on unmounted components.

The accept-invitation page was refactored from a single monolithic component into seven focused modules. AcceptDecline disables the accept button and shows an alert when the seat limit is reached, using the new seatLimitReached field from the verify endpoint. AuthMethodPicker uses the new userExists field to route returning users to login and new users to signup. The billing page now renders an informative card with "No entitlements configured" when no entitlements exist, instead of returning null. All hardcoded membersLimit: 300 values across UI pages now reference DEFAULT_MEMBERSHIP_LIMIT.

billing/page.tsx · invite-member-dialog.tsx · org-role-selector.tsx · app-sidebar.tsx

  ^{｜ View workflow run ｜ Triggered by Pullfrog ｜ Using Claude Opus ｜ 𝕏}

Ito Test Report ❌

21 test cases ran. 2 failed, 19 passed.

Across 21 validated scenarios, 19 passed and 2 failed, indicating the entitlement, quota, project-creation idempotency, invitation acceptance/security, and mobile invitation usability paths are mostly behaving correctly, including proper billing remediation at limits and expected uncapped behavior for no-entitlement tenants. The two key defects are a High-severity concurrency race that lets simultaneous member-to-admin promotions exceed admin seat caps and a Medium fail-closed regression where Billing stays visible on malformed tenant routes because stale async entitlement state is retained, both tied to changes in this PR.

❌ Failed (2)

Category	Summary	Screenshot
Adversarial	⚠️ Concurrent member-to-admin promotions both succeeded and exceeded the admin seat cap.
Adversarial	🟠 Billing nav remains visible on malformed tenant paths instead of failing closed when entitlement fetch becomes invalid.

beforeUpdateMemberRole: async ({ member, organization: org, newRole }) => {
  const { roleMatchesAdminBucket, enforcePerRoleSeatLimit } = await import(
    './entitlements'
  );
  const oldRole = member.role as OrgRole;
  const targetRole = newRole as OrgRole;

  const oldBucketIsAdmin = roleMatchesAdminBucket(oldRole);
  const newBucketIsAdmin = roleMatchesAdminBucket(targetRole);
  if (oldBucketIsAdmin !== newBucketIsAdmin) {
    await enforcePerRoleSeatLimit(config.dbClient, org.id, targetRole);
  }

await withEntitlementLock(db, orgId, resourceType, async (limit, tx) => {
  if (limit === null) return;

  const current = await countSeatsByRole(tx, orgId, role);
  if (current >= limit) {
    const bucket = roleMatchesAdminBucket(role) ? 'Admin' : 'Member';
    logger.info(
      { orgId, role, bucket, currentCount: current, maxValue: limit, action: 'enforce' },
      `${bucket} seat limit reached (${current}/${limit})`
    );
    throw new APIError('PAYMENT_REQUIRED', {
      message: `${bucket} seat limit reached (${current}/${limit})`,
      code: 'ENTITLEMENT_LIMIT_REACHED',
      resourceType,
      current,
      limit,
    });
  }
});

return db.transaction(async (tx) => {
  const rows = await tx
    .select({ maxValue: orgEntitlement.maxValue })
    .from(orgEntitlement)
    .where(
      and(eq(orgEntitlement.organizationId, orgId), eq(orgEntitlement.resourceType, resourceType))
    )
    .for('update');

  const limit = rows.length === 0 ? null : rows[0].maxValue;
  return fn(limit, tx as unknown as AgentsRunDatabaseClient);
});

const [hasEntitlements, setHasEntitlements] = useState(false);

useEffect(() => {
  if (tenantId) {
    fetchEntitlements(tenantId)
      .then((entitlements) => setHasEntitlements(entitlements.length > 0))
      .catch(() => setHasEntitlements(false));
  }
}, [tenantId]);

...(hasEntitlements
  ? [
      {
        title: STATIC_LABELS.billing,
        url: `/${tenantId}/billing`,
        icon: CreditCard,
      },
    ]
  : []),

✅ Passed (19)

Category	Summary	Screenshot
Adversarial	Rapid double-submit remained idempotent and produced exactly one project.
Adversarial	Rapid repeated invite submissions did not bypass limits; all over-capacity invites were rejected.
Adversarial	Authenticated direct accept API call was rejected with entitlement/payment-required style error (402), and invited user was not added to organization membership.
Adversarial	Appending external returnUrl did not produce open redirect; post-accept navigation stayed on same-origin tenant route.
Edge	Quota-boundary create behavior was verified as correctly blocked with billing remediation.
Edge	Project-full upsert create path enforced quota while existing-project update remained allowed.
Edge	Billing stayed hidden for tenant_unlimited, and inviting one member succeeded with no seat-limit/payment-required error.
Edge	Seat-limit enforcement blocked the extra invite and the remediation link correctly routed to billing.
Edge	Cross-bucket Member-to-Admin promotion is designed to be seat-enforced and remain blocked when admin seats are full.
Edge	Seat-limited invite displayed entitlement warning, kept Accept disabled, and left Decline actionable.
Edge	Opening /accept-invitation/ without email query produced deterministic invalid-link ErrorContent and Go home link, with no auth/login/signup controls rendered.
Logic	Project creation under available quota succeeded with one new project and success navigation.
Logic	Invite-under-capacity behavior was re-run successfully; adding a member completed with a success result as expected.
Logic	Same-bucket Admin/Owner role transitions are intentionally not seat-blocked, matching the entitlement guard logic.
Mobile	On iPhone 12 viewport, the invitation signup flow stayed usable through portrait→landscape→portrait rotation with no horizontal overflow, visible primary action, and preserved form state (email/full name/password).
Happy-path	Billing nav visibility logic is implemented correctly and behaves as expected for entitlement presence checks.
Happy-path	Entitlements endpoint contract returned expected resourceType/maxValue schema for the entitled tenant scenario.
Happy-path	Logged-out invite opened with signup-first UI (full name + password). After valid signup+accept, flow reached success and redirected to same-origin tenant route.
Happy-path	Invite URL rendered login-only branch with disabled email and forgot-password link; existing user sign-in and invitation acceptance reached success.

Commit: aee7335

View Full Run

Tell us how we did: Give Ito Feedback

Ito Test Report ✅

19 test cases ran. 19 passed.

The unified run passed all 19 of 19 test cases with zero failures, confirming expected entitlement, quota, billing, member-seat, and invitation behaviors in local non-production execution with no code-supported product defects observed. Key findings were that tenant entitlement APIs enforced strict auth and isolation (including no unauth/cross-tenant leakage), project creation and full upsert paths correctly enforced quota boundaries (402 at limit, no duplicate creates, updates allowed for existing IDs), billing UI/route access and usage rendering behaved correctly across admin/non-admin and zero-entitlement states, seat-saturation blocked admin invites/promotions with billing guidance, and invitation flows remained correct, mobile-usable, and secure against ID/email tampering, external returnUrl hijacking, and refresh/back-forward inconsistency.

✅ Passed (19)

Category	Summary	Screenshot
Adversarial	Endpoint authorization boundaries held: authenticated access succeeded; logged-out and tenant-mismatched access were denied with no payload exposure.
Adversarial	Invitation verify rejected mismatched id/email and malformed probes with stable 404 responses without metadata leakage.
Adversarial	Invitation acceptance ignored external returnUrl and redirected to an internal tenant route.
Adversarial	Refresh and back/forward after acceptance remained stable, and consumed invitation verify returned not_found.
Edge	Re-execution confirmed exact-quota project creation returns HTTP 402 payment_required with entitlement metadata, and billing CTA behavior is wired in code.
Edge	With one slot remaining, rapid double-submit created only one project (qa-edge2-202603311244) with no duplicate rows.
Edge	At exact quota, full-project upsert with non-existent id returned 402 payment_required and no new project row was created.
Edge	Non-admin direct access to /default/billing returned an Access denied 403 state, including after back/forward navigation.
Edge	Zero-entitlement tenant hid Billing navigation and loaded /billing without crashing or showing usage metrics.
Edge	Promoting a Member to Admin with a saturated admin seat bucket returned an entitlement failure and the role remained Member after refresh.
Edge	Method-matrix behavior matched verify payloads: existing invite rendered login path, new invite rendered signup path with actionable controls, and no-method invite rendered non-progressing dead-end guidance.
Edge	At 390x844 viewport, invitation flow remained usable with no horizontal overflow and accessible controls through sign-in/acceptance; flow completed and redirected to projects successfully.
Happy-path	Authenticated entitlement request returned valid tenant-scoped rows and schema; anonymous/cross-tenant requests were denied.
Happy-path	Created qa-route2-202603311242 under quota from UI and confirmed it appears in project list.
Happy-path	At exact quota, full-project upsert for existing project id qa-route2-202603311242 returned 200 and persisted updated fields.
Happy-path	Billing navigation was present for entitlement-enabled tenant and absent for zero-entitlement tenant, matching conditional visibility rules.
Happy-path	Billing usage cards rendered with populated values, and Projects usage matched the Projects list count.
Happy-path	Inviting an Admin while the admin seat bucket was saturated showed an entitlement-specific failure row and a working See usage link to billing.
Happy-path	Verify API returned valid=true, userExists=true, allowedAuthMethods and org/role metadata for existing invite; UI showed login-focused branch for existing user, signup branch for new user, and blocking no-method guidance correctly.

Commit: 20987d4

View Full Run

Tell us how we did: Give Ito Feedback

🔎💬 Inkeep AI search and chat service is syncing content for source 'Inkeep Agent Framework Docs'

Ito Test Report ❌

19 test cases ran. 1 failed, 18 passed.

Across 19 total test cases, 18 passed and 1 failed: entitlement retrieval, Billing visibility/authorization, quota and seat-capacity gating, invitation verification/acceptance (existing and new users), tamper/open-redirect defenses, rapid interaction handling, and mobile responsiveness all behaved as expected, with fail-closed behavior and no sensitive data leakage observed. The key finding is a High-severity real defect in concurrent project creation where two near-simultaneous POST /manage/tenants/:tenantId/projects requests can both succeed and exceed quota because the entitlement check counts usage via the global DB client instead of the lock transaction context, breaking entitlement and billing guarantees.

❌ Failed (1)

Category	Summary	Screenshot
Adversarial	⚠️ Concurrent project quota enforcement can be bypassed under race conditions.

await withEntitlementLock(runDbClient, tenantId, resourceType, async (limit, _tx) => {
  if (limit === null) {
    await next();
    return;
  }

  const current = await countFn(tenantId);

  if (current >= limit) {
    throw createApiError({
      code: 'payment_required',
      message: `${displayLabel} limit reached (${current}/${limit})`,
    });
  }

  await next();
});

return db.transaction(async (tx) => {
  const rows = await tx
    .select({ maxValue: orgEntitlement.maxValue })
    .from(orgEntitlement)
    .where(
      and(eq(orgEntitlement.organizationId, orgId), eq(orgEntitlement.resourceType, resourceType))
    )
    .for('update');

  const limit = rows.length === 0 ? null : rows[0].maxValue;
  return fn(limit, tx as unknown as AgentsRunDatabaseClient);
});

permission: requirePermission({ project: ['create'] }),
entitlement: requireEntitlement({
  resourceType: QUOTA_RESOURCE_TYPES.PROJECT,
  countFn: (tenantId) => countProjectsInRuntime(runDbClient)({ tenantId }),
  label: 'Project',
}),

✅ Passed (18)

Category	Summary	Screenshot
Adversarial	Rapid repeated submissions at quota did not create duplicate projects or bypass limits.
Adversarial	Missing email, mismatched email/id, and stale invitation id all failed safely with stable invalid-invitation screens and no visible sensitive data leakage, including after back/forward/reload.
Adversarial	Open-redirect attempts via returnUrl are blocked by same-origin validation and safe fallback redirect handling.
Adversarial	Rapid alternating Accept/Decline interactions produced one terminal accepted outcome without duplicate processing artifacts.
Authz	Non-admin deep-link to billing is blocked with access denied and no entitlement usage values exposed.
Edge	At quota, create was blocked with 402 payment_required contract; remediation action is implemented in UI.
Edge	With member seats saturated (0/0), invite submission was blocked and showed entitlement-specific remediation with a See usage link to billing.
Edge	In authenticated invited-user state under saturated seat entitlement, page showed limit alert, disabled Accept button, and enabled Decline button.
Mobile	Prior blocked outcome was a harness artifact; mobile billing showed no horizontal overflow and invitation submit entered disabled/loading state as expected.
Happy-path	Authenticated admin request to /manage/tenants/default/entitlements returned HTTP 200 with valid entitlements JSON payload.
Happy-path	Project creation below quota succeeded and navigated to the new project's agents page.
Happy-path	Verify endpoint returned required contract keys for valid invitation links; existing invite reported userExists=true and new invite reported userExists=false.
Screen	Billing nav visibility correctly toggled: visible with entitlements, hidden on simulated 500 and empty entitlement responses.
Screen	Billing usage cards render correctly for admin; the "Need more?" card is intentionally informational and non-clickable by design.
Screen	Inviting [email protected] as Member succeeded with 1 successful result, copy-link control, and invitation-sent status messaging.
Screen	Cross-bucket role change into a full admin bucket remained blocked, with the member role preserved and seat-limit messaging shown.
Screen	Existing invited user saw login path (no signup), signed in, and invitation flow redirected safely to an internal app route.
Screen	After reseeding to a truly new email, invitation page showed signup (not login); account creation and join flow completed successfully with safe internal redirect.

Commit: 72eb253

View Full Run

Tell us how we did: Give Ito Feedback