@vellumai/assistant 0.11.5 → 0.11.6-staging.1

package/src/runtime/routes/inference-profiles-routes.ts

@@ -18,6 +18,7 @@
 
 import { z } from "zod";
 
+import { validateInferenceProfileConfig } from "../../api/constants/profile-config-validation.js";
 import {
   getEffectiveProfilesForProvider,
   MANAGED_PROFILE_NAMES,
@@ -34,6 +35,7 @@ import {
 } from "../../config/schemas/llm.js";
 import { getDb } from "../../persistence/db-connection.js";
 import {
+  catalogProviderForProfile,
   resolveEntryProviderKind,
   writableProfileProviderIssue,
 } from "../../providers/connection-resolution.js";
@@ -45,7 +47,10 @@ import {
   isUnavailable,
 } from "../../providers/inference/connection-availability.js";
 import { getConnection } from "../../providers/inference/connections.js";
+import { probeInferenceProfile } from "../../providers/inference/profile-probe.js";
 import {
+  catalogContextWindowTokens,
+  catalogMaxOutputTokens,
   getModelDisplayName,
   isModelInCatalog,
 } from "../../providers/model-catalog.js";
@@ -82,6 +87,18 @@ const availabilitySchema = z
   })
   .meta({ id: "ProfileConnectionAvailability" });
 
+/**
+ * Static config problem with the stored entry itself (unknown model,
+ * impossible token budget), distinct from `availability` which judges the
+ * connection and credential behind it. Absent when the config checks out.
+ */
+const profileConfigIssueSchema = z
+  .object({
+    code: z.enum(["model_unknown", "over_output_cap", "no_input_room"]),
+    message: z.string(),
+  })
+  .meta({ id: "InferenceProfileConfigIssue" });
+
 const profileSummarySchema = z
   .object({
     name: z.string(),
@@ -93,6 +110,7 @@ const profileSummarySchema = z
     provider_connection: z.string().optional(),
     /** Null when the profile has no provider to judge (e.g. mix profiles). */
     availability: availabilitySchema.nullable(),
+    config_issue: profileConfigIssueSchema.optional(),
   })
   .meta({ id: "InferenceProfileSummary" });
 
@@ -101,6 +119,7 @@ const profileDetailSchema = z
     name: z.string(),
     entry: z.record(z.string(), z.unknown()),
     availability: availabilitySchema.nullable(),
+    config_issue: profileConfigIssueSchema.optional(),
   })
   .meta({ id: "InferenceProfileDetail" });
 
@@ -119,6 +138,17 @@ const profileWriteResultSchema = z
   })
   .meta({ id: "InferenceProfileWriteResult" });
 
+const profileCheckSchema = z
+  .object({
+    ok: z.boolean(),
+    blame: z.enum(["profile", "provider", "transient", "unknown"]).optional(),
+    reason: z.string().optional(),
+    detail: z.string().optional(),
+    connection: z.string().optional(),
+    message: z.string().optional(),
+  })
+  .meta({ id: "InferenceProfileCheck" });
+
 const createRequestSchema = z.object({
   name: z.string().min(1),
   provider: z.string().min(1),
@@ -160,63 +190,147 @@ function assertValidProvider(provider: string): void {
 }
 
 /**
- * Validate a (provider, model) pair against the catalog. Returns warnings
- * (never throws) when `allowUnlisted`; throws otherwise for an uncataloged
- * model. An uncataloged model always warns, whether or not it is allowed.
+ * Why a (provider, model, connection) triple cannot be vouched for, or null.
+ * The same reach checks dispatch applies: routing identities against their
+ * routing table, entry names against their row's dispatchable kind, vendor
+ * ids against the catalog, with the named connection's advertised model list
+ * authoritative for models the code-owned catalog doesn't know (a custom
+ * endpoint declares its own models at connection-create time).
  */
-function validateModel(
+function modelReachIssue(
   provider: string,
   model: string,
-  allowUnlisted: boolean,
   connectionName?: string,
-): string[] {
-  // Routing identities key no catalog entries; they validate against their
-  // route's actual reach — the same checks dispatch applies per-request.
-  // allowUnlisted deliberately does not apply: the routing table ships in
-  // this build, so an unroutable pair fails every request, and the schema
-  // strips it on the next config read.
+): { identity: boolean; catalogProvider: string; message: string } | null {
   if (ROUTING_IDENTITY_PROVIDERS.has(provider)) {
     const issue = routingIdentityModelIssue(provider, model);
-    if (issue) {
-      throw new BadRequestError(
-        `${issue} Pick a model this route serves, or a concrete provider.`,
-      );
-    }
-    return [];
+    return issue
+      ? { identity: true, catalogProvider: provider, message: issue }
+      : null;
   }
-  // An entry-name provider validates against its row's dispatchable kind,
-  // the same translation dispatch uses; the entry itself also serves as the
-  // model-list connection for custom endpoints below.
   const entryKind = resolveEntryProviderKind(provider, model);
   const catalogProvider = entryKind ?? provider;
   if (isModelInCatalog(catalogProvider, model)) {
-    return [];
+    return null;
   }
-  // The named connection's advertised model list is authoritative for models
-  // the code-owned catalog doesn't know — a custom (openai-compatible)
-  // endpoint declares its own models at connection-create time.
   const modelListConnection =
     connectionName ?? (entryKind !== null ? provider : undefined);
   if (modelListConnection) {
     const connection = getConnection(getDb(), modelListConnection);
     if (connection?.models?.some((m) => m.id === model)) {
-      return [];
+      return null;
     }
   }
+  return {
+    identity: false,
+    catalogProvider,
+    message: `Model "${model}" is not in the catalog for provider "${catalogProvider}".`,
+  };
+}
+
+/**
+ * Validate a (provider, model) pair against the catalog. Returns warnings
+ * (never throws) when `allowUnlisted`; throws otherwise for an uncataloged
+ * model. An uncataloged model always warns, whether or not it is allowed.
+ */
+function validateModel(
+  provider: string,
+  model: string,
+  allowUnlisted: boolean,
+  connectionName?: string,
+): string[] {
+  const issue = modelReachIssue(provider, model, connectionName);
+  if (!issue) {
+    return [];
+  }
+  // allowUnlisted deliberately does not apply to routing identities: the
+  // routing table ships in this build, so an unroutable pair fails every
+  // request, and the schema strips it on the next config read.
+  if (issue.identity) {
+    throw new BadRequestError(
+      `${issue.message} Pick a model this route serves, or a concrete provider.`,
+    );
+  }
   if (!allowUnlisted) {
     const remedy =
-      catalogProvider === "openai-compatible"
+      issue.catalogProvider === "openai-compatible"
         ? `Pass allowUnlisted to create it anyway, or declare the model on the connection ` +
           `("assistant inference providers update <name> --model ${model}").`
         : `Pass allowUnlisted to create it anyway, or run ` +
           `"assistant inference models list --provider ${provider}" to see valid ids.`;
-    throw new BadRequestError(
-      `Model "${model}" is not in the catalog for provider "${catalogProvider}". ${remedy}`,
+    throw new BadRequestError(`${issue.message} ${remedy}`);
+  }
+  return [`${issue.message} Created anyway (allowUnlisted).`];
+}
+
+/**
+ * Static config verdict for a stored profile: the model-reach and
+ * token-budget judgments the write routes enforce, recomputed over the
+ * entry so rows that predate validation (or were written through the
+ * generic config escape hatch) surface their problem in listings. Cheap
+ * and offline; the live probe covers what only a request can prove. Mix
+ * arms are judged on their own rows, and managed bodies are code-owned.
+ */
+function profileConfigIssue(record: Record<string, unknown>): {
+  code: "model_unknown" | "over_output_cap" | "no_input_room";
+  message: string;
+} | null {
+  if (record.mix != null || record.source === "managed") {
+    return null;
+  }
+  const provider =
+    typeof record.provider === "string" ? record.provider : undefined;
+  const model = typeof record.model === "string" ? record.model : undefined;
+  if (!provider || !model) {
+    // A missing provider/model is availability's `incomplete` verdict.
+    return null;
+  }
+  // A stored allowUnlisted marker records that catalog absence was accepted
+  // deliberately at write time; the live probe is the check for those.
+  if (record.allowUnlisted !== true) {
+    const reach = modelReachIssue(
+      provider,
+      model,
+      typeof record.provider_connection === "string"
+        ? record.provider_connection
+        : undefined,
     );
+    if (reach) {
+      return { code: "model_unknown", message: reach.message };
+    }
+  }
+  if (typeof record.maxTokens === "number") {
+    const budget = maxTokensBudgetIssue(provider, model, record.maxTokens);
+    if (budget) {
+      return { code: budget.code, message: budget.message };
+    }
   }
-  return [
-    `Model "${model}" is not in the catalog for provider "${catalogProvider}"; created anyway (allowUnlisted).`,
-  ];
+  return null;
+}
+
+/**
+ * The shared token-budget judgment over a (provider, model, maxTokens)
+ * triple with the catalog-provider translation applied. Null when the budget
+ * passes or the catalog knows nothing to judge against. One implementation
+ * for the write routes and the listing verdict so the two cannot drift.
+ */
+function maxTokensBudgetIssue(
+  provider: string,
+  model: string,
+  maxTokens: number,
+): ReturnType<typeof validateInferenceProfileConfig> {
+  const catalogProvider = catalogProviderForProfile(provider, model);
+  if (catalogProvider === null) {
+    return null;
+  }
+  return validateInferenceProfileConfig({
+    maxTokens,
+    modelMaxOutputTokens: catalogMaxOutputTokens(catalogProvider, model),
+    modelContextWindowTokens: catalogContextWindowTokens(
+      catalogProvider,
+      model,
+    ),
+  });
 }
 
 function assertConnectionExists(name: string): void {
@@ -373,6 +487,27 @@ function validateProfileEntry(entry: Record<string, unknown>): void {
   }
 }
 
+/**
+ * Reject an explicit `maxTokens` the catalog can prove impossible for the
+ * model (over its output cap, or reserving the whole context window so no
+ * input fits). Judged against the same catalog-provider translation
+ * `validateModel` uses; models the catalog does not know are left to the
+ * live probe.
+ */
+function assertSaneMaxTokens(
+  provider: string,
+  model: string,
+  maxTokens: number | undefined,
+): void {
+  if (maxTokens === undefined) {
+    return;
+  }
+  const issue = maxTokensBudgetIssue(provider, model, maxTokens);
+  if (issue) {
+    throw new BadRequestError(issue.message);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -386,6 +521,7 @@ async function handleListProfiles() {
   const profiles = await Promise.all(
     Object.entries(effective).map(async ([name, entry]) => {
       const record = entry as Record<string, unknown>;
+      const configIssue = profileConfigIssue(record);
       return {
         name,
         label: typeof record.label === "string" ? record.label : null,
@@ -397,6 +533,7 @@ async function handleListProfiles() {
           ? { provider_connection: record.provider_connection }
           : {}),
         availability: await computeProfileAvailability(record),
+        ...(configIssue ? { config_issue: configIssue } : {}),
       };
     }),
   );
@@ -418,10 +555,12 @@ async function handleGetProfile({ pathParams = {} }: RouteHandlerArgs) {
     throw new NotFoundError(`Profile "${name}" not found.`);
   }
   const record = entry as Record<string, unknown>;
+  const configIssue = profileConfigIssue(record);
   return {
     name,
     entry: record,
     availability: await computeProfileAvailability(record),
+    ...(configIssue ? { config_issue: configIssue } : {}),
   };
 }
 
@@ -456,12 +595,19 @@ async function handleCreateProfile({ body = {} }: RouteHandlerArgs) {
     input.allowUnlisted ?? false,
     input.connection,
   );
+  assertSaneMaxTokens(input.provider, input.model, input.maxTokens);
 
   const entry: Record<string, unknown> = {
     ...fragmentFromBody(body as Record<string, unknown>),
     provider: input.provider,
     model: input.model,
     source: "user",
+    // `warnings` here can only be validateModel's unlisted verdict (the
+    // availability warning pushes later), so its presence is exactly the
+    // deliberate allowUnlisted acceptance the listing verdict must honor.
+    ...(input.allowUnlisted && warnings.length > 0
+      ? { allowUnlisted: true }
+      : {}),
   };
   // Pickers render the label, so a label-less profile shows its raw config
   // key (e.g. "gemini-latest"). Default it to the model's human-readable
@@ -585,6 +731,24 @@ async function handleUpdateProfile({
       nextConnection,
     );
   }
+  // Gated on the fields that feed the judgment, mirroring the availability
+  // guard: metadata-only edits must not start rejecting a stored budget.
+  if (
+    (input.maxTokens !== undefined ||
+      input.model !== undefined ||
+      input.provider !== undefined) &&
+    typeof nextProvider === "string" &&
+    typeof nextModel === "string"
+  ) {
+    assertSaneMaxTokens(
+      nextProvider,
+      nextModel,
+      input.maxTokens ??
+        (typeof existing.maxTokens === "number"
+          ? existing.maxTokens
+          : undefined),
+    );
+  }
 
   const merged: Record<string, unknown> = {
     ...existing,
@@ -594,6 +758,17 @@ async function handleUpdateProfile({
     source:
       existing.source === "managed" ? "user" : (existing.source ?? "user"),
   };
+  // Keep the allowUnlisted marker faithful to the pair being stored: stamp
+  // it on a deliberate unlisted acceptance (warnings can only be the
+  // unlisted verdict here), and drop a stale one when the pair is now
+  // vouched for. Untouched pairs keep their stored marker.
+  if (input.provider !== undefined || input.model !== undefined) {
+    if (input.allowUnlisted && warnings.length > 0) {
+      merged.allowUnlisted = true;
+    } else if (warnings.length === 0) {
+      delete merged.allowUnlisted;
+    }
+  }
   validateProfileEntry(merged);
 
   // The availability guard runs only when the write touches the fields that
@@ -632,6 +807,14 @@ async function handleUpdateProfile({
   };
 }
 
+async function handleValidateProfile({ pathParams = {} }: RouteHandlerArgs) {
+  const name = (pathParams.name ?? "").trim();
+  if (!name) {
+    throw new BadRequestError("Profile name must be a non-empty string");
+  }
+  return { check: await probeInferenceProfile(name) };
+}
+
 async function handleDeleteProfile({ pathParams = {} }: RouteHandlerArgs) {
   const name = (pathParams.name ?? "").trim();
   if (!name) {
@@ -858,4 +1041,22 @@ export const ROUTES: RouteDefinition[] = [
     },
     handler: handleSetActiveProfile,
   },
+  {
+    operationId: "inference_profiles_validate",
+    endpoint: "inference/profiles/:name/validate",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Probe a saved profile with one minimal request",
+    description:
+      "Dispatch one minimal test request through the named profile's resolved model and connection, and classify any failure by which object the user should fix (the profile vs its provider connection). Advisory: the probe never mutates the profile. Returns a null check when there is no verdict to give (missing, disabled, managed, or routing-identity profiles, or a probe timeout). The probe spends one tiny request on the profile's own key.",
+    tags: ["inference"],
+    pathParams: [{ name: "name", description: "Profile name" }],
+    responseBody: z.object({
+      check: profileCheckSchema.nullable(),
+    }),
+    handler: handleValidateProfile,
+  },
 ];

package/src/runtime/routes/inference-provider-connection-routes.ts

@@ -39,6 +39,10 @@ import {
   MANAGED_CONNECTION_NAMES,
   updateConnection,
 } from "../../providers/inference/connections.js";
+import {
+  EndpointCheckSchema,
+  testInferenceConnection,
+} from "../../providers/inference/endpoint-probe.js";
 import { PROVIDER_CATALOG } from "../../providers/model-catalog.js";
 import {
   isVellumManagedConnection,
@@ -64,6 +68,16 @@ const log = getLogger("routes/inference-provider-connections");
 
 const providerConnectionResponseSchema = ProviderConnectionSchema;
 
+/**
+ * Create/update responses carry the save-time endpoint probe result for
+ * connections with a custom base URL. Advisory only: a failed probe never
+ * fails the save (some endpoints legitimately reject unauthenticated or
+ * minimal requests); clients render `hint` as a warning.
+ */
+const savedConnectionResponseSchema = ProviderConnectionSchema.extend({
+  endpoint_check: EndpointCheckSchema.optional(),
+}).meta({ id: "SavedProviderConnection" });
+
 // ---------------------------------------------------------------------------
 // Custom provider field parsing (openai-compatible base_url + models)
 // ---------------------------------------------------------------------------
@@ -428,7 +442,10 @@ async function handleCreateConnection({ body = {} }: RouteHandlerArgs) {
     throw new BadRequestError("Invalid auth configuration.");
   }
 
-  return result.connection;
+  const endpointCheck = await testInferenceConnection(result.connection);
+  return endpointCheck
+    ? { ...result.connection, endpoint_check: endpointCheck }
+    : result.connection;
 }
 
 async function handleUpdateConnection({
@@ -547,7 +564,10 @@ async function handleUpdateConnection({
     throw new BadRequestError("Invalid auth configuration.");
   }
 
-  return result.connection;
+  const endpointCheck = await testInferenceConnection(result.connection);
+  return endpointCheck
+    ? { ...result.connection, endpoint_check: endpointCheck }
+    : result.connection;
 }
 
 async function handleDeleteConnection({ pathParams = {} }: RouteHandlerArgs) {
@@ -751,7 +771,7 @@ export const ROUTES: RouteDefinition[] = [
       base_url: z.string().url().nullable().optional(),
       models: z.array(ConnectionModelSchema).nullable().optional(),
     }),
-    responseBody: providerConnectionResponseSchema,
+    responseBody: savedConnectionResponseSchema,
     responseStatus: "201",
     additionalResponses: {
       "400": { description: "Invalid provider or auth schema" },
@@ -779,7 +799,7 @@ export const ROUTES: RouteDefinition[] = [
       base_url: z.string().url().nullable().optional(),
       models: z.array(ConnectionModelSchema).nullable().optional(),
     }),
-    responseBody: providerConnectionResponseSchema,
+    responseBody: savedConnectionResponseSchema,
     additionalResponses: {
       "400": {
         description:

package/src/runtime/routes/ingress-status-routes.ts

@@ -0,0 +1,180 @@
+/**
+ * Ingress status route: is the assistant's public tunnel actually up?
+ *
+ * The recorded `ingress.publicBaseUrl` only says a tunnel was configured at
+ * some point. It stays behind in both directions: a killed tunnel leaves the
+ * URL in place, and an edge can survive while the gateway behind it dies or
+ * while it starts fronting a different assistant. This route resolves that by
+ * probing the URL live (`inbound/tunnel-probe.ts`) and reporting one of six
+ * states, so a client can tell the user what to do instead of guessing. The
+ * card the states drive exists to pair devices, so an address that answers
+ * without serving the pairing app is its own state (`unpairable`) rather than
+ * a healthy one.
+ *
+ * Platform-hosted assistants receive webhooks through platform callback
+ * routing and never run `vellum tunnel`, so they report `unconfigured`
+ * rather than a tunnel state they cannot act on. A self-hosted gateway whose
+ * Velay tunnel owns the URL is the same story one layer down: that URL
+ * carries webhooks alone, so it is `unconfigured` for pairing too, and the
+ * gateway publishes and restores it without a tunnel command either way.
+ */
+import { normalizePublicBaseUrl } from "@vellumai/service-contracts/ingress";
+import { z } from "zod";
+
+import {
+  getIngressConfigResult,
+  isVelayManagedIngress,
+  loadLastTunnelRecord,
+  loadPairingTunnelRecord,
+  loadRecordedAssistantId,
+} from "../../daemon/handlers/config-ingress.js";
+import { probeTunnel } from "../../inbound/tunnel-probe.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import type { RouteDefinition } from "./types.js";
+
+// ── Schemas ─────────────────────────────────────────────────────────────
+
+/**
+ * Flat rather than a union on `state` so the generated client SDK stays a
+ * single type; which fields are populated follows from `state`.
+ */
+const IngressStatusResponseSchema = z.object({
+  state: z.enum([
+    "unconfigured",
+    "stopped",
+    "healthy",
+    "unpairable",
+    "unreachable",
+    "foreign",
+  ]),
+  publicBaseUrl: z
+    .string()
+    .optional()
+    .describe(
+      "The probed URL. Set for healthy, unpairable, unreachable, and foreign.",
+    ),
+  lastTunnel: z
+    .object({ provider: z.string(), publicBaseUrl: z.string() })
+    .optional()
+    .describe(
+      "The tunnel to restart. Set on stopped whenever one is recorded, and on unpairable, unreachable and foreign when the recorded tunnel fronted the configured URL.",
+    ),
+  servingAssistantName: z
+    .string()
+    .optional()
+    .describe(
+      "Name the edge serves under. Set for foreign when it reports one.",
+    ),
+  detail: z
+    .string()
+    .optional()
+    .describe(
+      "Short failure reason, free of the URL. Set for unreachable, and for unpairable when the edge gave one.",
+    ),
+  checkedAt: z
+    .string()
+    .optional()
+    .describe("ISO-8601 instant the probe finished. Set whenever one ran."),
+});
+type IngressStatusResponse = z.infer<typeof IngressStatusResponseSchema>;
+
+// ── Handlers ────────────────────────────────────────────────────────────
+
+async function handleIngressStatus(): Promise<IngressStatusResponse> {
+  const config = getIngressConfigResult();
+  if (config.managedCallbacks) {
+    return { state: "unconfigured" };
+  }
+
+  // A tunnel published for pairing alone is the address this route reports on:
+  // it exists to answer the pairing card, and the `publicBaseUrl` beside it is
+  // a webhook callback base that tunnel deliberately left in place. The user
+  // owns and restarts that tunnel even where Velay owns the callback ingress.
+  const pairingTunnel = loadPairingTunnelRecord();
+  // A Velay-managed URL belongs to the gateway, which writes it, clears it,
+  // and reconnects on its own, so there is no tunnel for the user to restart.
+  // Velay's allowlist (`gateway/src/velay/allowed-paths.ts`) also exposes
+  // neither `/healthz` nor the `/assistant/*` pairing surface, so that URL can
+  // only ever probe as dead and prefills a page pairing cannot open. Without a
+  // pairing tunnel beside it there is no address to report at all.
+  if (isVelayManagedIngress() && !pairingTunnel) {
+    return { state: "unconfigured" };
+  }
+  const lastTunnel = pairingTunnel ?? loadLastTunnelRecord();
+
+  const publicBaseUrl =
+    pairingTunnel?.publicBaseUrl ?? config.publicBaseUrl.trim();
+  if (!publicBaseUrl && !lastTunnel) {
+    return { state: "unconfigured" };
+  }
+  // `ingress.enabled` governs callback ingress alone, and the URL survives
+  // that toggle, so probing a callback base while ingress is opted out would
+  // report an address the user switched off as healthy. A pairing tunnel is
+  // published outside the toggle, so the opt-out says nothing about it. An
+  // unset flag is not an opt-out either: a bring-your-own-HTTPS front sets
+  // only the URL.
+  if (!publicBaseUrl || (!pairingTunnel && config.explicitlyDisabled)) {
+    return { state: "stopped", ...(lastTunnel ? { lastTunnel } : {}) };
+  }
+
+  // A record left over from an address that is no longer configured names a
+  // tunnel that never fronted this one, so it is no help in getting back.
+  const restartHint =
+    lastTunnel &&
+    normalizePublicBaseUrl(lastTunnel.publicBaseUrl) ===
+      normalizePublicBaseUrl(publicBaseUrl)
+      ? { lastTunnel }
+      : {};
+
+  // Omitted when unrecorded so the probe skips the identity check entirely
+  // rather than reading every served id as a mismatch.
+  const expectedAssistantId = loadRecordedAssistantId();
+  const result = await probeTunnel({
+    publicBaseUrl,
+    ...(expectedAssistantId ? { expectedAssistantId } : {}),
+  });
+  const checked = { publicBaseUrl, checkedAt: new Date().toISOString() };
+
+  switch (result.kind) {
+    case "healthy":
+      return { state: "healthy", ...checked };
+    // One remedy for both: start a tunnel that serves the web app.
+    case "unpairable":
+    case "unreachable":
+      return {
+        state: result.kind,
+        ...checked,
+        ...restartHint,
+        ...(result.detail ? { detail: result.detail } : {}),
+      };
+    case "foreign":
+      return {
+        state: "foreign",
+        ...checked,
+        ...restartHint,
+        ...(result.assistantName
+          ? { servingAssistantName: result.assistantName }
+          : {}),
+      };
+  }
+}
+
+// ── Route definitions ───────────────────────────────────────────────────
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "integrations_ingress_status",
+    endpoint: "integrations/ingress/status",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get ingress tunnel status",
+    description:
+      "Probe the configured public ingress URL and report whether a tunnel is serving this assistant. `unconfigured` means no tunnel has ever been recorded (or the ingress is managed for this assistant, as it is when platform-hosted or fronted by a Velay tunnel), `stopped` means a tunnel ran before and is not running now (callback ingress is explicitly switched off, or its URL is gone), `healthy` means the URL answers and fronts this assistant's web app, `unpairable` means it answers but does not serve that app, so a pairing link minted against it would not open, `unreachable` means it does not answer, and `foreign` means it answers for a different assistant. `lastTunnel` names the tunnel to restart, on the states where a recorded one applies to the configured URL.",
+    tags: ["config"],
+    handler: handleIngressStatus,
+    responseBody: IngressStatusResponseSchema,
+  },
+];