@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/node_modules/@vellumai/environments/src/index.ts

@@ -1,11 +1,22 @@
 /**
- * @vellumai/environments — the single source of truth for Vellum's known
- * deployment environments (names, platform/web URLs, per-service port
- * blocks). Consumed by the CLI, the assistant daemon, and the local-mode
- * host library so the environment list is defined exactly once on the TS
- * side. The Swift client mirrors the same set in `VellumEnvironment.swift`.
+ * @vellumai/environments: the single source of truth for how a Vellum install
+ * is laid out and which deployment environment it belongs to.
  *
- * Intentionally free of runtime dependencies: pure types and constants only.
+ * Two things live here:
+ *
+ *   - The known deployment environments (names, platform/web URLs, per-service
+ *     port blocks). The Swift client mirrors the same set in
+ *     `VellumEnvironment.swift`.
+ *   - Install layout: whether a runtime is a repo checkout or an installed
+ *     package, and where the `assistant` command it ships lives.
+ *
+ * Consumed by the CLI, the assistant daemon, and the local-mode host library
+ * so each answer is defined exactly once on the TS side.
+ *
+ * This is the lowest layer of the shared-packages hierarchy and stays a leaf:
+ * types, constants, and small helpers over node builtins, with no runtime
+ * dependencies of its own. See `__tests__/package-boundary.test.ts`.
  */
 export * from "./types.js";
 export * from "./seeds.js";
+export * from "./install-layout.js";

package/node_modules/@vellumai/environments/src/install-layout.ts

@@ -0,0 +1,49 @@
+/**
+ * Reading the layout a Vellum runtime is installed in.
+ *
+ * The daemon is started either from a developer's repo checkout or from an
+ * installed npm package (`<install>/node_modules/@vellumai/assistant/src/
+ * index.ts`, which is what the desktop app runs). The CLI needs the layout to
+ * decide whether a launch is a dev run and what to put on the daemon's PATH;
+ * the daemon needs it to decide what to install as the `assistant` command.
+ * Both ask the same two questions, so they ask them here.
+ */
+
+import { existsSync } from "node:fs";
+import { join, sep } from "node:path";
+
+const NODE_MODULES_SEGMENT = `${sep}node_modules${sep}`;
+
+/**
+ * Whether `path` sits in a developer's repo checkout rather than inside an
+ * installed package.
+ */
+export function isRepoCheckoutPath(path: string): boolean {
+  return !path.includes(NODE_MODULES_SEGMENT);
+}
+
+/**
+ * The `assistant` command shipped with the install that contains `path`, or
+ * null when there is none (a repo checkout, or an install whose dependency
+ * graph omits the package declaring the bin).
+ *
+ * Searches innermost `node_modules` outward, since a nested install shadows a
+ * hoisted one.
+ */
+export function findAssistantCommand(path: string): string | null {
+  let index = path.lastIndexOf(NODE_MODULES_SEGMENT);
+
+  while (index !== -1) {
+    const nodeModulesDir = path.slice(
+      0,
+      index + NODE_MODULES_SEGMENT.length - 1,
+    );
+    const command = join(nodeModulesDir, ".bin", "assistant");
+    if (existsSync(command)) {
+      return command;
+    }
+    index = path.lastIndexOf(NODE_MODULES_SEGMENT, index - 1);
+  }
+
+  return null;
+}

package/node_modules/@vellumai/environments/src/seeds.ts

@@ -24,6 +24,35 @@ function portBlock(base: number): PortMap {
   };
 }
 
+/**
+ * Base URL of the cloud-hosted assistant SPA (the "hub") for a deployment
+ * environment. The Capacitor mobile shell bakes this into native builds as
+ * `server.url`, and the CLI's remote-web edge stamps it into the served
+ * config as `hubUrl`, so the environment-to-hub mapping lives here exactly
+ * once.
+ *
+ * Only the cloud deployments (production, staging) serve the hosted SPA at
+ * their own web origin; every other environment (dev, test, local, unknown)
+ * falls back to the dev SPA, whose host serves remote clients that cannot
+ * reach a local or per-developer web URL.
+ *
+ * The `/assistant` suffix is deliberate: booting on the bare host lands on
+ * the marketing page, whose CTA redirects to `www.vellum.ai/assistant` and
+ * bounces non-prod shells off their own host.
+ *
+ * NOTE: this module is loaded by Capacitor's single-file TS config loader
+ * (via the `@vellumai/environments/seeds` subpath), which cannot follow the
+ * package index's `.js`-suffixed runtime re-exports. Keep this file's
+ * imports type-only so it stays loadable on its own.
+ */
+export function cloudAssistantHubUrl(envName: string | undefined): string {
+  const seed =
+    envName === "production" || envName === "staging"
+      ? SEEDS[envName]
+      : SEEDS.dev;
+  return `${seed.webUrl}/assistant`;
+}
+
 /**
  * Built-in environment definitions and the source of truth for the
  * set of known environment names.

package/node_modules/@vellumai/gateway-client/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/gateway-client/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/gateway-client/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. */

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -157,6 +157,8 @@ export {
   hashVerificationSecret,
   IdentityBindingStatusSchema,
   ResolveBootstrapSessionIpcParamsSchema,
+  bindsSameIdentity,
+  boundIdentity,
   RevokePendingSessionsIpcParamsSchema,
   SessionLookupIpcResponseSchema,
   SessionMutationIpcResponseSchema,
@@ -172,6 +174,7 @@ export {
 
 export type {
   BindSessionIdentityIpcParams,
+  BoundIdentity,
   CountRecentSendsIpcParams,
   CountRecentSendsIpcResponse,
   CreateInboundSessionIpcParams,
@@ -183,6 +186,7 @@ export type {
   FindActiveSessionIpcParams,
   GetPendingSessionIpcParams,
   IdentityBindingStatus,
+  IdentityBoundSession,
   ResolveBootstrapSessionIpcParams,
   RevokePendingSessionsIpcParams,
   SessionLookupIpcResponse,

package/node_modules/@vellumai/gateway-client/src/verification-session-contract.ts

@@ -113,6 +113,78 @@ export const VerificationSessionSchema = z.object({
 
 export type VerificationSessionWire = z.infer<typeof VerificationSessionSchema>;
 
+// ---------------------------------------------------------------------------
+// Bound identity (which of the three identity columns decides who may redeem)
+// ---------------------------------------------------------------------------
+
+/** The identity fields the rules read. Callers may pass a full session row. */
+export interface IdentityBoundSession {
+  expectedExternalUserId?: string | null;
+  expectedChatId?: string | null;
+  expectedPhoneE164?: string | null;
+}
+
+/**
+ * The identity a session redeems on.
+ *
+ * `chatId` is compared against the actor's conversation and everything else
+ * against the actor themselves, which is why the field travels with the value.
+ */
+export interface BoundIdentity {
+  field: "phoneE164" | "externalUserId" | "chatId";
+  value: string;
+}
+
+/**
+ * The one identity a session is bound to, or null when it is bound to none
+ * (an inbound challenge, or a bootstrap session before its deep link is
+ * redeemed).
+ *
+ * This lives in the contract because more than one side has to agree on it:
+ * the gateway consume path decides who may redeem a code, and the supersede
+ * scope decides whose earlier codes a fresh mint kills. Those two disagreeing
+ * is a silent one-time-code bug, so the rule is stated once.
+ *
+ * Precedence, most to least specific:
+ *
+ * 1. `expectedPhoneE164` (a voice session's subject is the number itself).
+ * 2. `expectedExternalUserId` (the person).
+ * 3. `expectedChatId` (the conversation), and only when nothing identifies a
+ *    person. A chat id can be shared (a Slack channel, a Telegram group), so
+ *    on its own it would let any participant satisfy the binding. It counts
+ *    only where there is no better answer.
+ */
+export function boundIdentity(
+  session: IdentityBoundSession,
+): BoundIdentity | null {
+  // Presence, not truthiness. An empty string is a set-but-useless identity,
+  // and treating it as absent would report the session unbound, which the
+  // consume path reads as "no identity to check" and admits anyone holding
+  // the code. Kept as a value it can compare against and fail instead.
+  if (session.expectedPhoneE164 != null) {
+    return { field: "phoneE164", value: session.expectedPhoneE164 };
+  }
+  if (session.expectedExternalUserId != null) {
+    return { field: "externalUserId", value: session.expectedExternalUserId };
+  }
+  if (session.expectedChatId != null) {
+    return { field: "chatId", value: session.expectedChatId };
+  }
+  return null;
+}
+
+/**
+ * Whether two sessions are bound to the same identity. Two sessions bound to
+ * no identity are not the same: bootstrap sessions are claimed by id, so an
+ * unbound mint must not sweep up every other unbound row.
+ */
+export function bindsSameIdentity(
+  a: BoundIdentity | null,
+  b: BoundIdentity | null,
+): boolean {
+  return a !== null && b !== null && a.field === b.field && a.value === b.value;
+}
+
 // ---------------------------------------------------------------------------
 // IPC methods
 // ---------------------------------------------------------------------------
@@ -193,9 +265,12 @@ export type CreateInboundSessionIpcResponse = z.infer<
 /** Request for `verification_sessions_create_outbound`. */
 export const CreateOutboundSessionIpcParamsSchema = z.object({
   channel: z.string().min(1),
-  expectedExternalUserId: z.string().optional(),
-  expectedChatId: z.string().optional(),
-  expectedPhoneE164: z.string().optional(),
+  // An identity field is either absent or a real value. An empty string is
+  // neither, and a session bound to one can never be redeemed by anybody,
+  // so reject it at the boundary rather than mint a dead code.
+  expectedExternalUserId: z.string().min(1).optional(),
+  expectedChatId: z.string().min(1).optional(),
+  expectedPhoneE164: z.string().min(1).optional(),
   identityBindingStatus: IdentityBindingStatusSchema.optional(),
   destinationAddress: z.string().optional(),
   codeDigits: z.number().int().positive().optional(),
@@ -211,7 +286,6 @@ export const CreateOutboundSessionIpcParamsSchema = z.object({
   requireSourceSessionPending: z.string().min(1).optional(),
   // Mint only if the channel has no active (pending_bootstrap /
   // awaiting_response, non-expired) session.
-  ifNoneActive: z.boolean().optional(),
   // Sender-scoped variant: mint unless the channel's active session is bound
   // to this expectedExternalUserId (a different sender may supersede).
   ifNoneActiveForExternalUserId: z.string().min(1).optional(),
@@ -240,7 +314,8 @@ export type CreateOutboundSessionIpcResponse = z.infer<
 
 /**
  * Conflict marker returned by `verification_sessions_create_outbound` when a
- * claim guard (`requireSourceSessionPending` / `ifNoneActive`) fails. Only
+ * claim guard (`requireSourceSessionPending` /
+ * `ifNoneActiveForExternalUserId`) fails. Only
  * reachable when a guard was passed — legacy callers never see this shape.
  */
 export const CreateOutboundSessionConflictSchema = z.object({
@@ -277,7 +352,17 @@ export type GetPendingSessionIpcParams = z.infer<
  * Request for `verification_sessions_find_active` (statuses
  * `pending_bootstrap`/`awaiting_response`, newest first).
  */
-export const FindActiveSessionIpcParamsSchema = ChannelOnlyIpcParamsSchema;
+export const FindActiveSessionIpcParamsSchema =
+  ChannelOnlyIpcParamsSchema.extend({
+    /**
+     * Narrows the lookup to one session. A channel can carry several live
+     * sessions at once, one per person verifying plus the guardian's own flow,
+     * so a caller that means a particular one has to say which. Omitted, the
+     * lookup returns whoever started most recently.
+     */
+    expectedExternalUserId: z.string().min(1).optional(),
+    verificationPurpose: VerificationPurposeSchema.optional(),
+  });
 
 export type FindActiveSessionIpcParams = z.infer<
   typeof FindActiveSessionIpcParamsSchema

package/node_modules/@vellumai/ipc-server-utils/src/endpoint.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { removeIpcEndpointFile, resolveIpcEndpoint } from "./endpoint.js";
+const windowsEndpoint = (name: string, workspaceDir: string) => resolveIpcEndpoint(name, { workspaceDir, platform: "win32" });
+describe("resolveIpcEndpoint", () => {
+  test("keeps long POSIX fallbacks deterministic and bounded", () => {
+    const options = {
+      workspaceDir: `/tmp/${"a".repeat(120)}`,
+      platform: "darwin" as const,
+    };
+    const endpoint = resolveIpcEndpoint("assistant", options);
+    expect(resolveIpcEndpoint("assistant", options)).toEqual(endpoint);
+    expect(Buffer.byteLength(endpoint.path)).toBeLessThanOrEqual(103);
+  });
+  test("returns normalized, isolated, bounded Windows pipes", () => {
+    const first = windowsEndpoint("assistant", "C:\\one");
+    expect(resolveIpcEndpoint("assistant", { workspaceDir: "c:\\ONE\\", platform: "win32", env: { ASSISTANT_IPC_SOCKET_DIR: "C:\\ignored" } })).toEqual(first);
+    expect(first.path.length).toBeLessThanOrEqual(256);
+    expect(windowsEndpoint("assistant", "C:\\two").path).not.toBe(first.path);
+    expect(windowsEndpoint("gateway", "C:\\one").path).not.toBe(first.path);
+  });
+  test("cleans socket files but skips named pipes", () => {
+    const dir = mkdtempSync(join(tmpdir(), "vellum-ipc-cleanup-"));
+    const socketPath = join(dir, "assistant.sock");
+    try {
+      writeFileSync(socketPath, "stale");
+      removeIpcEndpointFile(socketPath);
+      expect(existsSync(socketPath)).toBe(false);
+      removeIpcEndpointFile("\\\\.\\pipe\\vellum-assistant-test");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/node_modules/@vellumai/ipc-server-utils/src/endpoint.ts

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { posix, win32 } from "node:path";
+
+const DARWIN_UNIX_SOCKET_MAX_PATH_BYTES = 103;
+const DEFAULT_UNIX_SOCKET_MAX_PATH_BYTES = 107;
+const IPC_TMP_DIR_NAME = "vellum-ipc";
+const join = posix.join;
+
+export type IpcSocketPathSource =
+  | "env-override"
+  | "workspace"
+  | "tmp-hash"
+  | "tmp-short-hash"
+  | "windows-named-pipe";
+
+export interface IpcSocketPathResolution {
+  path: string;
+  source: IpcSocketPathSource;
+}
+
+export interface IpcEndpointOptions {
+  workspaceDir: string;
+  env?: Record<string, string | undefined>;
+  platform?: NodeJS.Platform;
+}
+
+function getUnixSocketMaxPathBytes(platform: NodeJS.Platform): number {
+  return platform === "darwin"
+    ? DARWIN_UNIX_SOCKET_MAX_PATH_BYTES
+    : DEFAULT_UNIX_SOCKET_MAX_PATH_BYTES;
+}
+
+function isPathWithinSocketLimit(path: string, maxPathBytes: number): boolean {
+  return Buffer.byteLength(path, "utf8") <= maxPathBytes;
+}
+
+/**
+ * Derive the env var name and socket filename from a socket name.
+ *
+ * Examples (hyphens in the name become underscores in the env var):
+ */
+function deriveSocketNames(socketName: string): {
+  envVar: string;
+  fileName: string;
+} {
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(socketName)) {
+    throw new Error(`Invalid IPC endpoint name: ${socketName}`);
+  }
+  const envVar = `${socketName.toUpperCase().replace(/-/g, "_")}_IPC_SOCKET_DIR`;
+  const fileName = `${socketName}.sock`;
+  return { envVar, fileName };
+}
+
+function resolveWindowsNamedPipe(
+  socketName: string,
+  workspaceDir: string,
+): IpcSocketPathResolution {
+  const workspaceIdentity = win32
+    .normalize(workspaceDir)
+    .replace(/\\+$/, "")
+    .toLowerCase();
+  const hash = createHash("sha256")
+    .update(`${workspaceIdentity}\0${socketName}`)
+    .digest("hex")
+    .slice(0, 24);
+  return {
+    path: `\\\\.\\pipe\\vellum-${socketName}-${hash}`,
+    source: "windows-named-pipe",
+  };
+}
+
+export function isNamedPipePath(endpointPath: string): boolean {
+  return /^\\\\[.?]\\pipe\\/.test(endpointPath);
+}
+
+export function removeIpcEndpointFile(endpointPath: string): void {
+  if (isNamedPipePath(endpointPath)) {
+    return;
+  }
+  try {
+    unlinkSync(endpointPath);
+  } catch {
+    // Already absent.
+  }
+}
+
+/**
+ * Resolve the path to an IPC socket file.
+ *
+ * Resolution order:
+ * POSIX uses overrides, workspace paths, then bounded temporary paths.
+ * Windows uses deterministic named pipes.
+ */
+export function resolveIpcEndpoint(
+  socketName: string,
+  options: IpcEndpointOptions,
+): IpcSocketPathResolution {
+  const { envVar, fileName } = deriveSocketNames(socketName);
+  const platform = options.platform ?? process.platform;
+  if (platform === "win32") {
+    return resolveWindowsNamedPipe(socketName, options.workspaceDir);
+  }
+
+  // Explicit override via env var.
+  const envSocketDir = (options.env ?? process.env)[envVar]?.trim();
+  if (envSocketDir) {
+    return {
+      path: join(envSocketDir, fileName),
+      source: "env-override",
+    };
+  }
+
+  const maxPathBytes = getUnixSocketMaxPathBytes(platform);
+  const workspacePath = join(options.workspaceDir, fileName);
+
+  if (isPathWithinSocketLimit(workspacePath, maxPathBytes)) {
+    return {
+      path: workspacePath,
+      source: "workspace",
+    };
+  }
+
+  // Workspace path exceeds AF_UNIX limit - fall back to tmpdir.
+  const hash = createHash("sha256")
+    .update(workspacePath)
+    .digest("hex")
+    .slice(0, 12);
+  const hashedPath = join(tmpdir(), IPC_TMP_DIR_NAME, `${hash}-${fileName}`);
+  if (isPathWithinSocketLimit(hashedPath, maxPathBytes)) {
+    return {
+      path: hashedPath,
+      source: "tmp-hash",
+    };
+  }
+
+  return {
+    path: join(tmpdir(), `v-${hash}.sock`),
+    source: "tmp-short-hash",
+  };
+}

package/node_modules/@vellumai/ipc-server-utils/src/index.ts

@@ -4,6 +4,8 @@ export {
   type SocketWatchdogOptions,
   type SocketWatchdogLogger,
 } from "./socket-watchdog.js";
+export { isNamedPipePath, removeIpcEndpointFile, resolveIpcEndpoint } from "./endpoint.js";
+export { ipcListenOptions } from "./listen-options.js";
 export {
   IpcFrameReader,
   writeLegacyMessage,

package/node_modules/@vellumai/ipc-server-utils/src/listen-options.ts

@@ -0,0 +1,3 @@
+export function ipcListenOptions(path: string) {
+  return { path, readableAll: false, writableAll: false } as const;
+}

package/node_modules/@vellumai/ipc-server-utils/src/socket-watchdog.test.ts

@@ -46,6 +46,7 @@ interface TestHarness {
 
 interface BuildOptions {
   intervalMs?: number;
+  socketPathOverride?: string;
   createServerOverride?: () => Server;
   /** Override `getServer` to simulate races. */
   getServerOverride?: () => Server | null;
@@ -75,7 +76,7 @@ function buildHarness(opts: BuildOptions): TestHarness {
   };
 
   const watchdog = new SocketWatchdog({
-    socketPath,
+    socketPath: opts.socketPathOverride ?? socketPath,
     intervalMs: opts.intervalMs ?? 0,
     getServer: opts.getServerOverride ?? (() => serverRef.current),
     createServer: opts.createServerOverride ?? defaultFactory,
@@ -190,6 +191,19 @@ describe("SocketWatchdog", () => {
     expect(harness.rebinds).toHaveLength(0);
   });
 
+  test("named pipes skip filesystem watchdog behavior", async () => {
+    const server = createServer();
+    harness = buildHarness({
+      socketPathOverride: "\\\\.\\pipe\\vellum-assistant-test",
+      getServerOverride: () => server,
+      createServerOverride: () => {
+        throw new Error("must not rebind");
+      },
+    });
+    harness.spawnedServers.push(server);
+    expect(await harness.watchdog.rebindIfMissing()).toBe(false);
+  });
+
   test("rebindIfMissing recreates the listener when the path is gone", async () => {
     harness = buildHarness({});
     const initial = await startInitialServer(harness);

package/node_modules/@vellumai/ipc-server-utils/src/socket-watchdog.ts

@@ -16,6 +16,9 @@ import { existsSync, mkdirSync, unlinkSync } from "node:fs";
 import type { Server } from "node:net";
 import { dirname } from "node:path";
 
+import { isNamedPipePath } from "./endpoint.js";
+import { ipcListenOptions } from "./listen-options.js";
+
 /**
  * Minimal logger surface (pino-compatible). Each method receives a context
  * object plus an optional human-readable message.
@@ -66,6 +69,9 @@ const DEFAULT_INTERVAL_MS = 5000;
  * `mkdir` only applies the mode to directories it creates.
  */
 export function ensureSocketDir(socketPath: string): void {
+  if (isNamedPipePath(socketPath)) {
+    return;
+  }
   const socketDir = dirname(socketPath);
   if (!existsSync(socketDir)) {
     mkdirSync(socketDir, { recursive: true, mode: 0o700 });
@@ -109,7 +115,13 @@ export class SocketWatchdog {
    * watchdog is already running.
    */
   start(): void {
-    if (this.intervalMs <= 0 || this.handle !== null) return;
+    if (
+      this.intervalMs <= 0 ||
+      this.handle !== null ||
+      isNamedPipePath(this.socketPath)
+    ) {
+      return;
+    }
     this.handle = setInterval(() => {
       // The async entry path of rebindIfMissing performs filesystem work
       // (ensureSocketDir, createServer) before its inner try/catch, so a
@@ -143,6 +155,9 @@ export class SocketWatchdog {
    * is not running, or a shutdown/restart raced the rebind.
    */
   async rebindIfMissing(): Promise<boolean> {
+    if (isNamedPipePath(this.socketPath)) {
+      return false;
+    }
     const initialServer = this.getServer();
     if (initialServer === null) return false;
     if (existsSync(this.socketPath)) return false;
@@ -167,7 +182,7 @@ export class SocketWatchdog {
         };
         newServer.once("error", onError);
         newServer.once("listening", onListening);
-        newServer.listen(this.socketPath);
+        newServer.listen(ipcListenOptions(this.socketPath));
       });
     } catch (err) {
       this.log.error(

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,
+  );
+}