@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/runtime/invite-service.ts

@@ -1,78 +1,25 @@
 /**
- * Shared business logic for invite management.
+ * Daemon-owned invite presentation and provider-call helpers.
  *
- * Extracted from the handlers in daemon/handlers/config-inbox.ts so that
- * both the HTTP routes and the message handlers call the same logic.
- *
- * Member/contact operations have been migrated to the /v1/contacts and
- * /v1/contacts/channels endpoints.
+ * The gateway owns the canonical invite lifecycle (its `ingress_invites`
+ * table; mint/list/revoke/redeem run gateway-natively). These helpers layer
+ * display-only fields — share link, guardian instruction, channel handle —
+ * onto gateway-minted payloads and place outbound invite calls.
  */
 
 import { startInviteCall } from "../calls/call-domain.js";
 import { isChannelId } from "../channels/types.js";
 import { getContact } from "../contacts/contact-store.js";
-import {
-  createInvite,
-  findById,
-  findByTokenHash,
-  hashToken,
-  type IngressInvite,
-  markInviteExpired,
-} from "../persistence/invite-store.js";
 import {
   DECLINED_BY_USER_SENTINEL,
   DEFAULT_USER_REFERENCE,
   resolveGuardianName,
 } from "../prompts/user-reference.js";
-import { isValidE164 } from "../util/phone.js";
-import { generateVoiceCode, hashVoiceCode } from "../util/voice-code.js";
 import {
   getInviteAdapterRegistry,
   resolveAdapterHandle,
 } from "./channel-invite-transport.js";
 import { generateInviteInstruction } from "./invite-instruction-generator.js";
-import {
-  redeemInvite as redeemInviteTyped,
-  redeemVoiceInviteCode as redeemVoiceInviteCodeTyped,
-  type VoiceRedemptionOutcome,
-} from "./invite-redemption-service.js";
-
-// ---------------------------------------------------------------------------
-// Response shapes — used by both HTTP routes and message handlers
-// ---------------------------------------------------------------------------
-
-/**
- * Redemption outcome type surfaced to callers. `already_member` consumes no
- * invite use, so the gateway must not mirror it into recordInviteRedemption.
- */
-export type RedemptionType = "redeemed" | "already_member";
-
-export interface InviteResponseData {
-  id: string;
-  sourceChannel: string;
-  token?: string;
-  share?: {
-    url: string;
-    displayText: string;
-  };
-  tokenHash: string;
-  maxUses: number;
-  useCount: number;
-  expiresAt: number | null;
-  status: string;
-  note?: string;
-  // Voice invite fields (present only for voice invites)
-  expectedExternalUserId?: string;
-  voiceCode?: string;
-  voiceCodeDigits?: number;
-  friendName?: string;
-  guardianName?: string;
-  // Non-voice invite fields (present only for non-voice invites)
-  inviteCode?: string;
-  guardianInstruction?: string;
-  channelHandle?: string;
-  createdAt: number;
-}
 
 // ---------------------------------------------------------------------------
 // Mappers
@@ -81,7 +28,7 @@ export interface InviteResponseData {
 function buildSharePayload(
   sourceChannel: string,
   rawToken?: string,
-): InviteResponseData["share"] | undefined {
+): { url: string; displayText: string } | undefined {
   if (!rawToken || !isChannelId(sourceChannel)) return undefined;
   const adapter = getInviteAdapterRegistry().get(sourceChannel);
   if (!adapter?.buildShareLink) return undefined;
@@ -98,337 +45,133 @@ function buildSharePayload(
   }
 }
 
-function inviteToResponse(
-  inv: IngressInvite,
-  opts?: {
-    rawToken?: string;
-    voiceCode?: string;
-    inviteCode?: string;
-    guardianInstruction?: string;
-    channelHandle?: string;
-  },
-): InviteResponseData {
-  const share = buildSharePayload(inv.sourceChannel, opts?.rawToken);
-  return {
-    id: inv.id,
-    sourceChannel: inv.sourceChannel,
-    ...(opts?.rawToken ? { token: opts.rawToken } : {}),
-    ...(share ? { share } : {}),
-    tokenHash: inv.tokenHash,
-    maxUses: inv.maxUses,
-    useCount: inv.useCount,
-    expiresAt: inv.expiresAt,
-    status: inv.status,
-    note: inv.note ?? undefined,
-    ...(inv.expectedExternalUserId
-      ? { expectedExternalUserId: inv.expectedExternalUserId }
-      : {}),
-    ...(opts?.voiceCode ? { voiceCode: opts.voiceCode } : {}),
-    ...(inv.voiceCodeDigits != null
-      ? { voiceCodeDigits: inv.voiceCodeDigits }
-      : {}),
-    ...(inv.friendName ? { friendName: inv.friendName } : {}),
-    ...(inv.guardianName ? { guardianName: inv.guardianName } : {}),
-    ...(opts?.inviteCode ? { inviteCode: opts.inviteCode } : {}),
-    ...(opts?.guardianInstruction
-      ? { guardianInstruction: opts.guardianInstruction }
-      : {}),
-    ...(opts?.channelHandle ? { channelHandle: opts.channelHandle } : {}),
-    createdAt: inv.createdAt,
-  };
-}
-
 // ---------------------------------------------------------------------------
 // Result types
 // ---------------------------------------------------------------------------
 
-export type IngressResult<T> =
-  | { ok: true; data: T }
-  | { ok: false; error: string };
+type IngressResult<T> = { ok: true; data: T } | { ok: false; error: string };
 
 // ---------------------------------------------------------------------------
 // Invite operations
 // ---------------------------------------------------------------------------
 
-export async function createIngressInvite(params: {
-  sourceChannel?: string;
-  note?: string;
-  maxUses?: number;
-  expiresInMs?: number;
-  // Voice invite parameters. Display metadata is no longer accepted from
-  // callers: the invitee's name is resolved from the bound contact's
-  // displayName at every read site (voice greeting, instructions), and the
-  // guardian label is resolved at runtime via resolveGuardianName().
-  expectedExternalUserId?: string;
-  contactId: string;
-}): Promise<IngressResult<InviteResponseData>> {
-  if (!params.sourceChannel) {
-    return { ok: false, error: "sourceChannel is required for create" };
-  }
-
-  if (!params.contactId) {
-    return { ok: false, error: "contactId is required for create" };
+/**
+ * Guardian display label attached to voice invites, resolved from the
+ * guardian persona with the placeholder/declined sentinels filtered out.
+ * The daemon passes it through to the gateway mint, which stores it on the
+ * invite row and never interprets it.
+ */
+export function resolveInviteGuardianName(): string | undefined {
+  const name = resolveGuardianName();
+  if (
+    !name ||
+    name === DEFAULT_USER_REFERENCE ||
+    name === DECLINED_BY_USER_SENTINEL
+  ) {
+    return undefined;
   }
+  return name;
+}
 
-  // Resolve the bound contact's displayName as the canonical invitee name.
-  // The greeting and instruction copy use this rather than a free-text flag.
-  const boundContact = getContact(params.contactId);
-  const resolvedContactName = boundContact?.displayName?.trim() || undefined;
-  const resolvedFirstName = resolvedContactName?.split(/\s+/)[0];
-
-  // For voice invites: generate a one-time numeric code, hash it, and pass
-  // the hash to the store. The plaintext code is included in the response
-  // exactly once and never stored.
-  let voiceCode: string | undefined;
-  let voiceCodeHash: string | undefined;
-  let effectiveGuardianName: string | undefined;
-  const isVoice = params.sourceChannel === "phone";
-
-  // For non-voice invites: generate a 6-digit invite code for guardian-mediated
-  // redemption. The plaintext code is returned once in the response; only the
-  // hash is persisted for later redemption lookup.
-  let inviteCode: string | undefined;
-  let inviteCodeHash: string | undefined;
-
-  if (isVoice) {
-    if (!params.expectedExternalUserId) {
-      return {
-        ok: false,
-        error: "expectedExternalUserId is required for voice invites",
-      };
-    }
-    if (!isValidE164(params.expectedExternalUserId)) {
-      return {
-        ok: false,
-        error:
-          "expectedExternalUserId must be in E.164 format (e.g., +15551234567)",
-      };
-    }
-    effectiveGuardianName = resolveGuardianName();
-    if (
-      !effectiveGuardianName ||
-      effectiveGuardianName === DEFAULT_USER_REFERENCE ||
-      effectiveGuardianName === DECLINED_BY_USER_SENTINEL
-    ) {
-      effectiveGuardianName = undefined;
-    }
-    voiceCode = generateVoiceCode(6);
-    voiceCodeHash = hashVoiceCode(voiceCode);
-  } else {
-    inviteCode = generateVoiceCode(6);
-    inviteCodeHash = hashVoiceCode(inviteCode);
+/**
+ * Layer the daemon-owned presentation fields onto a gateway-minted invite
+ * payload: the share link, the guardian instruction (LLM-generated for
+ * non-voice channels), and the resolved channel handle. The gateway owns the
+ * invite row and its secrets; everything added here is display-only, derived
+ * from the one-time create response, and never persisted.
+ */
+export async function composeInvitePresentation(params: {
+  contactId?: string;
+  invite: Record<string, unknown>;
+  rawToken?: string;
+}): Promise<Record<string, unknown>> {
+  const invite = params.invite;
+  const sourceChannel =
+    typeof invite.sourceChannel === "string" ? invite.sourceChannel : "";
+  const isVoice = sourceChannel === "phone";
+  const inviteCode =
+    typeof invite.inviteCode === "string" ? invite.inviteCode : undefined;
+  if (!isVoice && !inviteCode) {
+    return invite;
   }
 
-  const { invite, rawToken } = createInvite({
-    sourceChannel: params.sourceChannel,
-    contactId: params.contactId,
-    note: params.note,
-    maxUses: params.maxUses,
-    expiresInMs: params.expiresInMs,
-    ...(isVoice
-      ? {
-          expectedExternalUserId: params.expectedExternalUserId,
-          voiceCodeHash,
-          voiceCodeDigits: 6,
-          // Mirror the contact-resolved names into the legacy columns so
-          // outbound invite calls (which still read invite.friendName /
-          // invite.guardianName) keep working without a separate lookup.
-          friendName: resolvedContactName,
-          guardianName: effectiveGuardianName,
-        }
-      : { inviteCodeHash }),
-  });
-
-  // Build invite instruction for non-voice invites via LLM generation
-  let guardianInstruction: string | undefined;
-  let channelHandle: string | undefined;
-  if (!isVoice && inviteCode) {
-    const channelId = isChannelId(params.sourceChannel)
-      ? params.sourceChannel
-      : undefined;
-    const adapter = channelId
-      ? getInviteAdapterRegistry().get(channelId)
-      : undefined;
-    if (params.sourceChannel === "telegram") {
-      const { ensureTelegramBotUsernameResolved } =
-        await import("./channel-invite-transports/telegram.js");
-      await ensureTelegramBotUsernameResolved();
-    }
-    channelHandle = adapter ? await resolveAdapterHandle(adapter) : undefined;
-    const share = buildSharePayload(params.sourceChannel, rawToken);
-    guardianInstruction = await generateInviteInstruction({
-      contactName: resolvedContactName,
-      channelType: params.sourceChannel,
-      channelHandle,
-      hasShareUrl: !!share?.url,
-      shareUrl: share?.url,
-    });
-  }
+  // The invitee's name comes from the bound contact's displayName; fall back
+  // to the gateway-stamped friendName when the local mirror lacks the contact.
+  const boundContact = params.contactId
+    ? getContact(params.contactId)
+    : undefined;
+  const resolvedContactName =
+    boundContact?.displayName?.trim() ||
+    (typeof invite.friendName === "string"
+      ? invite.friendName.trim()
+      : undefined) ||
+    undefined;
 
   if (isVoice) {
-    guardianInstruction = resolvedFirstName
+    const resolvedFirstName = resolvedContactName?.split(/\s+/)[0];
+    const guardianInstruction = resolvedFirstName
       ? `${resolvedFirstName} will need this code when they answer. Share it with them first.`
       : "Share this code with them — they'll need it when they answer the call.";
+    return { ...invite, guardianInstruction };
   }
 
-  // Voice invites must not expose the token — callers must redeem via the
-  // identity-bound voice code flow, not the generic token redemption path.
-  return {
-    ok: true,
-    data: inviteToResponse(invite, {
-      rawToken: isVoice ? undefined : rawToken,
-      voiceCode,
-      inviteCode,
-      guardianInstruction,
-      channelHandle,
-    }),
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Mint — gateway-facing projection
-//
-// The gateway owns the canonical invite lifecycle in its own DB, but token
-// generation/hashing and voice fields are assistant-owned. `mintIngressInvite`
-// runs the same `createIngressInvite` path and surfaces the raw token plus the
-// minimal projection the gateway mirrors. The raw token is returned exactly
-// once and never persisted in plaintext.
-// ---------------------------------------------------------------------------
-
-/** Minimal invite projection the gateway mirrors into its own store. */
-export interface GatewayInviteProjection {
-  id: string;
-  /** Hash of whatever code redeems this invite: token hash for token invites,
-   * voice code hash for voice/phone invites. Always non-null and mirrorable. */
-  inviteCodeHash: string;
-  sourceChannel: string;
-  contactId: string;
-  note: string | null;
-  maxUses: number;
-  expiresAt: number;
-}
-
-export interface MintInviteResult {
-  invite: InviteResponseData;
-  rawToken?: string;
-  gateway: GatewayInviteProjection;
-}
-
-export async function mintIngressInvite(
-  params: Parameters<typeof createIngressInvite>[0],
-): Promise<IngressResult<MintInviteResult>> {
-  const result = await createIngressInvite(params);
-  if (!result.ok) return result;
-
-  // The persisted row carries fields the response projection omits
-  // (inviteCodeHash); read it back to build the gateway projection.
-  const row = findById(result.data.id);
-  if (!row) {
-    return { ok: false, error: "Invite not found after mint" };
-  }
-
-  // The gateway mirrors the hash of whatever code redeems this invite. Token
-  // invites carry inviteCodeHash; voice/phone invites gate on voiceCodeHash.
-  const inviteCodeHash = row.inviteCodeHash ?? row.voiceCodeHash;
-  if (!inviteCodeHash) {
-    return { ok: false, error: "Invite is missing a redemption code hash" };
+  const channelId = isChannelId(sourceChannel) ? sourceChannel : undefined;
+  const adapter = channelId
+    ? getInviteAdapterRegistry().get(channelId)
+    : undefined;
+  if (sourceChannel === "telegram") {
+    const { ensureTelegramBotUsernameResolved } =
+      await import("./channel-invite-transports/telegram.js");
+    await ensureTelegramBotUsernameResolved();
   }
+  const channelHandle = adapter
+    ? await resolveAdapterHandle(adapter)
+    : undefined;
+  const share = buildSharePayload(sourceChannel, params.rawToken);
+  const guardianInstruction = await generateInviteInstruction({
+    contactName: resolvedContactName,
+    channelType: sourceChannel,
+    channelHandle,
+    hasShareUrl: !!share?.url,
+    shareUrl: share?.url,
+  });
 
   return {
-    ok: true,
-    data: {
-      invite: result.data,
-      rawToken: result.data.token,
-      gateway: {
-        id: row.id,
-        inviteCodeHash,
-        sourceChannel: row.sourceChannel,
-        contactId: row.contactId,
-        note: row.note,
-        maxUses: row.maxUses,
-        expiresAt: row.expiresAt,
-      },
-    },
+    ...invite,
+    ...(share ? { share } : {}),
+    ...(guardianInstruction ? { guardianInstruction } : {}),
+    ...(channelHandle ? { channelHandle } : {}),
   };
 }
 
-export async function triggerInviteCall(
-  inviteId: string,
-): Promise<IngressResult<{ callSid: string }>> {
-  if (!inviteId) return { ok: false, error: "inviteId is required" };
-  const invite = findById(inviteId);
-  if (!invite) return { ok: false, error: "Invite not found" };
-  if (invite.status !== "active")
-    return { ok: false, error: "Invite is not active" };
-  if (invite.expiresAt && invite.expiresAt <= Date.now()) {
-    markInviteExpired(invite.id);
-    return { ok: false, error: "Invite has expired" };
-  }
-  if (invite.sourceChannel !== "phone")
-    return { ok: false, error: "Only phone invites support call triggering" };
-  if (!invite.expectedExternalUserId) {
-    return { ok: false, error: "Invite is missing required voice metadata" };
+/**
+ * Place the outbound provider call for a voice invite. Invite lifecycle
+ * validation (existence, active status, expiry, phone channel) is the
+ * gateway's responsibility — it reads its canonical row and relays the
+ * resolved call fields here; the daemon only performs the provider call.
+ */
+export async function triggerInviteCall(params: {
+  phoneNumber?: string;
+  friendName?: string | null;
+  guardianName?: string | null;
+}): Promise<IngressResult<{ callSid: string }>> {
+  const phoneNumber = params.phoneNumber?.trim();
+  if (!phoneNumber) {
+    return { ok: false, error: "phoneNumber is required" };
   }
-  // Resolve the invitee's name from the bound contact's displayName.
-  // `contact_id` is NOT NULL on the invite row, so every invite is bound;
-  // an empty displayName falls through to the neutral "Hi there" greeting
-  // downstream rather than a stale free-text `friend_name` label.
-  const boundContact = getContact(invite.contactId);
-  const friendName = boundContact?.displayName?.trim() || "";
-  // Guardian label is resolved at runtime by the relay; mirror the legacy
-  // value into the session so STT hints continue to seed correctly.
-  const guardianName = invite.guardianName || resolveGuardianName() || "";
+  // An empty friendName falls through to the neutral "Hi there" greeting
+  // downstream rather than substituting the channel address.
+  const friendName = params.friendName?.trim() || "";
+  // Guardian label is resolved at runtime by the relay; mirror the value
+  // into the session so STT hints continue to seed correctly.
+  const guardianName = params.guardianName || resolveGuardianName() || "";
   const result = await startInviteCall({
-    phoneNumber: invite.expectedExternalUserId,
+    phoneNumber,
     friendName,
     guardianName,
   });
-  if (!result.ok) return { ok: false, error: result.error };
-  return { ok: true, data: { callSid: result.callSid } };
-}
-
-export async function redeemIngressInvite(params: {
-  token?: string;
-  externalUserId?: string;
-  externalChatId?: string;
-  sourceChannel?: string;
-}): Promise<
-  IngressResult<{ invite: InviteResponseData; type: RedemptionType }>
-> {
-  if (!params.token) {
-    return { ok: false, error: "token is required for redeem" };
-  }
-  if (!params.sourceChannel) {
-    return { ok: false, error: "sourceChannel is required for redeem" };
-  }
-  const outcome = await redeemInviteTyped({
-    rawToken: params.token,
-    sourceChannel: params.sourceChannel,
-    externalUserId: params.externalUserId,
-    externalChatId: params.externalChatId,
-  });
-  if (!outcome.ok) {
-    return { ok: false, error: outcome.reason };
+  if (!result.ok) {
+    return { ok: false, error: result.error };
   }
-  // Look up the invite by token hash for both outcomes (`redeemed` and
-  // `already_member`). Using findByTokenHash avoids the pagination limit of
-  // listInvites. The `type` is surfaced so the gateway can skip mirroring an
-  // `already_member` redemption (which consumes no use).
-  const inv = findByTokenHash(hashToken(params.token));
-  if (!inv) {
-    return { ok: false, error: "Invite not found after redemption" };
-  }
-  return {
-    ok: true,
-    data: { invite: inviteToResponse(inv), type: outcome.type },
-  };
-}
-
-export function redeemVoiceInviteCode(params: {
-  assistantId?: string;
-  callerExternalUserId: string;
-  sourceChannel: "phone";
-  code: string;
-}): Promise<VoiceRedemptionOutcome> {
-  return redeemVoiceInviteCodeTyped(params);
+  return { ok: true, data: { callSid: result.callSid } };
 }

package/src/runtime/local-actor-identity.test.ts

@@ -36,6 +36,7 @@ import { __resetGuardianDeliveryCacheForTest } from "../contacts/guardian-delive
 import {
   findLocalGuardianPrincipalIdFromStore,
   resolveActorPrincipalIdForLocalGuardianSync,
+  resolveDecidableGuardianPrincipalId,
   warmLocalGuardianPrincipalCache,
 } from "./local-actor-identity.js";
 
@@ -106,3 +107,40 @@ describe("warmLocalGuardianPrincipalCache", () => {
     expect(findLocalGuardianPrincipalIdFromStore()).toBe("principal-abc");
   });
 });
+
+describe("resolveDecidableGuardianPrincipalId", () => {
+  beforeEach(() => {
+    __resetGuardianDeliveryCacheForTest();
+    ipcHandlers.clear();
+  });
+
+  afterEach(() => {
+    __resetGuardianDeliveryCacheForTest();
+  });
+
+  test("a present binding principal is returned without an anchor read", async () => {
+    // No IPC handler registered: an anchor read would resolve undefined, so a
+    // "binding-1" result proves the binding principal short-circuits.
+    expect(await resolveDecidableGuardianPrincipalId("binding-1")).toBe(
+      "binding-1",
+    );
+  });
+
+  test("a null binding principal adopts the vellum anchor principal", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [vellumGuardian] }));
+
+    expect(await resolveDecidableGuardianPrincipalId(null)).toBe(
+      "principal-abc",
+    );
+  });
+
+  test("an empty-string binding principal is unresolved, never returned", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [vellumGuardian] }));
+
+    expect(await resolveDecidableGuardianPrincipalId("")).toBe("principal-abc");
+  });
+
+  test("unresolvable everywhere → undefined (caller fails closed)", async () => {
+    expect(await resolveDecidableGuardianPrincipalId(null)).toBeUndefined();
+  });
+});

package/src/runtime/local-actor-identity.ts

@@ -67,6 +67,20 @@ export async function findLocalGuardianPrincipalId(): Promise<
   return guardianForChannel(list, "vellum")?.principalId ?? undefined;
 }
 
+/**
+ * Resolve a decidable guardian principal for canonical guardian-request
+ * creation: the channel binding's principal when present, else the vellum
+ * anchor principal (the adopt/repair path for guardian rows that carry no
+ * principal). A falsy binding principal (`null` or `""`) is unresolved by
+ * contract — decisionable requests must never be created with an empty
+ * principal, so callers fail closed on `undefined`.
+ */
+export async function resolveDecidableGuardianPrincipalId(
+  bindingPrincipalId: string | null,
+): Promise<string | undefined> {
+  return bindingPrincipalId || (await findLocalGuardianPrincipalId());
+}
+
 /**
  * Eagerly warm the gateway guardian-delivery cache for the vellum channel.
  *

package/src/runtime/middleware/__tests__/rate-limiter.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, test } from "bun:test";
 import { isLoopbackAddress } from "../auth.js";
 import {
   apiRateLimiter,
+  isRateLimitExemptEndpoint,
   loopbackApiRateLimiter,
   selectAuthenticatedRateLimiter,
 } from "../rate-limiter.js";
@@ -61,3 +62,24 @@ describe("selectAuthenticatedRateLimiter", () => {
     expect(standard.limit).toBe(300);
   });
 });
+
+describe("isRateLimitExemptEndpoint", () => {
+  test("exempts the SSE stream and liveness probes", () => {
+    // Streaming: 429-ing the events stream drops it and drives a client
+    // reconnect + re-bootstrap storm, so it bypasses the per-minute limiter.
+    expect(isRateLimitExemptEndpoint("events")).toBe(true);
+    // Liveness/readiness probes must always answer.
+    expect(isRateLimitExemptEndpoint("health")).toBe(true);
+    expect(isRateLimitExemptEndpoint("healthz")).toBe(true);
+    expect(isRateLimitExemptEndpoint("readyz")).toBe(true);
+  });
+
+  test("does not exempt ordinary data endpoints", () => {
+    expect(isRateLimitExemptEndpoint("messages")).toBe(false);
+    expect(isRateLimitExemptEndpoint("conversations")).toBe(false);
+    expect(isRateLimitExemptEndpoint("home/feed")).toBe(false);
+    // Match is exact on the normalized endpoint segment, not a prefix.
+    expect(isRateLimitExemptEndpoint("events/replay")).toBe(false);
+    expect(isRateLimitExemptEndpoint("")).toBe(false);
+  });
+});

package/src/runtime/middleware/rate-limiter.ts

@@ -220,6 +220,36 @@ export function selectAuthenticatedRateLimiter(
   return isLoopbackAddress(clientIp) ? loopbackApiRateLimiter : apiRateLimiter;
 }
 
+/**
+ * `/v1/` endpoints that bypass the per-minute request rate limiter.
+ *
+ * - Liveness/readiness (`health`, `healthz`, `readyz`): cheap probes that
+ *   must always answer. The desktop app polls `/v1/health` every few seconds
+ *   and the reachability probe hits `/v1/healthz`; a 429 makes the client
+ *   treat the assistant as unreachable and reconnect harder.
+ * - SSE stream (`events`): a single long-lived streaming connection, not a
+ *   burst of discrete requests. Metering each (re)connect against the
+ *   per-minute budget is the wrong model — and 429-ing the stream drops it,
+ *   which drives a client reconnect + full re-bootstrap loop that generates
+ *   far more load than the limiter saves. The events route still enforces
+ *   auth downstream (an unauthenticated stream request is rejected there),
+ *   and daemon memory is bounded by SSE backpressure shedding and subscriber
+ *   caps rather than by this request-count limiter.
+ *
+ * The argument is the `/v1/`-stripped, trailing-slash-normalized endpoint
+ * segment (e.g. `events`, `health`) as computed by the HTTP server.
+ */
+const RATE_LIMIT_EXEMPT_ENDPOINTS = new Set([
+  "events",
+  "health",
+  "healthz",
+  "readyz",
+]);
+
+export function isRateLimitExemptEndpoint(endpoint: string): boolean {
+  return RATE_LIMIT_EXEMPT_ENDPOINTS.has(endpoint);
+}
+
 /**
  * Extract the client IP from a request. Only trusts proxy headers
  * (X-Forwarded-For, X-Real-IP) when the peer IP is loopback or private,