@vellumai/assistant 0.12.2-staging.1 → 0.12.2-staging.3

package/src/monitoring/mount-watch.ts

@@ -0,0 +1,348 @@
+/**
+ * Mount-table watcher for the assistant container, polled by the resource
+ * monitor.
+ *
+ * The monitor process shares the assistant container's mount namespace, so
+ * `/proc/self/mountinfo` is exactly that container's mounts (workspace and
+ * data PVC binds, plus any virtiofs handles). Gateway and CES sidecar mounts
+ * are out of scope. The watcher keeps a baseline and logs only when the
+ * watched set actually changes: a virtiofs bind that disappears, a fstype
+ * swap, or a statfs size collapse on `/workspace` or `/data`.
+ *
+ * Windows and macOS have no `/proc/self/mountinfo`; those platforms no-op.
+ */
+
+import { readFileSync, statfsSync } from "node:fs";
+
+import type { MonitoringConfig } from "../config/schemas/monitoring.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("mount-watch");
+
+/** Assistant-container PVC bind targets in the managed pod template. */
+export const ASSISTANT_VOLUME_MOUNT_POINTS = ["/workspace", "/data"] as const;
+
+const VIRTIOFS_TYPES = new Set(["virtiofs", "fuse.virtiofs"]);
+
+export interface MountInfoEntry {
+  mountId: string;
+  parentId: string;
+  majorMinor: string;
+  root: string;
+  mountPoint: string;
+  mountOptions: string;
+  fsType: string;
+  source: string;
+  superOptions: string;
+}
+
+export interface PathFsSnapshot {
+  path: string;
+  /** `statfs.f_type`; null when the path could not be measured. */
+  type: number | null;
+  blockSize: number | null;
+  blocks: number | null;
+  files: number | null;
+  /** Present when the path exists but `statfs` failed. */
+  error?: string;
+}
+
+export interface MountSnapshot {
+  mounts: MountInfoEntry[];
+  paths: PathFsSnapshot[];
+}
+
+export interface MountDiff {
+  added: MountInfoEntry[];
+  removed: MountInfoEntry[];
+  changed: Array<{ previous: MountInfoEntry; current: MountInfoEntry }>;
+  pathChanges: Array<{ previous: PathFsSnapshot; current: PathFsSnapshot }>;
+}
+
+export interface CollectMountSnapshotOptions {
+  platform?: NodeJS.Platform;
+  readMountinfo?: () => string;
+  statPath?: (path: string) => PathFsSnapshot;
+  watchedMountPoints?: readonly string[];
+}
+
+export interface MountWatchHandle {
+  stop: () => void;
+}
+
+/**
+ * Kernel mountinfo encodes space/tab/newline in paths as octal escapes
+ * (`\040`, `\011`, `\012`) and a backslash as `\\`.
+ */
+export function unescapeMountField(value: string): string {
+  return value
+    .replace(/\\([0-7]{3})/g, (_match, oct: string) =>
+      String.fromCharCode(parseInt(oct, 8)),
+    )
+    .replace(/\\\\/g, "\\");
+}
+
+/**
+ * Parse `/proc/self/mountinfo` into structured entries. Malformed lines are
+ * skipped rather than failing the pass.
+ */
+export function parseMountinfo(raw: string): MountInfoEntry[] {
+  const entries: MountInfoEntry[] = [];
+  for (const line of raw.split("\n")) {
+    if (line.length === 0) {
+      continue;
+    }
+    const separator = line.indexOf(" - ");
+    if (separator < 0) {
+      continue;
+    }
+    const left = line.slice(0, separator).split(" ");
+    const right = line.slice(separator + 3).split(" ");
+    if (left.length < 6 || right.length < 3) {
+      continue;
+    }
+    entries.push({
+      mountId: left[0],
+      parentId: left[1],
+      majorMinor: left[2],
+      root: unescapeMountField(left[3]),
+      mountPoint: unescapeMountField(left[4]),
+      mountOptions: left[5],
+      fsType: unescapeMountField(right[0]),
+      source: unescapeMountField(right[1]),
+      superOptions: right.slice(2).join(" "),
+    });
+  }
+  return entries;
+}
+
+export function isWatchedMount(
+  entry: MountInfoEntry,
+  watchedMountPoints: readonly string[] = ASSISTANT_VOLUME_MOUNT_POINTS,
+): boolean {
+  if (VIRTIOFS_TYPES.has(entry.fsType)) {
+    return true;
+  }
+  return watchedMountPoints.some(
+    (point) => entry.mountPoint === point || entry.mountPoint.startsWith(`${point}/`),
+  );
+}
+
+function mountIdentity(entry: MountInfoEntry): string {
+  return entry.mountPoint;
+}
+
+function mountSignature(entry: MountInfoEntry): string {
+  return [
+    entry.fsType,
+    entry.source,
+    entry.majorMinor,
+    entry.root,
+    entry.mountOptions,
+    entry.superOptions,
+  ].join("\0");
+}
+
+function pathSignature(snapshot: PathFsSnapshot): string {
+  return [
+    String(snapshot.type),
+    String(snapshot.blockSize),
+    String(snapshot.blocks),
+    String(snapshot.files),
+    snapshot.error ?? "",
+  ].join("\0");
+}
+
+export function diffMountSnapshots(
+  previous: MountSnapshot,
+  current: MountSnapshot,
+): MountDiff {
+  const prevByPoint = new Map(
+    previous.mounts.map((entry) => [mountIdentity(entry), entry]),
+  );
+  const currentByPoint = new Map(
+    current.mounts.map((entry) => [mountIdentity(entry), entry]),
+  );
+
+  const added: MountInfoEntry[] = [];
+  const removed: MountInfoEntry[] = [];
+  const changed: Array<{ previous: MountInfoEntry; current: MountInfoEntry }> =
+    [];
+
+  for (const [point, entry] of currentByPoint) {
+    const prior = prevByPoint.get(point);
+    if (prior == null) {
+      added.push(entry);
+      continue;
+    }
+    if (mountSignature(prior) !== mountSignature(entry)) {
+      changed.push({ previous: prior, current: entry });
+    }
+  }
+  for (const [point, entry] of prevByPoint) {
+    if (!currentByPoint.has(point)) {
+      removed.push(entry);
+    }
+  }
+
+  const prevPaths = new Map(previous.paths.map((row) => [row.path, row]));
+  const pathChanges: Array<{
+    previous: PathFsSnapshot;
+    current: PathFsSnapshot;
+  }> = [];
+  for (const row of current.paths) {
+    const prior = prevPaths.get(row.path);
+    if (prior != null && pathSignature(prior) !== pathSignature(row)) {
+      pathChanges.push({ previous: prior, current: row });
+    }
+  }
+
+  return { added, removed, changed, pathChanges };
+}
+
+export function mountDiffIsEmpty(diff: MountDiff): boolean {
+  return (
+    diff.added.length === 0 &&
+    diff.removed.length === 0 &&
+    diff.changed.length === 0 &&
+    diff.pathChanges.length === 0
+  );
+}
+
+function defaultReadMountinfo(): string {
+  return readFileSync("/proc/self/mountinfo", "utf8");
+}
+
+function defaultStatPath(path: string): PathFsSnapshot {
+  try {
+    const stats = statfsSync(path);
+    return {
+      path,
+      type: Number(stats.type),
+      blockSize: Number(stats.bsize),
+      blocks: Number(stats.blocks),
+      files: Number(stats.files),
+    };
+  } catch {
+    return {
+      path,
+      type: null,
+      blockSize: null,
+      blocks: null,
+      files: null,
+      error: "statfs-failed",
+    };
+  }
+}
+
+/**
+ * Snapshot the assistant container's watched mounts. Returns null on Windows
+ * and macOS, or when `/proc/self/mountinfo` is unreadable.
+ */
+export function collectMountSnapshot(
+  options: CollectMountSnapshotOptions = {},
+): MountSnapshot | null {
+  const platform = options.platform ?? process.platform;
+  if (platform === "win32" || platform === "darwin") {
+    return null;
+  }
+
+  const watchedMountPoints =
+    options.watchedMountPoints ?? ASSISTANT_VOLUME_MOUNT_POINTS;
+  const readMountinfo = options.readMountinfo ?? defaultReadMountinfo;
+  const statPath = options.statPath ?? defaultStatPath;
+
+  let raw: string;
+  try {
+    raw = readMountinfo();
+  } catch {
+    return null;
+  }
+
+  const mounts = parseMountinfo(raw)
+    .filter((entry) => isWatchedMount(entry, watchedMountPoints))
+    .sort((a, b) => a.mountPoint.localeCompare(b.mountPoint));
+
+  const paths = watchedMountPoints.map((path) => statPath(path));
+
+  return { mounts, paths };
+}
+
+function summarizeEntry(entry: MountInfoEntry): Record<string, string> {
+  return {
+    mountPoint: entry.mountPoint,
+    fsType: entry.fsType,
+    source: entry.source,
+    majorMinor: entry.majorMinor,
+  };
+}
+
+function summarizePath(snapshot: PathFsSnapshot): Record<string, unknown> {
+  return {
+    path: snapshot.path,
+    type: snapshot.type,
+    blockSize: snapshot.blockSize,
+    blocks: snapshot.blocks,
+    files: snapshot.files,
+    ...(snapshot.error != null ? { error: snapshot.error } : {}),
+  };
+}
+
+export function logMountDiff(diff: MountDiff): void {
+  log.warn(
+    {
+      added: diff.added.map(summarizeEntry),
+      removed: diff.removed.map(summarizeEntry),
+      changed: diff.changed.map((row) => ({
+        previous: summarizeEntry(row.previous),
+        current: summarizeEntry(row.current),
+      })),
+      pathChanges: diff.pathChanges.map((row) => ({
+        previous: summarizePath(row.previous),
+        current: summarizePath(row.current),
+      })),
+    },
+    "Assistant container mount table changed",
+  );
+}
+
+/**
+ * Start the mount poller. The first pass establishes a silent baseline so a
+ * healthy boot does not log; later passes warn only when the watched mounts
+ * or `/workspace`/`/data` statfs values change.
+ *
+ * The timer is unref'd: the resource sampler is the monitor process's
+ * keep-alive, and this loop must not extend its life on its own.
+ */
+export function startMountWatch(
+  config: MonitoringConfig,
+  options: CollectMountSnapshotOptions = {},
+): MountWatchHandle {
+  let previous: MountSnapshot | null = null;
+
+  const poll = () => {
+    try {
+      const snapshot = collectMountSnapshot(options);
+      if (snapshot == null) {
+        return;
+      }
+      if (previous != null) {
+        const diff = diffMountSnapshots(previous, snapshot);
+        if (!mountDiffIsEmpty(diff)) {
+          logMountDiff(diff);
+        }
+      }
+      previous = snapshot;
+    } catch (err) {
+      log.warn({ err }, "Mount-watch poll failed");
+    }
+  };
+
+  poll();
+  const timer = setInterval(poll, config.mountWatchIntervalMs);
+  timer.unref?.();
+
+  return {
+    stop: () => clearInterval(timer),
+  };
+}

package/src/monitoring/worker.ts

@@ -49,6 +49,7 @@ import {
   type FileDescriptorMonitorHandle,
   startFileDescriptorMonitor,
 } from "./file-descriptors.js";
+import { type MountWatchHandle, startMountWatch } from "./mount-watch.js";
 import {
   type PluginAutoUpdateHandle,
   startPluginAutoUpdate,
@@ -99,6 +100,7 @@ async function main(): Promise<void> {
 
   let sampler: ResourceSamplerHandle | null = null;
   let fdMonitor: FileDescriptorMonitorHandle | null = null;
+  let mountWatch: MountWatchHandle | null = null;
   let sourceWatch: PluginSourceWatchHandle | null = null;
   let autoUpdate: PluginAutoUpdateHandle | null = null;
   let recovery: RecoveryHandle | null = null;
@@ -125,6 +127,7 @@ async function main(): Promise<void> {
     stopDbIntegritySampler();
     autoUpdate?.stop();
     sourceWatch?.stop();
+    mountWatch?.stop();
     fdMonitor?.stop();
     sampler?.stop();
     // Bounded final telemetry flush, mirroring the daemon's shutdown. This
@@ -170,6 +173,9 @@ async function main(): Promise<void> {
   // Descriptor exhaustion is per-process and slow-moving, so it polls on its
   // own timer rather than riding the memory sampler's 250ms tick.
   fdMonitor = startFileDescriptorMonitor(config.monitoring);
+  // Assistant-container mount table only (this process's mount namespace).
+  // Warns only when /workspace, /data, or a virtiofs bind actually changes.
+  mountWatch = startMountWatch(config.monitoring);
   sourceWatch = startPluginSourceWatch(
     config.monitoring.pluginSourceScanIntervalMs,
   );
@@ -211,6 +217,7 @@ async function main(): Promise<void> {
     recovery?.stop();
     autoUpdate?.stop();
     sourceWatch?.stop();
+    mountWatch?.stop();
     fdMonitor?.stop();
     sampler?.stop();
     stopDbIntegritySampler();
@@ -223,6 +230,7 @@ async function main(): Promise<void> {
     recovery?.stop();
     autoUpdate?.stop();
     sourceWatch?.stop();
+    mountWatch?.stop();
     fdMonitor?.stop();
     sampler?.stop();
     stopDbIntegritySampler();
@@ -234,6 +242,7 @@ async function main(): Promise<void> {
     recovery?.stop();
     autoUpdate?.stop();
     sourceWatch?.stop();
+    mountWatch?.stop();
     fdMonitor?.stop();
     sampler?.stop();
     stopDbIntegritySampler();

package/src/oauth/__tests__/seed-providers-managed.test.ts

@@ -60,6 +60,26 @@ describe("PROVIDER_SEED_DATA managed mode wiring", () => {
       );
     }
 
+    // `folders:read` is documented too, but the app's scope picker only
+    // offers `folder_metadata:read` under Folders, so Figma answers
+    // "Invalid scopes for app" whenever it is requested.
+    expect(figma.defaultScopes).not.toContain("folders:read");
+    if (Array.isArray(availableScopes)) {
+      expect(availableScopes.map(({ scope }) => scope)).toContain(
+        "folders:read",
+      );
+    }
+
+    // `file_code_connect:write` is only offered to apps owned by an
+    // Organization-plan team. Managed apps in other environments are not,
+    // so requesting it fails the whole authorization there.
+    expect(figma.defaultScopes).not.toContain("file_code_connect:write");
+    if (Array.isArray(availableScopes)) {
+      expect(availableScopes.map(({ scope }) => scope)).toContain(
+        "file_code_connect:write",
+      );
+    }
+
     // GET /v1/me backs both the ping and the identity label.
     expect(figma.defaultScopes).toContain("current_user:read");
   });
@@ -181,6 +201,81 @@ describe("PROVIDER_SEED_DATA managed mode wiring", () => {
     expect(template?.hostPattern).toBe("*.myshopify.com");
   });
 
+  test("quickbooks is wired up for managed mode behind its flag", () => {
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    expect(quickbooks).toBeDefined();
+    expect(quickbooks.managedServiceConfigKey).toBe("quickbooks-oauth");
+    expect("quickbooks-oauth" in ServicesSchema.shape).toBe(true);
+    // Hidden until the platform side and client ids are live, like Figma
+    // and Shopify.
+    expect(quickbooks.featureFlag).toBe("quickbooks-oauth");
+  });
+
+  test("quickbooks uses Intuit's OAuth endpoints with HTTP Basic", () => {
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    expect(quickbooks.authorizeUrl).toBe(
+      "https://appcenter.intuit.com/connect/oauth2",
+    );
+    expect(quickbooks.tokenExchangeUrl).toBe(
+      "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer",
+    );
+    expect(quickbooks.refreshUrl).toBe(quickbooks.tokenExchangeUrl);
+    expect(quickbooks.tokenEndpointAuthMethod).toBe("client_secret_basic");
+  });
+
+  test("quickbooks keeps its per-company URL templates", () => {
+    // Every Accounting API path is scoped to the realm the user picked on
+    // Intuit's consent screen. The platform fills {realm_id} from the
+    // connection; a hardcoded realm here would send every company's calls
+    // to the wrong books.
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    for (const url of [quickbooks.baseUrl, quickbooks.identityUrl]) {
+      expect(url).toContain("/v3/company/{realm_id}");
+    }
+  });
+
+  test("quickbooks seeds no ping or revoke URL", () => {
+    // The ping route sends the URL's origin as a base override and cannot
+    // fill {realm_id}; the daemon's revoke helper posts an unauthenticated
+    // form body that Intuit's JSON + Basic-auth endpoint rejects. Either
+    // would fail silently on every your-own connection.
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    expect(quickbooks.pingUrl).toBeUndefined();
+    expect(quickbooks.revokeUrl).toBeUndefined();
+  });
+
+  test("quickbooks requests only the accounting scope by default", () => {
+    // Payments needs a Payments-enabled app and the OpenID scopes only add
+    // the user's profile; requesting either widens the consent screen for
+    // nothing the Accounting API needs.
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    expect(quickbooks.defaultScopes).toEqual([
+      "com.intuit.quickbooks.accounting",
+    ]);
+    const available = quickbooks.availableScopes;
+    expect(Array.isArray(available)).toBe(true);
+    if (Array.isArray(available)) {
+      expect(available.map(({ scope }) => scope)).toContain(
+        "com.intuit.quickbooks.payment",
+      );
+    }
+  });
+
+  test("quickbooks allows the credential on both Intuit API hosts", () => {
+    // Development keys only work against sandbox companies, which live on
+    // the sandbox host. Both hosts belong to Intuit and take the same
+    // bearer token.
+    const templates = PROVIDER_SEED_DATA.quickbooks.injectionTemplates ?? [];
+    expect(templates.map((t) => t.hostPattern).sort()).toEqual([
+      "quickbooks.api.intuit.com",
+      "sandbox-quickbooks.api.intuit.com",
+    ]);
+    for (const template of templates) {
+      expect(template.headerName).toBe("Authorization");
+      expect(template.valuePrefix).toBe("Bearer ");
+    }
+  });
+
   test("every managedServiceConfigKey resolves to a ServicesSchema key", () => {
     // Cross-repo invariant: a provider with managedServiceConfigKey but no
     // matching ServicesSchema entry silently falls back to BYO mode in

package/src/oauth/connection-resolver.test.ts

@@ -72,6 +72,7 @@ import { setConfig } from "../__tests__/helpers/set-config.js";
 import { BYOOAuthConnection } from "./byo-connection.js";
 import {
   formatNoConnectionError,
+  platformProxyBaseUrl,
   resolveEffectiveBaseUrl,
   resolveOAuthConnection,
   resolveOAuthConnectionWithMeta,
@@ -755,6 +756,32 @@ describe("resolveEffectiveBaseUrl", () => {
   });
 });
 
+describe("platformProxyBaseUrl", () => {
+  test("forwards a concrete seed base URL", () => {
+    expect(platformProxyBaseUrl("https://api.figma.com")).toBe(
+      "https://api.figma.com",
+    );
+  });
+
+  test("withholds a templated base URL so the platform fills it", () => {
+    // Shopify's host and QuickBooks' realm are pinned to the connection on
+    // the platform. Forwarding the unfilled template would fail the proxy's
+    // allowlist check and shadow the platform's own default.
+    expect(platformProxyBaseUrl("https://{tenant_host}")).toBeUndefined();
+    expect(
+      platformProxyBaseUrl(
+        "https://quickbooks.api.intuit.com/v3/company/{realm_id}",
+      ),
+    ).toBeUndefined();
+  });
+
+  test("treats a missing base URL as no override", () => {
+    expect(platformProxyBaseUrl(undefined)).toBeUndefined();
+    expect(platformProxyBaseUrl(null)).toBeUndefined();
+    expect(platformProxyBaseUrl("")).toBeUndefined();
+  });
+});
+
 describe("resolveTokenHeader", () => {
   const shopify = JSON.stringify([
     {

package/src/oauth/connection-resolver.ts

@@ -129,7 +129,10 @@ export async function resolveOAuthConnectionWithMeta(
         accountInfo: resolution.accountLabel ?? account ?? null,
         client,
         connectionId: resolution.id,
-        baseUrl: providerRow?.baseUrl ?? undefined,
+        // A templated base URL (`https://{tenant_host}`, `.../{realm_id}`) is
+        // filled in by the platform from what it pinned to the connection;
+        // sent as-is it would fail the proxy's allowlist and shadow that.
+        baseUrl: platformProxyBaseUrl(providerRow?.baseUrl),
       });
       return {
         connection,
@@ -317,6 +320,24 @@ function hostMatchesPattern(host: string, pattern: string): boolean {
   return host === p;
 }
 
+/**
+ * The base URL a managed connection sends to the platform proxy, or
+ * `undefined` to let the proxy use the provider's configured default.
+ *
+ * Per-tenant and per-realm providers seed a template the platform fills from
+ * the connection (`{tenant_host}`, `{realm_id}`). Forwarding the unfilled
+ * template would fail the proxy's allowlist check, so those fall through to
+ * the platform's own default.
+ */
+export function platformProxyBaseUrl(
+  seedBaseUrl: string | null | undefined,
+): string | undefined {
+  if (!seedBaseUrl || /\{[a-z_]+\}/.test(seedBaseUrl)) {
+    return undefined;
+  }
+  return seedBaseUrl;
+}
+
 /**
  * Resolve the effective API base URL for a connection, preferring per-tenant
  * values stored on the connection's `metadata` over the provider's static
@@ -394,6 +415,9 @@ interface PlatformConnectionEntry {
   /** Scopes the platform actually granted this connection. May be absent for
    *  older connections or providers that don't report scopes. */
   scopes_granted?: string[] | null;
+  /** Provider-supplied values the connection is scoped by (QuickBooks'
+   *  `realm_id`). Absent from older platforms; empty for most providers. */
+  provider_params?: Record<string, string> | null;
 }
 
 interface PlatformConnectionResolution {

package/src/oauth/provider-serializer.ts

@@ -20,6 +20,8 @@ export type SerializedProvider = ReturnType<typeof serializeProvider> &
 
 import { isChannelBotProvider } from "@vellumai/service-contracts/channels";
 
+import { PROVIDER_SEED_DATA } from "./seed-providers.js";
+
 /**
  * Lightweight summary projection of an OAuth provider, suitable for API
  * list responses where full detail is not needed. All keys are snake_case
@@ -36,6 +38,12 @@ export interface SerializedProviderSummary {
   supports_managed_mode: boolean;
   managed_service_is_paid: boolean;
   feature_flag: string | null;
+  /**
+   * Per-tenant providers only (Shopify): what a client must collect before
+   * starting a managed connect, since the provider's OAuth endpoints live on
+   * the customer's own host. `null` for providers with one global host.
+   */
+  tenant_host: { pattern: string; label: string; placeholder: string } | null;
   /**
    * Which sense of "connected" this provider represents: `assistant` for a bot
    * credential people reach the assistant through, `user` for a grant letting
@@ -164,6 +172,7 @@ export function serializeProviderSummary(
     supports_managed_mode: !!row.managedServiceConfigKey,
     managed_service_is_paid: !!row.managedServiceIsPaid,
     feature_flag: row.featureFlag ?? null,
+    tenant_host: PROVIDER_SEED_DATA[row.provider]?.tenantHost ?? null,
     acts_as: isChannelBotProvider(row.provider) ? "assistant" : "user",
   };
 }