@vellumai/cli 0.11.2 → 0.11.3-staging.2

package/node_modules/@vellumai/local-mode/src/pair.ts

@@ -0,0 +1,354 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { nanoid } from "nanoid";
+
+import { guardianTokenPath } from "./config";
+import {
+  isConfidentialRefreshUrl,
+  isLoopbackUrl,
+  saveGuardianToken,
+} from "./guardian-token";
+import { readRawLockfile, upsertLockfileAssistant } from "./lockfile";
+
+/**
+ * A decoded `vellum pair` bundle: base64(JSON.stringify({ gatewayUrl, token,
+ * ... })) printed on the host machine and imported on this one.
+ */
+export interface PairBundle {
+  gatewayUrl: string;
+  token: string;
+  assistantId?: string;
+  deviceId?: string;
+  // Optional refresh credential. Present when the host's gateway issued a
+  // device-bound token pair; absent for older access-only bundles (which remain
+  // importable, just without auto-renewal). `refreshTokenExpiresAt` mirrors
+  // GuardianTokenData (ISO string OR epoch-ms number) so a numeric expiry isn't
+  // silently dropped on import.
+  refreshToken?: string;
+  refreshTokenExpiresAt?: string | number;
+  refreshAfter?: string;
+}
+
+export type DecodePairBundleResult =
+  | { ok: true; bundle: PairBundle }
+  | { ok: false; error: string };
+
+/**
+ * Decode and validate a base64 pairing bundle. Total and non-throwing:
+ * malformed input yields a typed failure. `gatewayUrl` is persisted as
+ * `runtimeUrl` and used to build fetch URLs, so it must be an absolute http(s)
+ * URL rather than letting an invalid string through (which would crash
+ * `new URL(...)` or break later client calls).
+ */
+export function decodePairBundle(encoded: string): DecodePairBundleResult {
+  let json: unknown;
+  try {
+    json = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+  } catch {
+    return { ok: false, error: "Bundle is not base64-encoded JSON" };
+  }
+  if (typeof json !== "object" || json === null) {
+    return { ok: false, error: "Bundle is not a JSON object" };
+  }
+  const b = json as Record<string, unknown>;
+  if (typeof b.gatewayUrl !== "string" || typeof b.token !== "string") {
+    return { ok: false, error: "Bundle is missing gatewayUrl or token" };
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(b.gatewayUrl);
+  } catch {
+    return { ok: false, error: "Bundle gatewayUrl is not an absolute URL" };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { ok: false, error: "Bundle gatewayUrl is not an http(s) URL" };
+  }
+  return {
+    ok: true,
+    bundle: {
+      gatewayUrl: b.gatewayUrl,
+      token: b.token,
+      assistantId:
+        typeof b.assistantId === "string" ? b.assistantId : undefined,
+      deviceId: typeof b.deviceId === "string" ? b.deviceId : undefined,
+      refreshToken:
+        typeof b.refreshToken === "string" ? b.refreshToken : undefined,
+      refreshTokenExpiresAt:
+        typeof b.refreshTokenExpiresAt === "string" ||
+        typeof b.refreshTokenExpiresAt === "number"
+          ? b.refreshTokenExpiresAt
+          : undefined,
+      refreshAfter:
+        typeof b.refreshAfter === "string" ? b.refreshAfter : undefined,
+    },
+  };
+}
+
+/** Lowercase, collapse non-alphanumerics to single dashes, trim dashes. */
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/** Best-effort JWT `exp` (epoch seconds) → epoch ms; null if undecodable. */
+function jwtExpiryMs(token: string): number | null {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  try {
+    const payload = JSON.parse(
+      Buffer.from(parts[1]!, "base64").toString("utf8"),
+    ) as Record<string, unknown>;
+    if (typeof payload.exp === "number") return payload.exp * 1000;
+  } catch {
+    /* fall through */
+  }
+  return null;
+}
+
+export interface PairOptions {
+  /** A bundle validated by {@link decodePairBundle}. */
+  bundle: PairBundle;
+  /** Optional local name; its slug becomes the entry's assistantId. */
+  name?: string;
+}
+
+/**
+ * Failure statuses: 400 the name slugifies to nothing, 409 the id names an
+ * existing non-paired assistant (`assistantId` carries the refused id),
+ * 422 the bundle's gatewayUrl is unparseable, 500 a write failed.
+ */
+export type PairResult =
+  | {
+      ok: true;
+      /** The unique local id the pairing was registered under. */
+      assistantId: string;
+      /** True when an existing paired entry was updated in place. */
+      updated: boolean;
+      /** True when the bundle carried no refresh credential. */
+      accessOnly: boolean;
+    }
+  | { ok: false; status: number; error: string; assistantId?: string };
+
+/**
+ * Register a pairing bundle on this machine: persist the guardian token and
+ * upsert a `cloud: "paired"` lockfile entry, the write counterpart of
+ * `unpairAssistant`.
+ *
+ * The entry is stored under a UNIQUE LOCAL id (not the bundle's assistantId,
+ * which is typically "self" and would collide across hosts). This is safe
+ * because the gateway's runtime proxy strips the `/v1/assistants/<id>/` segment
+ * before forwarding, so the local id never has to match the remote one: the
+ * token (validated by signature/audience) is what authorizes requests.
+ */
+export function pairAssistant(
+  lockfilePaths: string[],
+  configDir: string,
+  { bundle, name }: PairOptions,
+): PairResult {
+  let gatewayHost: string;
+  try {
+    gatewayHost = new URL(bundle.gatewayUrl).host;
+  } catch {
+    return {
+      ok: false,
+      status: 422,
+      error: "Bundle gatewayUrl is not an absolute URL",
+    };
+  }
+
+  // A paired entry is remote by definition (`vellum pair` refuses to advertise
+  // loopback URLs), and a loopback runtimeUrl in the lockfile would otherwise
+  // read as a local gateway to loopback-port consumers. Refuse it outright so
+  // a crafted bundle cannot point a pairing at this machine's own services.
+  if (isLoopbackUrl(bundle.gatewayUrl)) {
+    return {
+      ok: false,
+      status: 422,
+      error:
+        "A paired assistant needs a non-loopback gateway URL; run `vellum pair` " +
+        "with --url pointing at a tunnel or LAN address.",
+    };
+  }
+
+  // Unique local id: a name slug, or paired-<deviceId> (deviceId is unique per
+  // pairing). Never the bundle's "self" assistantId, which would collide. The
+  // deviceId comes from an untrusted bundle and is used as a path component by
+  // saveGuardianToken, so it MUST be slugified (no `../` traversal); fall back
+  // to a random id if it sanitizes to empty.
+  const localId = name
+    ? slugify(name)
+    : `paired-${slugify(bundle.deviceId ?? "") || nanoid()}`;
+  if (!localId) {
+    return {
+      ok: false,
+      status: 400,
+      error: "Name must contain at least one alphanumeric character",
+    };
+  }
+
+  // Don't clobber an existing assistant. Only update in place when the prior
+  // entry is itself a paired import (marked `paired: true`); otherwise the id
+  // collides with a real local/remote assistant and overwriting would drop its
+  // resources/runtime metadata. Reject and let the caller pick a fresh name.
+  const rawAssistants = readRawLockfile(lockfilePaths).assistants;
+  const existing = (
+    Array.isArray(rawAssistants)
+      ? (rawAssistants as Array<Record<string, unknown>>)
+      : []
+  ).find((a) => a?.assistantId === localId);
+  if (existing && existing.paired !== true) {
+    return {
+      ok: false,
+      status: 409,
+      error: `An assistant named '${localId}' already exists`,
+      assistantId: localId,
+    };
+  }
+
+  // Write the token BEFORE committing the lockfile entry, the mirror of
+  // unpair's ordering. A lockfile entry must never exist without its
+  // credential (every read path would 404 on the token), while a token
+  // without an entry is inert and overwritten by the next import. The prior
+  // token contents are kept in memory so a failed lockfile write below can
+  // roll the file back.
+  const tokenPath = guardianTokenPath(configDir, localId);
+  let priorToken: string | null;
+  try {
+    priorToken = fs.readFileSync(tokenPath, "utf-8");
+  } catch {
+    priorToken = null;
+  }
+
+  const now = Date.now();
+  try {
+    saveGuardianToken(configDir, localId, {
+      guardianPrincipalId: "imported",
+      accessToken: bundle.token,
+      accessTokenExpiresAt:
+        jwtExpiryMs(bundle.token) ?? now + 24 * 60 * 60 * 1000,
+      refreshToken: bundle.refreshToken ?? "",
+      refreshTokenExpiresAt: bundle.refreshTokenExpiresAt ?? 0,
+      refreshAfter: bundle.refreshAfter ?? "",
+      isNew: false,
+      deviceId: bundle.deviceId ?? "",
+      leasedAt: new Date(now).toISOString(),
+      pairedGatewayUrl: bundle.gatewayUrl,
+    });
+  } catch (err) {
+    return {
+      ok: false,
+      status: 500,
+      error: `Failed to write the guardian token: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    };
+  }
+
+  const writeResult = upsertLockfileAssistant(
+    lockfilePaths,
+    {
+      assistantId: localId,
+      name: name ?? `paired (${gatewayHost})`,
+      runtimeUrl: bundle.gatewayUrl,
+      // Paired entries are reached by bearer token at the remote runtimeUrl
+      // (a non-"vellum" cloud selects the bearer-token auth path in client.ts).
+      // The "paired" topology lets lifecycle/status commands (ps/wake/sleep)
+      // recognize this as a remote pairing rather than an on-machine process.
+      cloud: "paired",
+      // Marks this entry as a connect-import so re-imports update in place
+      // while imports never silently overwrite a non-paired assistant (see
+      // guard above).
+      paired: true,
+      species: "vellum",
+    },
+    undefined,
+  );
+  if (!writeResult.ok) {
+    // The entry was not registered, so undo the token write (best-effort;
+    // the write failure itself is what gets reported): restore the prior
+    // token of a re-import, or delete the freshly written one.
+    try {
+      if (priorToken !== null) {
+        fs.writeFileSync(tokenPath, priorToken, { mode: 0o600 });
+      } else {
+        fs.rmSync(tokenPath, { force: true });
+        fs.rmdirSync(path.dirname(tokenPath));
+      }
+    } catch {
+      // Rollback failed; the reported write error already covers the outcome.
+    }
+    return writeResult;
+  }
+
+  return {
+    ok: true,
+    assistantId: localId,
+    updated: existing !== undefined,
+    // A refresh token is only usable over a confidential channel; with
+    // loopback refused above, a plaintext http gateway can never renew, so it
+    // is reported access-only and gets the expiry warning.
+    accessOnly:
+      !bundle.refreshToken || !isConfidentialRefreshUrl(bundle.gatewayUrl),
+  };
+}
+
+/**
+ * Bounds what an untrusted connect-import request can make a host buffer and
+ * decode. Enforced by {@link connectImport} for every host.
+ */
+export const MAX_PAIR_BUNDLE_LENGTH = 64 * 1024;
+
+export interface ConnectImportOptions {
+  /** The encoded bundle exactly as received from the transport. */
+  bundle: unknown;
+  /** Optional local name; non-string or empty values are ignored. */
+  name?: unknown;
+}
+
+/**
+ * Wire-shaped result of a connect-import: the success members are the response
+ * body fields, and `status` on failure is the HTTP status the loopback hosts
+ * respond with (the IPC host ignores it).
+ */
+export type ConnectImportResult =
+  | { ok: true; assistantId: string; accessOnly: boolean }
+  | { ok: false; status: number; error: string };
+
+/**
+ * The complete connect-import host operation: validate the raw bundle value
+ * (present, non-empty, within {@link MAX_PAIR_BUNDLE_LENGTH}), decode it, and
+ * register the pairing via {@link pairAssistant}. Hosts keep only
+ * transport-specific parsing and pass the untrusted values straight through,
+ * so bundle limits, error strings, and the result shape are defined once.
+ */
+export function connectImport(
+  lockfilePaths: string[],
+  configDir: string,
+  { bundle, name }: ConnectImportOptions,
+): ConnectImportResult {
+  if (typeof bundle !== "string" || !bundle) {
+    return { ok: false, status: 400, error: "Missing pairing bundle" };
+  }
+  if (bundle.length > MAX_PAIR_BUNDLE_LENGTH) {
+    return { ok: false, status: 400, error: "Pairing bundle is too large" };
+  }
+  const decoded = decodePairBundle(bundle.trim());
+  if (!decoded.ok) {
+    return { ok: false, status: 400, error: decoded.error };
+  }
+  const result = pairAssistant(lockfilePaths, configDir, {
+    bundle: decoded.bundle,
+    name: typeof name === "string" && name ? name : undefined,
+  });
+  if (!result.ok) {
+    return { ok: false, status: result.status, error: result.error };
+  }
+  return {
+    ok: true,
+    assistantId: result.assistantId,
+    accessOnly: result.accessOnly,
+  };
+}

package/node_modules/@vellumai/local-mode/src/paths.ts

@@ -0,0 +1,49 @@
+import os from "node:os";
+import path from "node:path";
+export interface LocalPathOptions {
+  platform?: NodeJS.Platform;
+  homeDir?: string;
+  environmentName?: string;
+  configDirOverride?: string;
+  lockfileDirOverride?: string;
+}
+const isWindows = (options: LocalPathOptions) => (options.platform ?? process.platform) === "win32";
+const paths = (options: LocalPathOptions) =>
+  isWindows(options) ? path.win32 : path.posix;
+const home = (options: LocalPathOptions) => options.homeDir ?? os.homedir();
+export function resolveConfigHome(env: Record<string, string | undefined>, options: LocalPathOptions = {}): string {
+  if (isWindows(options)) {
+    return env.APPDATA?.trim() || paths(options).join(home(options), "AppData", "Roaming");
+  }
+  return env.XDG_CONFIG_HOME?.trim() || paths(options).join(home(options), ".config");
+}
+export function resolveConfigHomes(env: Record<string, string | undefined>, options: LocalPathOptions = {}): string[] {
+  const canonical = resolveConfigHome(env, options);
+  if (!isWindows(options)) {
+    return [canonical];
+  }
+  const legacy =
+    env.XDG_CONFIG_HOME?.trim() || paths(options).join(home(options), ".config");
+  return canonical === legacy ? [canonical] : [canonical, legacy];
+}
+export function resolveDataHome(env: Record<string, string | undefined>, options: LocalPathOptions = {}): string {
+  if (isWindows(options)) {
+    return env.LOCALAPPDATA?.trim() || paths(options).join(home(options), "AppData", "Local");
+  }
+  return env.XDG_DATA_HOME?.trim() || paths(options).join(home(options), ".local", "share");
+}
+export const joinLocalPath = (options: LocalPathOptions, ...segments: string[]) =>
+  paths(options).join(...segments);
+export function assertSafePathSegment(value: string, label: string, options: LocalPathOptions = {}): void {
+  const unsafe =
+    !value ||
+    /[/\\\0]/.test(value) ||
+    /^\.{1,2}$/.test(value) ||
+    (isWindows(options) &&
+      (/[<>:"|?*\u0000-\u001f]/.test(value) ||
+        /[. ]$/.test(value) ||
+        /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(value)));
+  if (unsafe) {
+    throw new Error(`Invalid ${label}: ${value}`);
+  }
+}

package/node_modules/@vellumai/local-mode/src/status.ts

@@ -1,12 +1,14 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
-import os from "node:os";
 import http from "node:http";
 import path from "node:path";
 
 import { SEEDS } from "@vellumai/environments";
 
+import { resolveInstanceDir } from "./config";
+import { resolveEnvironmentName } from "./environment";
 import type { LockfileAssistant } from "./lockfile-contract";
 import { getLockfileData } from "./lockfile";
+import { assertSafePathSegment } from "./paths";
 
 const HEALTH_TIMEOUT_MS = 1_500;
 const STARTING_GRACE_MS = 60_000;
@@ -209,7 +211,7 @@ function defaultPorts(env: Record<string, string | undefined>): {
   daemon: number;
   gateway: number;
 } {
-  const envName = env.VELLUM_ENVIRONMENT?.trim() || PRODUCTION_ENVIRONMENT_NAME;
+  const envName = resolveEnvironmentName(env);
   const seed = SEEDS[envName] ?? SEEDS[PRODUCTION_ENVIRONMENT_NAME];
   return {
     daemon: seed?.portsOverride?.daemon ?? DEFAULT_PORTS.daemon,
@@ -221,12 +223,7 @@ function defaultInstanceDir(
   env: Record<string, string | undefined>,
   assistantId: string,
 ): string {
-  const envName = env.VELLUM_ENVIRONMENT?.trim() || PRODUCTION_ENVIRONMENT_NAME;
-  const xdgDataHome =
-    env.XDG_DATA_HOME?.trim() || path.join(os.homedir(), ".local", "share");
-  const dataRoot =
-    envName === PRODUCTION_ENVIRONMENT_NAME ? "vellum" : `vellum-${envName}`;
-  return path.join(xdgDataHome, dataRoot, "assistants", assistantId);
+  return resolveInstanceDir(env, assistantId);
 }
 
 function firstString(...values: unknown[]): string | undefined {
@@ -394,6 +391,11 @@ export async function getLocalAssistantStatus(
   assistantId: string,
   env: Record<string, string | undefined> = process.env,
 ): Promise<LocalAssistantStatusResult> {
+  try {
+    assertSafePathSegment(assistantId, "assistant ID");
+  } catch {
+    return { ok: false, status: 400, error: "Invalid assistant ID" };
+  }
   const result = getLockfileData(lockfilePaths);
   if (!result.ok) {
     return {

package/node_modules/@vellumai/local-mode/src/unpair.ts

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { guardianTokenPath } from "./config";
+import {
+  readRawLockfile,
+  writeRawLockfile,
+  type WriteResult,
+} from "./lockfile";
+import { resolveCloud } from "./lockfile-contract";
+
+/**
+ * Forget a paired assistant on this machine: remove its lockfile entry and
+ * delete its stored guardian token. Client-side only, mirroring the CLI's
+ * `vellum unpair`: the remote assistant itself is never touched (host-side
+ * device revocation is `vellum devices`). Only pairing records
+ * (`cloud: "paired"`, created by `vellum connect import`) are forgettable this
+ * way; local and managed assistants go through retire.
+ */
+export function unpairAssistant(
+  lockfilePaths: string[],
+  configDir: string,
+  assistantId: string,
+): WriteResult {
+  const lockfile = readRawLockfile(lockfilePaths);
+  const assistants = Array.isArray(lockfile.assistants)
+    ? (lockfile.assistants as Array<Record<string, unknown>>)
+    : [];
+  const entry = assistants.find((a) => a?.assistantId === assistantId);
+  if (!entry) {
+    return { ok: false, status: 404, error: "No such assistant" };
+  }
+  if (resolveCloud(entry) !== "paired") {
+    return {
+      ok: false,
+      status: 400,
+      error:
+        "Only paired assistants can be unpaired. Use retire for local or managed assistants.",
+    };
+  }
+
+  // Delete the token BEFORE committing the lockfile removal. A failed delete
+  // aborts with the entry intact, so unpair stays retryable; the reverse order
+  // would strand the credential on disk forever (the retry 404s on the
+  // already-removed entry and never reaches cleanup). The token contents are
+  // kept in memory so a failed lockfile write below can restore them.
+  const tokenPath = guardianTokenPath(configDir, assistantId);
+  let savedToken: string | null = null;
+  try {
+    savedToken = fs.readFileSync(tokenPath, "utf-8");
+  } catch {
+    savedToken = null;
+  }
+  try {
+    fs.rmSync(tokenPath, { force: true });
+  } catch (err) {
+    return {
+      ok: false,
+      status: 500,
+      error: `Failed to delete the stored guardian token: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    };
+  }
+  try {
+    fs.rmdirSync(path.dirname(tokenPath));
+  } catch {
+    // Directory not empty or absent.
+  }
+
+  const remaining = assistants.filter((a) => a?.assistantId !== assistantId);
+  lockfile.assistants = remaining;
+  // Reassign the active assistant like the CLI's removeAssistantEntry does, so
+  // unpairing through the bridge and through `vellum unpair` leave the same
+  // active state. Skip tolerated malformed entries (no string assistantId):
+  // parseLockfile drops them from the returned lockfile, so pointing at one
+  // would report no active assistant while valid entries remain.
+  if (lockfile.activeAssistant === assistantId) {
+    const next = remaining.find(
+      (a) => typeof a?.assistantId === "string",
+    )?.assistantId;
+    if (typeof next === "string") {
+      lockfile.activeAssistant = next;
+    } else {
+      delete lockfile.activeAssistant;
+    }
+  }
+
+  const result = writeRawLockfile(lockfilePaths, lockfile);
+  if (!result.ok && savedToken !== null) {
+    // The entry is still listed, so put its credential back (best-effort;
+    // the write failure itself is what gets reported).
+    try {
+      fs.mkdirSync(path.dirname(tokenPath), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(tokenPath, savedToken, { mode: 0o600 });
+    } catch {
+      // Restore failed; the reported write error already covers the outcome.
+    }
+  }
+  return result;
+}

package/node_modules/@vellumai/local-mode/src/util.ts

@@ -71,6 +71,40 @@ export function originIsAllowed(originHeader: string | undefined): boolean {
   }
 }
 
+/**
+ * Require browser-controlled proof that a request came from the loopback HTTP
+ * origin named by its Host header. Conflicting Origin or Fetch Metadata values
+ * are rejected even when the other signal is valid.
+ */
+export function hasSameOriginCredentialProof(
+  hostHeader: string | undefined,
+  originHeader: string | undefined,
+  secFetchSiteHeader: string | undefined,
+): boolean {
+  if (!hostHeader || !headerHostIsLoopback(hostHeader)) {
+    return false;
+  }
+
+  let hasMatchingOrigin = false;
+  if (originHeader) {
+    try {
+      hasMatchingOrigin =
+        new URL(originHeader).origin === new URL(`http://${hostHeader}`).origin;
+    } catch {
+      return false;
+    }
+    if (!hasMatchingOrigin) {
+      return false;
+    }
+  }
+
+  if (secFetchSiteHeader && secFetchSiteHeader !== "same-origin") {
+    return false;
+  }
+
+  return hasMatchingOrigin || secFetchSiteHeader === "same-origin";
+}
+
 export function isLoopbackAddr(addr: string): boolean {
   const v4Mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
   const normalized = v4Mapped ? v4Mapped[1]! : addr;

package/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -40,3 +40,42 @@ export function isChannelId(value: unknown): value is ChannelId {
     (CHANNEL_IDS as readonly string[]).includes(value)
   );
 }
+
+/**
+ * The provider key holding each channel's bot credential.
+ *
+ * Two senses of "connected" share the provider registry: a provider the user
+ * authorized so the assistant can act **as them** (`slack`, `discord`,
+ * `google`), and a bot credential letting people reach the assistant **as
+ * itself**. Nothing in a provider key says which, and the naming actively
+ * misleads: `slack` and `discord` name the user integration while their bots
+ * take a `_channel` suffix, yet `telegram` *is* the bot, because Telegram has
+ * no user-identity integration.
+ *
+ * That irregularity is why this is stated rather than derived from the key,
+ * and it is stated here because this file already owns what a channel is.
+ *
+ * Deliberately only the key. What fields each credential requires is declared
+ * once already, per service, in the gateway's credential specs; restating it
+ * here would be a second copy of a different fact.
+ *
+ * Channels absent from this map reach the assistant without a bot credential
+ * of their own: `phone` through the voice provider, `vellum` and `platform`
+ * internally.
+ */
+export const CHANNEL_BOT_PROVIDER = {
+  slack: "slack_channel",
+  discord: "discord_channel",
+  telegram: "telegram",
+} as const satisfies Partial<Record<ChannelId, string>>;
+
+/**
+ * Whether a provider key names a bot the assistant is reached through, rather
+ * than a grant letting it act as the user. This is the "which sense of
+ * connected" question, for any provider key.
+ */
+export function isChannelBotProvider(providerKey: string): boolean {
+  return (Object.values(CHANNEL_BOT_PROVIDER) as readonly string[]).includes(
+    providerKey,
+  );
+}

package/node_modules/@vellumai/service-contracts/src/ingress.ts

@@ -20,6 +20,16 @@ export function normalizePublicBaseUrl(value: unknown): string | undefined {
   return normalized.length > 0 ? normalized : undefined;
 }
 
+/**
+ * Application close code the gateway's velay bridge sends to proxied
+ * WebSockets when the tunnel itself is lost (velay disconnect, gateway
+ * shutdown). A dedicated code because the natural 1001 (going away) cannot
+ * be sent through the JS `close()` API (the bridge would remap it to a
+ * misleading 4001), and Bun's WebSocket client drops close reasons, so the
+ * code is the only signal that survives the relay to the daemon.
+ */
+export const GATEWAY_TUNNEL_LOST_WS_CLOSE_CODE = 4801;
+
 export function normalizeHttpPublicBaseUrl(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();

package/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -21,6 +21,12 @@
  * `Date#toISOString()`.
  */
 
+/**
+ * Pairing-challenge TTL in milliseconds (10 minutes): the gateway's challenge
+ * store enforces it and the `vellum pair` CLI renders it in user-facing copy.
+ */
+export const REMOTE_WEB_PAIRING_CODE_TTL_MS = 10 * 60 * 1000;
+
 /** `POST /v1/remote-web/pairing-challenge` request body. */
 export interface RemoteWebPairingChallengeRequest {
   /** Public https base URL the scanning device can reach the assistant at. */