@vellumai/assistant 0.11.8-staging.1 → 0.11.8

package/src/api/responses/home.ts

@@ -164,14 +164,8 @@ export const FeedItemGuardianRequestSchema = z.object({
   sourceContextLabel: z.string().optional(),
   /** Permalink to the originating channel message, when derivable. */
   sourceUrl: z.string().optional(),
-  /** Web URL of the Slack guardian-DM approval card ("Open in Slack"). */
-  slackCardUrl: z.string().optional(),
-  /** slack:// deep link for the same card, preferred on devices with the app. */
-  slackCardAppUrl: z.string().optional(),
   /** Action that resolved the request, for terminal statuses. */
   decidedAction: z.string().optional(),
-  /** Display label of the decider, when the decision came from a person. */
-  decidedByLabel: z.string().optional(),
   /** ISO-8601 time the request reached its terminal status. */
   decidedAt: z.string().optional(),
   /**

package/src/config/__tests__/default-profile-catalog.test.ts

@@ -440,7 +440,7 @@ describe("resolveDefaultProfileForProvider", () => {
       expect(entry?.provider_connection).toBeUndefined();
       expect(entry?.source).toBe("managed");
     }
-    // Cost and Speed both opt fully out of reasoning.
+    // Budget and Fast both opt fully out of reasoning.
     expect(effective["cost-optimized"]?.effort).toBe("none");
     expect(effective["latency-optimized"]?.effort).toBe("none");
     expect(effective.balanced?.thinking?.enabled).toBe(true);

package/src/config/call-site-defaults.ts

@@ -133,7 +133,7 @@ export const CALL_SITE_DEFAULTS: Record<LLMCallSite, CallSiteDefaultConfig> = {
   // default-profile-catalog.ts): managed installs get the pinned latency model,
   // BYOK installs resolve their own provider's latency model through the intent
   // table rather than a model id they may hold no credential for. The profile
-  // is user-facing ("Speed"), so a user edit to it moves this call site too.
+  // is user-facing ("Fast"), so a user edit to it moves this call site too.
   voiceProgressNarration: {
     profile: "latency-optimized",
     effort: "low",

package/src/config/default-profile-catalog.ts

@@ -117,7 +117,7 @@ const VELLUM_PROFILE_IMPLS: ProfileImpls = {
     model: "accounts/fireworks/models/deepseek-v4-flash-0731",
     provider: "vellum",
     source: "managed",
-    label: "Cost",
+    label: "Budget",
     // Tier intent only - never name the concrete model here. Clients
     // surface the live model beside the description, so a model name in
     // this copy would go stale the moment the pin moves.
@@ -150,7 +150,7 @@ const VELLUM_PROFILE_IMPLS: ProfileImpls = {
     model: "gpt-5.6-luna",
     provider: "vellum",
     source: "managed",
-    label: "Speed",
+    label: "Fast",
     description: "Fastest responses, with reasoning turned off",
     fallbackProfile: FALLBACK_PROFILE_BY_KEY["latency-optimized"],
     maxTokens: 8192,
@@ -211,10 +211,10 @@ const BACKUP_PROFILE_IMPLS: Record<BackupProfileKey, DefaultProfileTemplate> = {
     model: "gemini-3.1-flash-lite",
     provider: "vellum",
     source: "managed",
-    label: "Cost Backup",
-    description: "Automatic backup for the Cost profile",
+    label: "Budget Backup",
+    description: "Automatic backup for the Budget profile",
     maxTokens: 8192,
-    // Explicit reasoning opt-out, matching the primary Cost profile: OpenAI-
+    // Explicit reasoning opt-out, matching the primary Budget profile: OpenAI-
     // compat APIs default reasoning to "medium" when the field is omitted,
     // and effort-driven providers encode disabled thinking through this same
     // knob (see DISABLED_THINKING_USES_EFFORT_PROVIDERS in
@@ -229,8 +229,8 @@ const BACKUP_PROFILE_IMPLS: Record<BackupProfileKey, DefaultProfileTemplate> = {
     model: "claude-haiku-4-5-20251001",
     provider: "vellum",
     source: "managed",
-    label: "Speed Backup",
-    description: "Automatic backup for the Speed profile",
+    label: "Fast Backup",
+    description: "Automatic backup for the Fast profile",
     maxTokens: 8192,
     effort: "low",
     thinking: { enabled: false, streamThinking: false },
@@ -286,7 +286,7 @@ function managedProfileImpl(key: DefaultProfileKey): DefaultProfileTemplate {
  * `chatgpt-subscription` row via `resolveRoutingIdentity` with no pinned
  * connection. Models are pinned (never intents): the intent tables are
  * keyed by concrete dispatch providers, and the Codex endpoint serves only
- * `CODEX_SUBSCRIPTION_MODEL_IDS`. Cost and Speed are identical
+ * `CODEX_SUBSCRIPTION_MODEL_IDS`. Budget and Fast are identical
  * implementations here: the subscription serves no tier cheaper or faster
  * than luna, and both profiles advertise reasoning off.
  */
@@ -319,7 +319,7 @@ const CHATGPT_PROFILE_IMPLS: ProfileImpls = {
     model: "gpt-5.6-luna",
     provider: "chatgpt",
     source: "managed",
-    label: "Cost",
+    label: "Budget",
     description: "Cheapest responses, for high-volume work",
     maxTokens: 8192,
     effort: "none",
@@ -330,7 +330,7 @@ const CHATGPT_PROFILE_IMPLS: ProfileImpls = {
     model: "gpt-5.6-luna",
     provider: "chatgpt",
     source: "managed",
-    label: "Speed",
+    label: "Fast",
     description: "Fastest responses, with reasoning turned off",
     maxTokens: 8192,
     // Explicit reasoning opt-out, matching the other columns: this profile
@@ -381,7 +381,7 @@ const BYOK_PROFILE_IMPLS: Record<
   "cost-optimized": {
     intent: "cost-optimized",
     source: "user",
-    label: "Cost",
+    label: "Budget",
     description: "Cheapest responses, for high-volume work",
     maxTokens: 8192,
     effort: "none",
@@ -391,7 +391,7 @@ const BYOK_PROFILE_IMPLS: Record<
   "latency-optimized": {
     intent: "latency-optimized",
     source: "user",
-    label: "Speed",
+    label: "Fast",
     description: "Fastest responses, with reasoning turned off",
     maxTokens: 8192,
     effort: "none",

package/src/config/default-profile-names.ts

@@ -11,8 +11,8 @@
  *
  * A key is an on-disk contract: `llm.callSites.*.profile`, `activeProfile`,
  * mix arms and schedule pins all reference it, so a key is fixed regardless of
- * the label its profile carries. `cost-optimized` is labelled "Cost" and
- * `latency-optimized` is labelled "Speed" (see `default-profile-catalog.ts`).
+ * the label its profile carries. `cost-optimized` is labelled "Budget" and
+ * `latency-optimized` is labelled "Fast" (see `default-profile-catalog.ts`).
  *
  * `latency-optimized` also backs the live-voice front model, which is why it
  * exists as a profile rather than a raw model pin on the call site: a pin

package/src/email/byo-email-credential.test.ts

@@ -0,0 +1,39 @@
+/**
+ * A stored or deleted BYO email provider credential must drop the readiness
+ * service's cached email snapshot: the BYO check lives in the TTL-cached
+ * remote bucket, so without the invalidation the channel badge serves the
+ * pre-write verdict for the rest of the TTL.
+ */
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+let invalidatedChannels: string[];
+
+mock.module("../daemon/handlers/config-channels.js", () => ({
+  getReadinessService: () => ({
+    invalidateChannel: (channel: string) => {
+      invalidatedChannels.push(channel);
+    },
+  }),
+}));
+
+import { invalidateEmailReadinessForByoCredential } from "./byo-email-credential.js";
+
+describe("invalidateEmailReadinessForByoCredential", () => {
+  beforeEach(() => {
+    invalidatedChannels = [];
+  });
+
+  test("invalidates the email channel for each BYO provider", async () => {
+    await invalidateEmailReadinessForByoCredential("resend");
+    await invalidateEmailReadinessForByoCredential("mailgun");
+
+    expect(invalidatedChannels).toEqual(["email", "email"]);
+  });
+
+  test("leaves other services' credentials alone", async () => {
+    await invalidateEmailReadinessForByoCredential("telegram");
+    await invalidateEmailReadinessForByoCredential("slack_channel");
+
+    expect(invalidatedChannels).toEqual([]);
+  });
+});

package/src/email/byo-email-credential.ts

@@ -0,0 +1,76 @@
+/**
+ * "Your own" (BYO) email providers: the assistant sends and receives email
+ * through the user's own provider account instead of a platform-managed
+ * inbox. Configuration is the provider's stored `api_key` credential;
+ * inbound arrives through the gateway's per-provider webhook routes
+ * (`gateway/src/http/routes/resend-webhook.ts`, `mailgun-webhook.ts`).
+ *
+ * The service ids here are the credential-store service names those webhook
+ * routes and the web client's BYO setup read (`EMAIL_BYO_PROVIDERS` in
+ * `clients/web/src/lib/provider-catalogs.ts` mirrors this list). Adding a
+ * provider means a new gateway webhook route and a web catalog entry, so
+ * extend all three together.
+ */
+
+import { credentialKey } from "../security/credential-key.js";
+import { getSecureKeyAsync } from "../security/secure-keys.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("byo-email-credential");
+
+export const BYO_EMAIL_CREDENTIAL_SERVICES = ["resend", "mailgun"] as const;
+
+export type ByoEmailCredentialService =
+  (typeof BYO_EMAIL_CREDENTIAL_SERVICES)[number];
+
+export function isByoEmailCredentialService(
+  service: string,
+): service is ByoEmailCredentialService {
+  return BYO_EMAIL_CREDENTIAL_SERVICES.some((s) => s === service);
+}
+
+/**
+ * The first BYO email provider whose API key is stored, or `undefined` when
+ * none is configured. Credential presence is the configuration claim, the
+ * same standard the other channels' readiness checks apply to their tokens.
+ */
+export async function resolveConfiguredByoEmailService(): Promise<
+  ByoEmailCredentialService | undefined
+> {
+  for (const service of BYO_EMAIL_CREDENTIAL_SERVICES) {
+    if (await getSecureKeyAsync(credentialKey(service, "api_key"))) {
+      return service;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * A stored or deleted BYO email provider key changes the email channel's
+ * readiness verdict, and that check lives in the readiness service's
+ * TTL-cached remote bucket; drop the cached snapshot so the next readiness
+ * read re-evaluates instead of serving the pre-write answer for the rest of
+ * the TTL. Called from the credential write and delete paths. Best-effort:
+ * the credential change already succeeded, and a missed invalidation
+ * self-heals when the TTL lapses.
+ */
+export async function invalidateEmailReadinessForByoCredential(
+  service: string,
+): Promise<void> {
+  if (!isByoEmailCredentialService(service)) {
+    return;
+  }
+  try {
+    // Lazily imported: the readiness service sits in the daemon handler
+    // graph, which credential writers (CLI, plugin API) should not load
+    // unless a BYO email key actually changed.
+    const { getReadinessService } =
+      await import("../daemon/handlers/config-channels.js");
+    getReadinessService().invalidateChannel("email");
+  } catch (err) {
+    log.warn(
+      { err, service },
+      "Credential change succeeded, but email readiness invalidation failed",
+    );
+  }
+}

package/src/email/registered-inbox.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Tests for the shared registered-inbox reader: the single answer to "does
+ * this assistant have a managed inbox?", read from the platform
+ * email-addresses API (the only writer of managed registrations).
+ */
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mocks, set up before importing the module under test
+// ---------------------------------------------------------------------------
+
+let mockPlatformAssistantId: string | null;
+let mockResponse: { ok: boolean; status: number; body: unknown };
+let mockFetchThrows: boolean;
+let mockCreateThrows: boolean;
+let fetchCallCount: number;
+
+mock.module("../platform/client.js", () => ({
+  VellumPlatformClient: {
+    create: async () => {
+      if (mockCreateThrows) {
+        throw new Error("credential store unavailable");
+      }
+      return clientStub();
+    },
+  },
+}));
+
+const clientStub = () => ({
+  platformAssistantId: mockPlatformAssistantId,
+  fetch: async (_path: string) => {
+    fetchCallCount += 1;
+    if (mockFetchThrows) {
+      throw new Error("platform unreachable");
+    }
+    return {
+      ok: mockResponse.ok,
+      status: mockResponse.status,
+      json: async () => mockResponse.body,
+    };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Import after mocks
+// ---------------------------------------------------------------------------
+
+import { VellumPlatformClient } from "../platform/client.js";
+import {
+  invalidateRegisteredInboxCache,
+  listEmailAddresses,
+  resolveRegisteredInbox,
+} from "./registered-inbox.js";
+
+async function testClient(): Promise<VellumPlatformClient> {
+  const client = await VellumPlatformClient.create();
+  if (!client) {
+    throw new Error("mocked create returned null");
+  }
+  return client;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("resolveRegisteredInbox", () => {
+  beforeEach(() => {
+    mockPlatformAssistantId = "assistant-test-id";
+    mockResponse = { ok: true, status: 200, body: { count: 0, results: [] } };
+    mockFetchThrows = false;
+    mockCreateThrows = false;
+    fetchCallCount = 0;
+    invalidateRegisteredInboxCache();
+  });
+
+  test("unavailable when client creation itself throws", async () => {
+    mockCreateThrows = true;
+
+    const state = await resolveRegisteredInbox();
+
+    expect(state).toEqual({
+      status: "unavailable",
+      detail: "credential store unavailable",
+    });
+  });
+
+  test("registered when the platform lists an address", async () => {
+    mockResponse = {
+      ok: true,
+      status: 200,
+      body: {
+        count: 1,
+        results: [{ id: "addr-1", address: "assistant@example.com" }],
+      },
+    };
+
+    const state = await resolveRegisteredInbox();
+
+    expect(state).toEqual({
+      status: "registered",
+      address: "assistant@example.com",
+    });
+  });
+
+  test("none when the platform lists no addresses", async () => {
+    const state = await resolveRegisteredInbox();
+
+    expect(state).toEqual({ status: "none" });
+  });
+
+  test("no_platform when platform credentials are missing", async () => {
+    mockPlatformAssistantId = null;
+
+    const state = await resolveRegisteredInbox();
+
+    expect(state).toEqual({ status: "no_platform" });
+  });
+
+  test("unavailable on a non-ok platform response", async () => {
+    mockResponse = { ok: false, status: 503, body: { detail: "boom" } };
+
+    const state = await resolveRegisteredInbox();
+
+    expect(state).toEqual({ status: "unavailable", detail: "HTTP 503" });
+  });
+
+  test("unavailable when the platform fetch throws", async () => {
+    mockFetchThrows = true;
+
+    const state = await resolveRegisteredInbox();
+
+    expect(state).toEqual({
+      status: "unavailable",
+      detail: "platform unreachable",
+    });
+  });
+
+  test("unavailable on an unexpected response shape", async () => {
+    mockResponse = { ok: true, status: 200, body: { results: "not-a-list" } };
+
+    const state = await resolveRegisteredInbox();
+
+    expect(state).toEqual({
+      status: "unavailable",
+      detail: "unexpected response shape",
+    });
+  });
+
+  test("serves the cached answer within the TTL", async () => {
+    mockResponse = {
+      ok: true,
+      status: 200,
+      body: { count: 1, results: [{ id: "addr-1", address: "hi@bot" }] },
+    };
+    await resolveRegisteredInbox();
+
+    // A changed platform answer is not observed until the cache is dropped.
+    mockResponse = { ok: true, status: 200, body: { count: 0, results: [] } };
+    const state = await resolveRegisteredInbox();
+
+    expect(state).toEqual({ status: "registered", address: "hi@bot" });
+    expect(fetchCallCount).toBe(1);
+  });
+
+  test("fresh bypasses the cache and updates it", async () => {
+    await resolveRegisteredInbox();
+    mockResponse = {
+      ok: true,
+      status: 200,
+      body: { count: 1, results: [{ id: "addr-1", address: "hi@bot" }] },
+    };
+
+    const fresh = await resolveRegisteredInbox({ fresh: true });
+    const cached = await resolveRegisteredInbox();
+
+    expect(fresh).toEqual({ status: "registered", address: "hi@bot" });
+    expect(cached).toEqual({ status: "registered", address: "hi@bot" });
+    expect(fetchCallCount).toBe(2);
+  });
+
+  test("invalidate drops the cached answer", async () => {
+    await resolveRegisteredInbox();
+    invalidateRegisteredInboxCache();
+    await resolveRegisteredInbox();
+
+    expect(fetchCallCount).toBe(2);
+  });
+
+  test("unavailable is not cached, so the next call retries", async () => {
+    mockFetchThrows = true;
+    await resolveRegisteredInbox();
+
+    mockFetchThrows = false;
+    mockResponse = {
+      ok: true,
+      status: 200,
+      body: { count: 1, results: [{ id: "addr-1", address: "hi@bot" }] },
+    };
+    const state = await resolveRegisteredInbox();
+
+    expect(state).toEqual({ status: "registered", address: "hi@bot" });
+  });
+});
+
+describe("listEmailAddresses", () => {
+  beforeEach(() => {
+    mockPlatformAssistantId = "assistant-test-id";
+    mockResponse = { ok: true, status: 200, body: { count: 0, results: [] } };
+    mockFetchThrows = false;
+    mockCreateThrows = false;
+    fetchCallCount = 0;
+  });
+
+  test("a 200 without results is a failed listing, not an empty one", async () => {
+    mockResponse = { ok: true, status: 200, body: {} };
+
+    const list = await listEmailAddresses(await testClient());
+
+    expect(list).toEqual({ ok: false, detail: "unexpected response shape" });
+  });
+
+  test("a positive count with no rows is a failed listing", async () => {
+    mockResponse = { ok: true, status: 200, body: { count: 2, results: [] } };
+
+    const list = await listEmailAddresses(await testClient());
+
+    expect(list).toEqual({
+      ok: false,
+      detail: "listing reported 2 addresses but returned none",
+    });
+  });
+
+  test("returns the platform's rows with ids", async () => {
+    mockResponse = {
+      ok: true,
+      status: 200,
+      body: { results: [{ id: "addr-1", address: "user@example.com" }] },
+    };
+
+    const list = await listEmailAddresses(await testClient());
+
+    expect(list).toEqual({
+      ok: true,
+      addresses: [{ id: "addr-1", address: "user@example.com" }],
+    });
+  });
+
+  test("carries the platform's status on a non-ok response", async () => {
+    mockResponse = { ok: false, status: 503, body: { detail: "boom" } };
+
+    const list = await listEmailAddresses(await testClient());
+
+    expect(list).toEqual({ ok: false, status: 503, detail: "HTTP 503" });
+  });
+
+  test("fails without a status when the fetch throws", async () => {
+    mockFetchThrows = true;
+
+    const list = await listEmailAddresses(await testClient());
+
+    expect(list).toEqual({ ok: false, detail: "platform unreachable" });
+  });
+
+  test("fails on an unexpected response shape", async () => {
+    mockResponse = { ok: true, status: 200, body: { results: [{ id: 7 }] } };
+
+    const list = await listEmailAddresses(await testClient());
+
+    expect(list).toEqual({ ok: false, detail: "unexpected response shape" });
+  });
+});

package/src/email/registered-inbox.ts

@@ -0,0 +1,169 @@
+/**
+ * The one place that answers "does this assistant have a managed inbox?".
+ *
+ * Managed email registration lives on the Vellum platform: the
+ * `/v1/assistants/:id/email-addresses/` API is the only writer and the only
+ * source of truth. Nothing about a registration lands in workspace config, so
+ * any reader that wants the inbox address has to ask the platform. Every
+ * consumer of the listing (the email readiness probe, the email invite
+ * adapter, the channel-availability route, the email management routes, and
+ * verification email delivery) reads through this module so they cannot
+ * drift onto different answers.
+ *
+ * `unavailable` is distinct from `none` for the same reason the readiness
+ * service separates "failed" from "indeterminate": an unreachable platform is
+ * not evidence that no inbox exists, and reporting it as one turns every
+ * platform blip into a "set up email" prompt.
+ */
+
+import { z } from "zod";
+
+import { VellumPlatformClient } from "../platform/client.js";
+
+export type RegisteredInboxState =
+  /** The platform holds a registered inbox address for this assistant. */
+  | { status: "registered"; address: string }
+  /** The platform answered: no inbox is registered. */
+  | { status: "none" }
+  /** No platform credentials, so no managed inbox can exist. */
+  | { status: "no_platform" }
+  /** The platform could not be asked; nothing is known either way. */
+  | { status: "unavailable"; detail: string };
+
+/** One row of the platform's email-address listing. */
+export interface RegisteredEmailAddress {
+  id: string;
+  address: string;
+}
+
+export type EmailAddressListResult =
+  | { ok: true; addresses: RegisteredEmailAddress[] }
+  /** The platform could not be asked or answered unusably. */
+  | { ok: false; status?: number; detail: string };
+
+/**
+ * Validated rather than cast: the response crosses a runtime boundary, and a
+ * shape drift should read as a failed listing (nothing established), not as a
+ * confidently wrong answer. Unknown keys are ignored, since the platform adds
+ * fields over time.
+ */
+const EmailAddressListSchema = z.object({
+  count: z.number().optional(),
+  // Required: the platform's paginated listing always carries `results`, so
+  // a 200 without it is shape drift and must read as a failed listing, never
+  // as "no inbox".
+  results: z.array(z.object({ id: z.string(), address: z.string() })),
+});
+
+/**
+ * Fetch the platform's email-address listing for the caller's own client.
+ *
+ * The seam every consumer of the listing shares: the readiness resolver
+ * below, the email register/unregister/status/send routes, and verification
+ * email delivery. Takes the caller's client rather than creating one so a
+ * route that already authenticated (and already knows how to report a
+ * missing platform connection) keeps its own error semantics.
+ */
+export async function listEmailAddresses(
+  client: VellumPlatformClient,
+): Promise<EmailAddressListResult> {
+  let response: Response;
+  try {
+    response = await client.fetch(
+      `/v1/assistants/${client.platformAssistantId}/email-addresses/`,
+    );
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return { ok: false, detail };
+  }
+
+  if (!response.ok) {
+    return {
+      ok: false,
+      status: response.status,
+      detail: `HTTP ${response.status}`,
+    };
+  }
+
+  const parsed = EmailAddressListSchema.safeParse(
+    await response.json().catch(() => null),
+  );
+  if (!parsed.success) {
+    return { ok: false, detail: "unexpected response shape" };
+  }
+
+  const { count, results: addresses } = parsed.data;
+  if (addresses.length === 0 && (count ?? 0) > 0) {
+    // A positive count with no rows is drift, not an empty listing: treating
+    // it as "no inbox" would recreate the false Not connected verdict.
+    return {
+      ok: false,
+      detail: `listing reported ${count} addresses but returned none`,
+    };
+  }
+
+  return { ok: true, addresses };
+}
+
+/**
+ * Matches the readiness service's remote-check TTL: the cache exists so the
+ * invite-adapter enrichment on the readiness poll (every 15s per client) does
+ * not turn into a platform request per poll, and registration changes made
+ * through the daemon invalidate it explicitly.
+ */
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+let cache: { state: RegisteredInboxState; fetchedAt: number } | null = null;
+
+/** Drop the cached answer; call after registering or releasing an inbox. */
+export function invalidateRegisteredInboxCache(): void {
+  cache = null;
+}
+
+/**
+ * Resolve the managed inbox state, serving a cached answer within
+ * {@link CACHE_TTL_MS} unless `fresh` demands a live read. `unavailable` is
+ * never cached: a platform blip should heal on the next call, not pin the
+ * unknown state for the TTL.
+ */
+export async function resolveRegisteredInbox(
+  options: { fresh?: boolean } = {},
+): Promise<RegisteredInboxState> {
+  if (!options.fresh && cache && Date.now() - cache.fetchedAt < CACHE_TTL_MS) {
+    return cache.state;
+  }
+
+  const state = await fetchRegisteredInbox();
+  if (state.status === "unavailable") {
+    return state;
+  }
+  cache = { state, fetchedAt: Date.now() };
+  return state;
+}
+
+async function fetchRegisteredInbox(): Promise<RegisteredInboxState> {
+  // Creation resolves the managed-proxy context and the credential store,
+  // either of which can reject; a backend blip there is "could not ask",
+  // not an error the caller should surface as a failed request.
+  let client: VellumPlatformClient | null;
+  try {
+    client = await VellumPlatformClient.create();
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return { status: "unavailable", detail };
+  }
+  if (!client?.platformAssistantId) {
+    return { status: "no_platform" };
+  }
+
+  const list = await listEmailAddresses(client);
+  if (!list.ok) {
+    return { status: "unavailable", detail: list.detail };
+  }
+
+  const address = list.addresses[0]?.address;
+  if (typeof address === "string" && address.length > 0) {
+    return { status: "registered", address };
+  }
+  return { status: "none" };
+}