@vellumai/assistant 0.10.9-staging.1 → 0.10.9

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

@@ -0,0 +1,69 @@
+/**
+ * Gateway status route — public tunnel status via the gateway IPC proxy.
+ *
+ * The tunnel is the gateway's outbound public-ingress transport. It is only
+ * used to tunnel inbound Twilio webhooks and live voice/audio WebSockets to
+ * this assistant — it plays no part in platform credentials or the managed
+ * LLM proxy. The handler reads the live status from the gateway over the local
+ * IPC socket, so the assistant does not need gateway signing material.
+ *
+ * The response is deliberately tunnel-agnostic: a single `tunnel` field holding
+ * the active public URL, omitted entirely when a tunnel is up but has no URL.
+ * This keeps the contract stable if the underlying transport (currently Velay)
+ * is ever swapped for another tunnel. If the gateway is not running (no IPC
+ * answer), the handler errors instead of returning an empty result.
+ */
+import { z } from "zod";
+
+import { ipcGetVelayStatus } from "../../ipc/gateway-client.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { ServiceUnavailableError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+// ── Schemas ─────────────────────────────────────────────────────────────
+
+const GatewayStatusResponseSchema = z.object({
+  // Present with the public tunnel URL when a tunnel is connected; omitted
+  // (so the object is `{}`) when no tunnel is up or the gateway is not running.
+  tunnel: z.string().optional(),
+});
+type GatewayStatusResponse = z.infer<typeof GatewayStatusResponseSchema>;
+
+// ── Handlers ────────────────────────────────────────────────────────────
+
+async function handleGatewayStatus(
+  _args: RouteHandlerArgs,
+): Promise<GatewayStatusResponse> {
+  const status = await ipcGetVelayStatus().catch(() => null);
+  // A null status means the gateway did not answer over IPC — i.e. it is not
+  // running. That is a fatal condition for this command, not a "no tunnel"
+  // state, so surface it as an error rather than an empty result.
+  if (status === null) {
+    throw new ServiceUnavailableError(
+      "Gateway is not running or is unreachable over IPC.",
+    );
+  }
+  return status.connected && status.publicUrl
+    ? { tunnel: status.publicUrl }
+    : {};
+}
+
+// ── Route definitions ───────────────────────────────────────────────────
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "gateway_status",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    endpoint: "gateway/status",
+    handler: handleGatewayStatus,
+    summary: "Get gateway status",
+    description:
+      "Reports the gateway's public tunnel status. `tunnel` holds the active public URL when a tunnel is connected and is omitted otherwise. Errors with 503 when the gateway is not running. The tunnel only matters for routing inbound Twilio webhooks and live voice/audio WebSockets.",
+    tags: ["gateway"],
+    responseBody: GatewayStatusResponseSchema,
+  },
+];

package/src/runtime/routes/index.ts

@@ -68,6 +68,7 @@ import { ROUTES as EMAIL_ROUTES } from "./email-routes.js";
 import { ROUTES as EVENTS_ROUTES } from "./events-routes.js";
 import { ROUTES as FILING_ROUTES } from "./filing-routes.js";
 import { ROUTES as GATEWAY_LOG_ROUTES } from "./gateway-log-routes.js";
+import { ROUTES as GATEWAY_STATUS_ROUTES } from "./gateway-status-routes.js";
 import { ROUTES as GLOBAL_SEARCH_ROUTES } from "./global-search-routes.js";
 import { ROUTES as GROUP_ROUTES } from "./group-routes.js";
 import { ROUTES as GUARDIAN_ACTION_ROUTES } from "./guardian-action-routes.js";
@@ -210,6 +211,7 @@ export const ROUTES: RouteDefinition[] = [
   ...EVENTS_ROUTES,
   ...FILING_ROUTES,
   ...GATEWAY_LOG_ROUTES,
+  ...GATEWAY_STATUS_ROUTES,
   ...GLOBAL_SEARCH_ROUTES,
   ...GROUP_ROUTES,
   ...GUARDIAN_ACTION_ROUTES,

package/src/runtime/routes/platform-routes.ts

@@ -3,7 +3,8 @@
  *
  * Serves six operations:
  *   - platform_status (GET platform/status): aggregates platform context,
- *     credentials, assistant ID, webhook secret, and Velay tunnel status.
+ *     credentials, assistant ID, and webhook secret. (Velay tunnel status
+ *     lives on the gateway — see gateway_status.)
  *   - platform_connect (POST platform/connect): checks existing credentials
  *     and emits the show_platform_login signal to connected clients.
  *   - platform_disconnect (POST platform/disconnect): deletes stored platform
@@ -23,7 +24,6 @@ import {
   registerCallbackRoute,
   resolvePlatformCallbackRegistrationContext,
 } from "../../inbound/platform-callback-registration.js";
-import { ipcGetVelayStatus } from "../../ipc/gateway-client.js";
 import { credentialKey } from "../../security/credential-key.js";
 import {
   deleteSecureKeyAsync,
@@ -56,11 +56,6 @@ const CREDENTIAL_KEYS = {
 // Schemas
 // ---------------------------------------------------------------------------
 
-const VelayTunnelStatusSchema = z.object({
-  connected: z.boolean(),
-  publicUrl: z.string().nullable(),
-});
-
 const PlatformStatusResponseSchema = z.object({
   isPlatform: z.boolean(),
   baseUrl: z.string(),
@@ -71,7 +66,6 @@ const PlatformStatusResponseSchema = z.object({
   available: z.boolean(),
   organizationId: z.string().nullable(),
   userId: z.string().nullable(),
-  velayTunnel: VelayTunnelStatusSchema.nullable(),
 });
 type PlatformStatusResponse = z.infer<typeof PlatformStatusResponseSchema>;
 
@@ -137,10 +131,7 @@ type PlatformCreditsResponse = z.infer<typeof PlatformCreditsResponseSchema>;
 async function handlePlatformStatus(
   _args: RouteHandlerArgs,
 ): Promise<PlatformStatusResponse> {
-  const [context, velayTunnel] = await Promise.all([
-    resolvePlatformCallbackRegistrationContext(),
-    ipcGetVelayStatus().catch(() => null),
-  ]);
+  const context = await resolvePlatformCallbackRegistrationContext();
 
   const [orgIdRaw, userIdRaw, webhookSecretRaw] = await Promise.all([
     getSecureKeyAsync(
@@ -172,7 +163,6 @@ async function handlePlatformStatus(
     available: context.enabled,
     organizationId: organizationId || null,
     userId: userId || null,
-    velayTunnel,
   };
 }
 
@@ -433,7 +423,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Get platform deployment context and connection status",
     description:
-      "Aggregates platform context, credentials, assistant ID, webhook secret, and Velay tunnel status.",
+      "Aggregates platform context, credentials, assistant ID, and webhook secret. Velay tunnel status is reported separately by gateway_status.",
     tags: ["platform"],
     handler: handlePlatformStatus,
     responseBody: PlatformStatusResponseSchema,

package/src/runtime/routes/plugins-routes.ts

@@ -88,9 +88,11 @@ import {
   PluginNotUpgradableError,
   upgradePlugin,
 } from "../../cli/lib/upgrade-plugin.js";
+import { getPlatformBaseUrl } from "../../config/env.js";
 import { isPluginDisabled } from "../../plugins/disabled-state.js";
 import { ensurePluginApiShim } from "../../plugins/ensure-plugin-api-shim.js";
 import { getLocalCategorySlugs } from "../../skills/categories-cache.js";
+import { getLogger } from "../../util/logger.js";
 import { getWorkspacePluginsDir } from "../../util/platform.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
@@ -701,6 +703,37 @@ const pluginDiffResponseSchema = z.object({
 // Helpers
 // ---------------------------------------------------------------------------
 
+const log = getLogger("plugins-routes");
+
+/**
+ * Emit a structured log for a platform plugin-catalog outage before the caller
+ * maps it to a client-facing error.
+ *
+ * The catalog fetcher (`plugin-catalog-platform.ts`) throws
+ * `PluginCatalogUnavailableError` without logging, and the transport adapters
+ * return the resulting `RouteError` (a 503) without any Sentry capture — so an
+ * outage on the platform-first paths (`search`, `install`, the remote-only
+ * detail view) otherwise leaves no trace beyond the daemon access-log status
+ * code, and the real upstream status / URL is lost. Log at `error` so the
+ * outage is time-correlatable in the daemon log and surfaces in Sentry;
+ * `upstreamStatus` preserves the true platform status (e.g. 404 / 500 / 503)
+ * that the client-facing 503 collapses.
+ */
+function logPluginCatalogUnavailable(
+  operation: string,
+  err: PluginCatalogUnavailableError,
+): void {
+  log.error(
+    {
+      err,
+      operation,
+      upstreamStatus: err.status,
+      platformBaseUrl: getPlatformBaseUrl(),
+    },
+    "Platform plugin catalog unavailable",
+  );
+}
+
 interface PluginView {
   id: string;
   name: string;
@@ -880,10 +913,31 @@ export async function loadCategoryMapBounded(
       }),
     ]);
     if (!catalog) {
+      // Timed out past the budget: the installed list degrades to no
+      // categories rather than stalling. Non-fatal, but log it so a slow
+      // marketplace is diagnosable and not silently invisible.
+      log.warn(
+        { timeoutMs, platformBaseUrl: getPlatformBaseUrl() },
+        "Plugin catalog lookup timed out; listing without categories",
+      );
       return new Map();
     }
     return new Map(catalog.matches.map((m) => [m.name, m.category]));
-  } catch {
+  } catch (err) {
+    // The installed list must never fail on a catalog outage, so this degrades
+    // to no categories — but log it (warn: the request still succeeds) so the
+    // same platform outage that hard-fails search/install is not invisible on
+    // the list path. `upstreamStatus` is preserved when the failure carries one.
+    log.warn(
+      {
+        err,
+        platformBaseUrl: getPlatformBaseUrl(),
+        ...(err instanceof PluginCatalogUnavailableError
+          ? { upstreamStatus: err.status }
+          : {}),
+      },
+      "Plugin catalog lookup failed; listing without categories",
+    );
     return new Map();
   } finally {
     if (timer) {
@@ -999,6 +1053,7 @@ async function handleSearchPlugins({
     // misleading 500 so the client can show a "temporarily unavailable"
     // state and retry later.
     if (err instanceof PluginCatalogUnavailableError) {
+      logPluginCatalogUnavailable("search", err);
       throw new ServiceUnavailableError(err.message);
     }
     throw new InternalError(
@@ -1080,6 +1135,7 @@ async function handleGetPluginDetails({
     // transient — surface it as retryable rather than a misleading 404/500 so
     // clients retry instead of treating the plugin as permanently gone.
     if (err instanceof PluginCatalogUnavailableError) {
+      logPluginCatalogUnavailable("details", err);
       throw new ServiceUnavailableError(err.message);
     }
     throw new InternalError(
@@ -1207,6 +1263,7 @@ async function handleInstallPlugin({ body = {}, headers }: RouteHandlerArgs) {
     // A rate-limited or unavailable platform catalog (no stale fallback) is
     // transient — surface it as retryable rather than a misleading 500.
     if (err instanceof PluginCatalogUnavailableError) {
+      logPluginCatalogUnavailable("install", err);
       throw new ServiceUnavailableError(err.message);
     }
     throw new InternalError(

package/src/runtime/routes/settings-routes.ts

@@ -16,11 +16,11 @@ import {
 import { loadRawConfig, saveRawConfig } from "../../config/loader.js";
 import { loadSkillCatalog } from "../../config/skills.js";
 import { getGuardianDelivery } from "../../contacts/guardian-delivery-reader.js";
+import type { Conversation } from "../../daemon/conversation.js";
 import { findConversation } from "../../daemon/conversation-registry.js";
 import {
   createResolveToolsCallback,
   DEFAULT_PREACTIVATED_SKILL_IDS,
-  type SkillProjectionContext,
 } from "../../daemon/conversation-tool-setup.js";
 import {
   computeGatewayTarget,
@@ -487,8 +487,8 @@ function handleToolNamesList(
  * Resolve the tool surface a subagent would receive, identified either by a
  * role name (e.g. "researcher") or a live subagent id.
  *
- * For a role name: build a {@link SkillProjectionContext} matching what the
- * {@link SubagentManager} sets up at spawn time (isSubagent, allowedTools,
+ * For a role name: build a minimal {@link Conversation} stand-in matching what
+ * the {@link SubagentManager} sets up at spawn time (isSubagent, allowedTools,
  * preactivated skill ids, no client), then run the exact same
  * {@link createResolveToolsCallback} the real subagent uses to project tools
  * for its first turn. This ensures the diagnostic reports the same tool set
@@ -516,7 +516,9 @@ function handleAgentToolList(agent: string): ToolNamesListResponse {
     );
   }
 
-  // Build the same context the SubagentManager creates at spawn time:
+  // Build the same context the SubagentManager creates at spawn time. The
+  // resolver reads only this subset of Conversation state, so a minimal
+  // stand-in cast to Conversation is enough:
   //   - isSubagent: true (gates subagent-only tools like notify_parent)
   //   - subagentAllowedTools: the role's allowlist (wire gate mode by default)
   //   - preactivatedSkillIds: role skill ids merged with defaults
@@ -527,7 +529,7 @@ function handleAgentToolList(agent: string): ToolNamesListResponse {
     roleConfig.skillIds,
     DEFAULT_PREACTIVATED_SKILL_IDS,
   );
-  const ctx: SkillProjectionContext = {
+  const ctx = {
     isSubagent: true,
     subagentAllowedTools: roleConfig.allowedTools
       ? new Set(roleConfig.allowedTools)
@@ -539,7 +541,7 @@ function handleAgentToolList(agent: string): ToolNamesListResponse {
     skillProjectionCache: {},
     hasNoClient: true,
     preactivatedSkillIds: mergedSkillIds,
-  };
+  } as unknown as Conversation;
 
   // Run the real tool resolver — the same callback a subagent conversation
   // uses each turn. An empty message history simulates the first turn before

package/src/runtime/routes/user-route-dispatcher.ts

@@ -27,17 +27,15 @@
  * whose file does not exist 404s — nothing is registered ahead of time.
  */
 
-import { existsSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { statSync } from "node:fs";
 
-import { isPluginDisabled } from "../../plugins/disabled-state.js";
 import { getLogger } from "../../util/logger.js";
-import {
-  getWorkspacePluginsDir,
-  getWorkspaceRoutesDir,
-} from "../../util/platform.js";
 import type { AssistantEventHub } from "../assistant-event-hub.js";
 import { httpError } from "../http-errors.js";
+import {
+  resolveHandlerFile,
+  resolveRouteLocation,
+} from "./user-route-resolution.js";
 
 const log = getLogger("user-routes");
 
@@ -131,44 +129,6 @@ interface CachedModule {
 /** Default per-request timeout for user-defined route handlers (30 seconds). */
 const DEFAULT_HANDLER_TIMEOUT_MS = 30_000;
 
-/** Supported file extensions for handler modules. */
-const HANDLER_EXTENSIONS = [".ts", ".js"] as const;
-
-/** Path segment reserved for plugin-namespaced routes under `/x/`. */
-const PLUGIN_ROUTE_SEGMENT = "plugins";
-
-/**
- * Resolve an `/x/` route path to the base directory + sub-path the handler file
- * is looked up under.
- *
- * `plugins/<name>/<rest>` resolves against that plugin's own
- * `<workspaceDir>/plugins/<name>/routes/` directory (`<rest>` may be empty,
- * mapping to the namespace's `index` handler). Everything else resolves against
- * the workspace `routes/` directory. Returns `null` (caller 404s) when:
- *
- * - the path is a malformed plugin path (`plugins` with no name segment), so it
- *   never falls back to a workspace route — the `plugins/` prefix is reserved
- *   for plugin routes; or
- * - the named plugin is disabled (`.disabled` sentinel present), so a disabled
- *   plugin serves no routes even though its files remain on disk.
- */
-function resolveRouteLocation(
-  routePath: string,
-): { routesDir: string; subPath: string } | null {
-  const segments = routePath.split("/");
-  if (segments[0] === PLUGIN_ROUTE_SEGMENT) {
-    const pluginName = segments[1];
-    if (!pluginName || isPluginDisabled(pluginName)) {
-      return null;
-    }
-    return {
-      routesDir: join(getWorkspacePluginsDir(), pluginName, "routes"),
-      subPath: segments.slice(2).join("/"),
-    };
-  }
-  return { routesDir: getWorkspaceRoutesDir(), subPath: routePath };
-}
-
 export class UserRouteDispatcher {
   private moduleCache = new Map<string, CachedModule>();
   private handlerTimeoutMs: number;
@@ -197,7 +157,7 @@ export class UserRouteDispatcher {
 
     const location = resolveRouteLocation(routePath);
     const filePath = location
-      ? this.resolveHandlerFile(location.routesDir, location.subPath)
+      ? resolveHandlerFile(location.routesDir, location.subPath)
       : null;
 
     if (!filePath) {
@@ -223,46 +183,6 @@ export class UserRouteDispatcher {
     return this.executeHandler(handler, request, routePath);
   }
 
-  /**
-   * Resolve a route path to a handler file on disk.
-   *
-   * Checks for direct file matches first (`<path>.ts`, `<path>.js`),
-   * then falls back to index files (`<path>/index.ts`, `<path>/index.js`).
-   *
-   * Returns the absolute path to the handler file, or null if not found.
-   */
-  private resolveHandlerFile(
-    routesDir: string,
-    routePath: string,
-  ): string | null {
-    const basePath = join(routesDir, routePath);
-    const resolved = resolve(basePath);
-
-    // Ensure the resolved path is within the routes directory to prevent
-    // any path traversal that slipped through the initial check.
-    if (!resolved.startsWith(resolve(routesDir))) {
-      return null;
-    }
-
-    // Direct file match: routes/<path>.ts or routes/<path>.js
-    for (const ext of HANDLER_EXTENSIONS) {
-      const candidate = `${resolved}${ext}`;
-      if (existsSync(candidate)) {
-        return candidate;
-      }
-    }
-
-    // Index file convention: routes/<path>/index.ts or routes/<path>/index.js
-    for (const ext of HANDLER_EXTENSIONS) {
-      const candidate = join(resolved, `index${ext}`);
-      if (existsSync(candidate)) {
-        return candidate;
-      }
-    }
-
-    return null;
-  }
-
   /**
    * Load a handler module, using the mtime-based cache when possible.
    *

package/src/runtime/routes/user-route-resolution.ts

@@ -0,0 +1,141 @@
+/**
+ * Shared path resolution for `/x/*` user routes.
+ *
+ * Both the request dispatcher (`user-route-dispatcher.ts`) and the CLI
+ * discovery surface (`user-routes-cli.ts`) resolve `/x/` paths to on-disk
+ * handler files through this module, so what the CLI lists can never drift
+ * from what the dispatcher actually serves.
+ *
+ * Two locations back the surface:
+ * - `<workspaceDir>/routes/<path>` — workspace routes, served at `/x/<path>`.
+ * - `<workspaceDir>/plugins/<name>/routes/<path>` — a plugin's routes, served
+ *   in that plugin's reserved namespace at `/x/plugins/<name>/<path>`.
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { isPluginDisabled } from "../../plugins/disabled-state.js";
+import {
+  getWorkspacePluginsDir,
+  getWorkspaceRoutesDir,
+} from "../../util/platform.js";
+
+/** Supported file extensions for handler modules (`.js` preferred over `.ts`). */
+export const HANDLER_EXTENSIONS = [".ts", ".js"] as const;
+
+/** Path segment reserved for plugin-namespaced routes under `/x/`. */
+export const PLUGIN_ROUTE_SEGMENT = "plugins";
+
+export interface RouteLocation {
+  /** Absolute directory the handler file is resolved under. */
+  routesDir: string;
+  /** Path within `routesDir`, relative and without the `/x/` prefix. */
+  subPath: string;
+}
+
+/**
+ * Resolve an `/x/` route path to the base directory + sub-path the handler file
+ * is looked up under.
+ *
+ * `plugins/<name>/<rest>` resolves against that plugin's own
+ * `<workspaceDir>/plugins/<name>/routes/` directory (`<rest>` may be empty,
+ * mapping to the namespace's `index` handler). Everything else resolves against
+ * the workspace `routes/` directory. Returns `null` (caller 404s) when:
+ *
+ * - the path is a malformed plugin path (`plugins` with no name segment), so it
+ *   never falls back to a workspace route — the `plugins/` prefix is reserved
+ *   for plugin routes; or
+ * - the named plugin is disabled (`.disabled` sentinel present), so a disabled
+ *   plugin serves no routes even though its files remain on disk.
+ */
+export function resolveRouteLocation(routePath: string): RouteLocation | null {
+  const segments = routePath.split("/");
+  if (segments[0] === PLUGIN_ROUTE_SEGMENT) {
+    const pluginName = segments[1];
+    if (!pluginName || isPluginDisabled(pluginName)) {
+      return null;
+    }
+    return {
+      routesDir: join(getWorkspacePluginsDir(), pluginName, "routes"),
+      subPath: segments.slice(2).join("/"),
+    };
+  }
+  return { routesDir: getWorkspaceRoutesDir(), subPath: routePath };
+}
+
+/**
+ * Resolve a sub-path within `routesDir` to a handler file on disk.
+ *
+ * Checks for direct file matches first (`<path>.ts`, `<path>.js`), then falls
+ * back to index files (`<path>/index.ts`, `<path>/index.js`). Returns the
+ * absolute path to the handler file, or `null` if not found. Rejects any path
+ * that escapes `routesDir` (traversal backstop).
+ */
+export function resolveHandlerFile(
+  routesDir: string,
+  subPath: string,
+): string | null {
+  const resolved = resolve(join(routesDir, subPath));
+
+  if (!resolved.startsWith(resolve(routesDir))) {
+    return null;
+  }
+
+  for (const ext of HANDLER_EXTENSIONS) {
+    const candidate = `${resolved}${ext}`;
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  for (const ext of HANDLER_EXTENSIONS) {
+    const candidate = join(resolved, `index${ext}`);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * True when a workspace `/x/<path>` collides with the reserved plugin prefix
+ * (`plugins` or `plugins/…`). Such a file lives under `<workspaceDir>/routes/`
+ * but is shadowed by the plugin namespace and never served, so discovery must
+ * exclude it — {@link resolveRouteLocation} routes the same path to a plugin
+ * directory instead.
+ */
+export function isReservedWorkspaceRoutePath(routePath: string): boolean {
+  return (
+    routePath === PLUGIN_ROUTE_SEGMENT ||
+    routePath.startsWith(`${PLUGIN_ROUTE_SEGMENT}/`)
+  );
+}
+
+/**
+ * Enumerate enabled workspace plugins that ship a `routes/` directory, for
+ * route discovery. Mirrors {@link resolveRouteLocation}'s plugin resolution —
+ * same base directory, same disabled-sentinel gate — so discovery and dispatch
+ * agree on which plugin routes exist.
+ */
+export function listPluginRouteRoots(): {
+  pluginName: string;
+  routesDir: string;
+}[] {
+  const pluginsDir = getWorkspacePluginsDir();
+  if (!existsSync(pluginsDir)) {
+    return [];
+  }
+  const roots: { pluginName: string; routesDir: string }[] = [];
+  for (const entry of readdirSync(pluginsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || isPluginDisabled(entry.name)) {
+      continue;
+    }
+    const routesDir = join(pluginsDir, entry.name, "routes");
+    if (existsSync(routesDir) && statSync(routesDir).isDirectory()) {
+      roots.push({ pluginName: entry.name, routesDir });
+    }
+  }
+  return roots;
+}