@vellumai/assistant 0.11.4 → 0.11.5-dev.202608220019.a778cf0

package/src/inbound/tunnel-probe.ts

@@ -0,0 +1,261 @@
+/**
+ * Reachability probe for the public URL a tunnel exposes.
+ *
+ * A tunnel's public URL is recorded in the workspace config, but a recorded
+ * URL says nothing about whether anything still answers on it: the tunnel
+ * process can die, the nginx edge can stay up while the gateway behind it is
+ * down, and a URL can end up fronting a different assistant entirely. The
+ * probe asks the edge two questions at once, and the two answers carry very
+ * different weight:
+ *
+ *   - `GET /healthz` is the liveness verdict. Every ingress shape answers it:
+ *     the nginx edge proxies it to the gateway, and a tunnel pointed straight
+ *     at the gateway port serves it from the gateway itself. Anything but a
+ *     2xx means the URL is not usable at all, which is `unreachable`.
+ *   - `GET /assistant/__config` decides whether that live edge is one a device
+ *     can pair against. Only the nginx remote-web SPA edge serves it
+ *     (`buildRemoteWebIngressLocations` in `cli/src/lib/nginx-ingress.ts`),
+ *     and that is the same edge serving `/assistant/pair`, so an edge that
+ *     answers the config request with anything but that edge's own config is
+ *     an edge whose pair URL would 404. That is `unpairable`: alive, and no
+ *     use to a card whose whole job is pairing. A tunnel pointed straight at
+ *     the gateway, a bring-your-own HTTPS front that only proxies the gateway,
+ *     and a catch-all that answers every path with some JSON all land there.
+ *     A config request that gets no answer at all, because it lost the shared
+ *     deadline or the connection dropped under it, proves nothing either way,
+ *     and the live `/healthz` stands.
+ *
+ * The served config also carries the assistant's id, which is what separates
+ * `healthy` from `foreign`.
+ *
+ * Neither path is denylisted, so both are publicly reachable.
+ *
+ * The module takes a URL and an expected id and returns a verdict: it reads no
+ * config and knows nothing about workspace paths, which is what lets callers
+ * probe an arbitrary URL and lets tests run without network access.
+ */
+
+import {
+  normalizeHttpPublicBaseUrlWithoutTrailingSlash,
+  trimmedNonEmptyString,
+} from "@vellumai/service-contracts/ingress";
+
+import { isPlainObject } from "../util/object.js";
+import { truncate } from "../util/truncate.js";
+
+/**
+ * Verdict for one probe.
+ *
+ * `unpairable` means the edge answered the config request with something that
+ * is not the pairing edge's config, so it is alive without fronting the
+ * pairing app.
+ * `foreign` means the edge positively identified itself as a different
+ * assistant. Any case where either id is unknown is `healthy`: a config
+ * served by a CLI that predates the id, or a URL recorded before the id was
+ * saved, is version skew, not someone else's assistant.
+ */
+export type TunnelProbeResult =
+  | { kind: "healthy"; assistantId?: string; assistantName?: string }
+  | { kind: "unreachable"; detail: string }
+  | { kind: "unpairable"; detail?: string }
+  | { kind: "foreign"; assistantId?: string; assistantName?: string };
+
+const DEFAULT_TIMEOUT_MS = 4_000;
+
+/** Placeholder swapped in for the probed URL so `detail` stays URL-free. */
+const REDACTED_URL = "<url>";
+
+/** `detail` is rendered inline in a settings card, so it has to stay short. */
+const MAX_DETAIL_LENGTH = 120;
+
+/** Bound on the `cause` walk, so a self-referential chain cannot spin. */
+const MAX_CAUSE_DEPTH = 5;
+
+/** Wrappers fetch layers raise when the real reason sits one `cause` down. */
+const GENERIC_FETCH_MESSAGES = new Set(["fetch failed", "failed to fetch"]);
+
+/** Reported when the config path answers with a body that is not a config. */
+const UNREADABLE_CONFIG_DETAIL = "no assistant config served";
+
+/** Reported when a served body parses but is not the pairing edge's config. */
+const UNMARKED_CONFIG_DETAIL = "not a pairing edge config";
+
+/**
+ * Stamped into the served config by the nginx pairing edge and nothing else
+ * (`remoteWebIngressConfig` in `cli/src/lib/nginx-ingress.ts`), which makes it
+ * the marker that separates that edge from any other JSON a live URL serves.
+ */
+const PAIRING_EDGE_MODE = "remote-gateway";
+
+export async function probeTunnel(args: {
+  publicBaseUrl: string;
+  /** Id recorded when this URL was saved; omit to skip the identity check. */
+  expectedAssistantId?: string;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+}): Promise<TunnelProbeResult> {
+  if (args.publicBaseUrl.trim().length === 0) {
+    return { kind: "unreachable", detail: "no public base URL" };
+  }
+  // The same validation the config writers apply, so a value they would have
+  // rejected is named as malformed rather than handed to `fetch` and reported
+  // through whatever string that layer happens to produce.
+  const base = normalizeHttpPublicBaseUrlWithoutTrailingSlash(
+    args.publicBaseUrl,
+  );
+  if (base === undefined) {
+    return { kind: "unreachable", detail: "not an http(s) URL" };
+  }
+
+  const fetchImpl = args.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  // One deadline covers both requests: only an answered config request can
+  // demote a live edge, so a slow edge that answers `/healthz` and loses the
+  // config request to the same deadline keeps its liveness verdict.
+  const signal = AbortSignal.timeout(args.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  const [health, config] = await Promise.allSettled([
+    fetchImpl(`${base}/healthz`, { signal }),
+    fetchImpl(`${base}/assistant/__config`, { signal }),
+  ]);
+  const configResponse =
+    config.status === "fulfilled" ? config.value : undefined;
+
+  if (health.status === "rejected") {
+    await discardBody(configResponse);
+    return unreachable(describeError(health.reason), base);
+  }
+  // Liveness is the status line; the health body is never read.
+  await discardBody(health.value);
+  if (!health.value.ok) {
+    await discardBody(configResponse);
+    return unreachable(`HTTP ${health.value.status}`, base);
+  }
+
+  const served = await readServedConfig(configResponse);
+  if (served.kind === "notServed") {
+    return { kind: "unpairable", detail: served.detail };
+  }
+
+  const identity = served.kind === "served" ? served.config : {};
+  const expected = trimmedNonEmptyString(args.expectedAssistantId);
+  const isForeign =
+    expected !== undefined &&
+    identity.assistantId !== undefined &&
+    identity.assistantId !== expected;
+
+  return { kind: isForeign ? "foreign" : "healthy", ...identity };
+}
+
+/**
+ * Fetch layers vary in how much of the request they echo into an error
+ * message, and the caller already knows which URL it asked about.
+ */
+function unreachable(detail: string, base: string): TunnelProbeResult {
+  return {
+    kind: "unreachable",
+    detail: truncate(detail.replaceAll(base, REDACTED_URL), MAX_DETAIL_LENGTH),
+  };
+}
+
+/**
+ * An unread fetch body pins its socket until GC under Bun and undici, and the
+ * probe runs on every settings mount, resume, and manual refresh.
+ */
+async function discardBody(response: Response | undefined): Promise<void> {
+  try {
+    await response?.body?.cancel();
+  } catch {
+    /* best effort */
+  }
+}
+
+function isTimeoutError(error: unknown): boolean {
+  return (
+    isPlainObject(error) &&
+    (error.name === "TimeoutError" || error.name === "AbortError")
+  );
+}
+
+function isGenericFetchMessage(message: string): boolean {
+  return GENERIC_FETCH_MESSAGES.has(message.toLowerCase());
+}
+
+/**
+ * A dead tunnel surfaces as a generic wrapper ("fetch failed") whose `cause`
+ * carries the reason worth reading (`ECONNREFUSED`, `ENOTFOUND`), so walk the
+ * chain for a code, then for the first message that says something.
+ */
+function describeError(error: unknown): string {
+  let message: string | undefined;
+  let current: unknown = error;
+
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth += 1) {
+    if (!isPlainObject(current)) {
+      break;
+    }
+    if (isTimeoutError(current)) {
+      return "timeout";
+    }
+    const code = trimmedNonEmptyString(current.code);
+    if (code !== undefined) {
+      return code;
+    }
+    // A wrapper only holds the slot until a deeper level fills it.
+    if (message === undefined || isGenericFetchMessage(message)) {
+      message = trimmedNonEmptyString(current.message) ?? message;
+    }
+    current = current.cause;
+  }
+
+  return message ?? String(error);
+}
+
+interface ServedEdgeConfig {
+  assistantId?: string;
+  assistantName?: string;
+}
+
+/**
+ * What the config request settled: the identity the pairing edge reports, a
+ * positive "whatever is here does not serve the pairing app", or nothing.
+ */
+type ServedConfigReading =
+  | { kind: "unanswered" }
+  | { kind: "notServed"; detail: string }
+  | { kind: "served"; config: ServedEdgeConfig };
+
+/**
+ * A 2xx JSON object carrying the pairing edge's marker is that edge
+ * identifying itself, any other answer is an edge that does not serve the
+ * pairing app, and no answer is no evidence.
+ */
+async function readServedConfig(
+  response: Response | undefined,
+): Promise<ServedConfigReading> {
+  if (response === undefined) {
+    return { kind: "unanswered" };
+  }
+  if (!response.ok) {
+    await discardBody(response);
+    return { kind: "notServed", detail: `HTTP ${response.status}` };
+  }
+  let detail = UNREADABLE_CONFIG_DETAIL;
+  try {
+    const body: unknown = await response.json();
+    if (isPlainObject(body)) {
+      if (body.mode === PAIRING_EDGE_MODE) {
+        return {
+          kind: "served",
+          config: {
+            assistantId: trimmedNonEmptyString(body.assistantId),
+            assistantName: trimmedNonEmptyString(body.assistantName),
+          },
+        };
+      }
+      detail = UNMARKED_CONFIG_DETAIL;
+    }
+  } catch {
+    /* an unparseable body is an edge answering with something else */
+  }
+  await discardBody(response);
+  return { kind: "notServed", detail };
+}

package/src/ipc/__tests__/socket-path.test.ts

@@ -1,10 +1,14 @@
 import { createServer } from "node:net";
 import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
 import { ensureSocketPathFree } from "../socket-cleanup.js";
 import { resolveIpcSocketPath } from "../socket-path.js";
 
+// Fake workspace under tmpdir so the live-workspace guard accepts it.
+const WS_DIR = join(tmpdir(), "vellum-workspace-test");
+
 let savedWorkspaceDir: string | undefined;
 let savedGatewayIpcSocketDir: string | undefined;
 
@@ -29,7 +33,7 @@ afterEach(() => {
 describe("resolveIpcSocketPath", () => {
   test("uses env var override when set", () => {
     process.env.GATEWAY_IPC_SOCKET_DIR = "/run/gateway-ipc";
-    process.env.VELLUM_WORKSPACE_DIR = "/tmp/vellum-workspace-test";
+    process.env.VELLUM_WORKSPACE_DIR = WS_DIR;
 
     const resolved = resolveIpcSocketPath("gateway");
 
@@ -39,28 +43,32 @@ describe("resolveIpcSocketPath", () => {
 
   test("ignores empty env var override", () => {
     process.env.GATEWAY_IPC_SOCKET_DIR = "  ";
-    process.env.VELLUM_WORKSPACE_DIR = "/tmp/vellum-workspace-test";
+    process.env.VELLUM_WORKSPACE_DIR = WS_DIR;
 
     const resolved = resolveIpcSocketPath("gateway");
 
     expect(resolved.source).toBe("workspace");
-    expect(resolved.path).toBe("/tmp/vellum-workspace-test/gateway.sock");
+    expect(resolved.path).toBe(join(WS_DIR, "gateway.sock"));
   });
 
   test("uses workspace path by default", () => {
     delete process.env.GATEWAY_IPC_SOCKET_DIR;
-    process.env.VELLUM_WORKSPACE_DIR = "/tmp/vellum-workspace-test";
+    process.env.VELLUM_WORKSPACE_DIR = WS_DIR;
 
     const resolved = resolveIpcSocketPath("gateway");
 
     expect(resolved.source).toBe("workspace");
-    expect(resolved.path).toBe("/tmp/vellum-workspace-test/gateway.sock");
+    expect(resolved.path).toBe(join(WS_DIR, "gateway.sock"));
   });
 
   test("falls back to tmpdir when workspace path exceeds AF_UNIX limit", () => {
     delete process.env.GATEWAY_IPC_SOCKET_DIR;
     // 90-char workspace dir + /gateway.sock = well over 103 bytes
-    process.env.VELLUM_WORKSPACE_DIR = "/tmp/" + "a".repeat(85) + "/workspace";
+    process.env.VELLUM_WORKSPACE_DIR = join(
+      tmpdir(),
+      "a".repeat(90),
+      "workspace",
+    );
 
     const resolved = resolveIpcSocketPath("gateway");
 
@@ -70,7 +78,7 @@ describe("resolveIpcSocketPath", () => {
 
   test("derives a hyphenated socket name's env var and filename", () => {
     process.env.EXAMPLE_SERVICE_IPC_SOCKET_DIR = "/run/example-ipc";
-    process.env.VELLUM_WORKSPACE_DIR = "/tmp/vellum-workspace-test";
+    process.env.VELLUM_WORKSPACE_DIR = WS_DIR;
 
     const resolved = resolveIpcSocketPath("example-service");
 

package/src/ipc/gateway-client.test.ts

@@ -143,7 +143,7 @@ describe("ipcClassifyRisk retry", () => {
   const CLASSIFY_OK = {
     risk: "low",
     reason: "safe",
-    matchType: "none",
+    matchType: "registry",
     scopeOptions: [],
   };
   const emptyParams = {} as unknown as Parameters<typeof ipcClassifyRisk>[0];

package/src/ipc/gateway-client.ts

@@ -10,16 +10,17 @@
  * deterministic fallback for long AF_UNIX paths.
  */
 
+import {
+  type ClassifyRiskIpcParams,
+  type ClassifyRiskIpcResponse,
+  ClassifyRiskIpcResponseSchema,
+} from "@vellumai/gateway-client";
 import {
   ipcCall as packageIpcCall,
   IpcCallError,
   PersistentIpcClient as PackagePersistentIpcClient,
 } from "@vellumai/gateway-client/ipc-client";
 
-import type {
-  ClassificationResult,
-  ClassifyRiskParams,
-} from "../permissions/ipc-risk-types.js";
 import { getLogger } from "../util/logger.js";
 import { abortableSleep, computeRetryDelay } from "../util/retry.js";
 import { resolveIpcSocketPath } from "./socket-path.js";
@@ -173,37 +174,29 @@ const CLASSIFY_RISK_ATTEMPT_TIMEOUT_MS = 1_500; // per-attempt cap (< 5s default
  * When a `signal` is supplied, retries stop as soon as it aborts.
  */
 export async function ipcClassifyRisk(
-  params: ClassifyRiskParams,
+  params: ClassifyRiskIpcParams,
   signal?: AbortSignal,
-): Promise<ClassificationResult | undefined> {
+): Promise<ClassifyRiskIpcResponse | undefined> {
   for (let attempt = 0; ; attempt++) {
     try {
       const result = await ipcCallPersistent(
         "classify_risk",
-        params as unknown as Record<string, unknown>,
+        params,
         CLASSIFY_RISK_ATTEMPT_TIMEOUT_MS,
       );
 
-      // Returned-but-malformed responses are deterministic, not transient:
+      // A returned-but-malformed response is deterministic, not transient:
       // fail closed immediately (no retry).
-      if (!result || typeof result !== "object" || Array.isArray(result)) {
-        log.warn(
-          { result },
-          "ipcClassifyRisk: gateway returned non-object response",
-        );
-        return undefined;
-      }
-
-      const obj = result as Record<string, unknown>;
-      if (typeof obj.risk !== "string") {
+      const parsed = ClassifyRiskIpcResponseSchema.safeParse(result);
+      if (!parsed.success) {
         log.warn(
-          { result },
-          "ipcClassifyRisk: gateway response missing 'risk' field",
+          { result, issues: parsed.error.issues },
+          "ipcClassifyRisk: gateway response does not match the classify_risk contract",
         );
         return undefined;
       }
 
-      return result as ClassificationResult;
+      return parsed.data;
     } catch (err) {
       // A structured gateway error means the gateway was reachable and
       // deterministically rejected the request — not a transient blip.

package/src/ipc/socket-cleanup.ts

@@ -15,6 +15,8 @@ import {
   removeIpcEndpointFile,
 } from "@vellumai/ipc-server-utils";
 
+import { makeAddrInUseError } from "../daemon/startup-error.js";
+
 /**
  * Maximum time to wait for the probe `connect()` to settle before declaring
  * the path occupied. Without a bound, a hung process holding the socket would
@@ -25,17 +27,6 @@ import {
  */
 const PROBE_CONNECT_TIMEOUT_MS = 2000;
 
-/**
- * Build an `EADDRINUSE`-coded error so callers (and `categorizeDaemonError`)
- * can branch on `err.code` and surface the structured "already running"
- * guidance instead of a generic UNKNOWN.
- */
-function makeAddrInUseError(message: string): NodeJS.ErrnoException {
-  const err = new Error(message) as NodeJS.ErrnoException;
-  err.code = "EADDRINUSE";
-  return err;
-}
-
 /**
  * Probe-connect to `socketPath`. Behavior:
  *   - Path doesn't exist → return.

package/src/mcp/__tests__/mcp-auth-orchestrator.test.ts

@@ -67,7 +67,7 @@ mock.module("../../daemon/mcp-reload-service.js", () => ({
 
 mock.module("../../config/env-registry.js", () => ({
   getIsContainerized: () => false,
-  getWorkspaceDirOverride: () => undefined,
+  getWorkspaceDirOverride: () => process.env.VELLUM_WORKSPACE_DIR,
   // Imported by the real util/logger.js; ESM named-import validation
   // requires it even though the silent test logger never calls it.
   getDebugStdoutLogs: () => false,

package/src/messaging/provider-message-metadata.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+
+import { CHANNEL_IDS } from "../channels/types.js";
+
+/**
+ * What a stored channel message row knows about itself, in terms no single
+ * provider owns.
+ *
+ * "Provider" here is the channel sense, the one `messaging/providers/*` uses:
+ * Slack, Telegram, Discord. It is not the inference sense in `providers/*`,
+ * whose `providerMetadata` rides on a content block and describes a model.
+ *
+ * Named for the provider rather than the channel because `channel metadata`
+ * is already taken: `buildChannelMetadata` builds the whole envelope a
+ * message row carries (provenance, `userMessageChannel`, interfaces), and
+ * this is one key inside that envelope. This is the neutral counterpart of
+ * `slackMeta`, so it reads as the generalization of what `providers/slack`
+ * stores.
+ *
+ * Every channel needs the same facts to reconstruct a transcript: which chat
+ * the row belongs to, the provider's id for the row itself, the thread it sits
+ * in, whether it is a message or a reaction, and, when it is a reaction, which
+ * message it was attached to.
+ *
+ * History assembly is structural, not Slack logic: it groups a reaction with
+ * the message it targets, inside a thread. That rule holds for any
+ * thread-scoped channel.
+ *
+ * The schema passes through what it does not name, so a provider carries its
+ * own fields (Slack's file markers and timezone labels) on this same object
+ * and validates them with its own schema. This is how `SourceMetadataSchema`
+ * already carries `slackBotMentioned` and the email fields on the wire: one
+ * object per row, no per-provider sub-envelope, and no second copy of
+ * anything named here.
+ */
+
+const providerReactionMetadataSchema = z.object({
+  /**
+   * Provider id of the message this reaction was attached to, in the same
+   * namespace as `messageId`. Resolution is keyed on it, so it is required.
+   */
+  targetMessageId: z.string(),
+  emoji: z.string(),
+  op: z.enum(["added", "removed"]),
+  actorDisplayName: z.string().optional(),
+});
+
+export const providerMessageMetadataSchema = z
+  .object({
+    source: z.enum(CHANNEL_IDS),
+    /**
+     * Provider id of the chat, channel or room this row belongs to. Same name
+     * and meaning as on the inbound wire, where "conversation" is the canonical
+     * word for a delivery address and "channel" names the provider.
+     */
+    conversationExternalId: z.string(),
+    /**
+     * Provider id of this row itself. Absent on a reaction, which no channel
+     * gives an id of its own: a reaction event names the chat, the message it
+     * was attached to, the actor and the emoji, and nothing identifies the
+     * reaction. The message it acts on is `reaction.targetMessageId`.
+     */
+    messageId: z.string().optional(),
+    /**
+     * Provider id of the thread this row sits in, absent when it is not in one.
+     * Never synthesized from `messageId`: a value here asserts that a thread
+     * exists, and inventing one keys conversations on threads that never do.
+     */
+    threadId: z.string().optional(),
+    /**
+     * Provider id of whoever authored the row or performed the reaction. Trust
+     * is keyed on this everywhere else, and it is what lets a channel say who
+     * acted; a display name is a label, not an identity. Optional because a
+     * provider envelope need not carry one.
+     */
+    actorExternalId: z.string().optional(),
+    displayName: z.string().optional(),
+    /**
+     * Only reactions get a row of their own. An edit rewrites the row it
+     * targets and a delete stamps `deletedAt` on it, so neither appears here.
+     */
+    eventKind: z.enum(["message", "reaction"]),
+    reaction: providerReactionMetadataSchema.optional(),
+    editedAt: z.number().optional(),
+    deletedAt: z.number().optional(),
+  })
+  .passthrough();
+
+export type ProviderReactionMetadata = z.infer<
+  typeof providerReactionMetadataSchema
+>;
+export type ProviderMessageMetadata = z.infer<
+  typeof providerMessageMetadataSchema
+>;
+
+/**
+ * Parse and validate a serialized `ProviderMessageMetadata`, the counterpart of
+ * `readSlackMetadata` for the neutral shape. Anything that does not parse or
+ * does not validate reads as null.
+ */
+export function readProviderMessageMetadata(
+  raw: unknown,
+): ProviderMessageMetadata | null {
+  if (typeof raw !== "string") {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const result = providerMessageMetadataSchema.safeParse(parsed);
+  return result.success ? result.data : null;
+}
+
+/**
+ * The id a row is grouped by when assembling a thread: its own for a message,
+ * its target's for a reaction, so a reaction lands beside the message it was
+ * attached to rather than in a block of its own.
+ *
+ * Undefined for a row that identifies neither, which cannot be placed.
+ */
+export function groupingMessageId(
+  meta: ProviderMessageMetadata,
+): string | undefined {
+  return meta.reaction?.targetMessageId ?? meta.messageId;
+}