@vellumai/assistant 0.11.5 → 0.11.6-staging.1

package/src/runtime/__tests__/desktop-presence.test.ts

@@ -2,7 +2,7 @@
  * Tests for the desktop presence policy.
  *
  * The invariant under test is fail-open: only a fresh `active` report from a
- * `macos` client answers `true`. Every other shape (stale, idle, away, no
+ * desktop client answers `true`. Every other shape (stale, idle, away, no
  * presence, wrong interface, no clients, hub throw) answers `false` so the
  * push is sent. Scoping the read to an actor principal narrows what counts as
  * attendance, so it can only ever turn a `true` into a `false`.
@@ -45,6 +45,15 @@ describe("isDesktopAttended", () => {
     expect(isDesktopAttended()).toBe(true);
   });
 
+  test("fresh active windows client is attended", () => {
+    registerClient({
+      clientId: "windows-1",
+      interfaceId: "windows",
+      presence: "active",
+    });
+    expect(isDesktopAttended()).toBe(true);
+  });
+
   test("active report older than the staleness bound is not attended", () => {
     registerClient({ clientId: "mac-1", presence: "active" });
     expect(isDesktopAttended({ now: afterStaleness() })).toBe(false);
@@ -92,9 +101,13 @@ describe("isDesktopAttended", () => {
     }
   });
 
-  test("one active macos client among several is enough", () => {
+  test("one active desktop client among several is enough", () => {
     registerClient({ clientId: "mac-1", presence: "away" });
-    registerClient({ clientId: "mac-2", presence: "active" });
+    registerClient({
+      clientId: "windows-1",
+      interfaceId: "windows",
+      presence: "active",
+    });
     expect(isDesktopAttended()).toBe(true);
   });
 });
@@ -109,6 +122,16 @@ describe("isDesktopAttended scoped to an actor principal", () => {
     expect(isDesktopAttended({ actorPrincipalId: "actor-a" })).toBe(true);
   });
 
+  test("matching actor principal on windows is attended", () => {
+    registerClient({
+      clientId: "windows-1",
+      interfaceId: "windows",
+      presence: "active",
+      actorPrincipalId: "actor-a",
+    });
+    expect(isDesktopAttended({ actorPrincipalId: "actor-a" })).toBe(true);
+  });
+
   test("another actor's attended mac does not count", () => {
     registerClient({
       clientId: "mac-1",
@@ -123,7 +146,7 @@ describe("isDesktopAttended scoped to an actor principal", () => {
     expect(isDesktopAttended({ actorPrincipalId: "actor-a" })).toBe(false);
   });
 
-  test("omitting the principal counts any attended macos client", () => {
+  test("omitting the principal counts any attended desktop client", () => {
     registerClient({
       clientId: "mac-1",
       presence: "active",

package/src/runtime/__tests__/host-observe.test.ts

@@ -0,0 +1,302 @@
+/**
+ * Tests for `observeHostScreen()`, the conversation-agnostic screen
+ * observation helper.
+ *
+ * Covers:
+ *  1. A posted `host-cu-result` resolves the request with the AX tree, with no
+ *     conversation and no tool call involved.
+ *  2. A request that never resolves times out cleanly and returns a failure.
+ *  3. `executionError` from the client surfaces as a structured failure.
+ *  4. The pending interaction is unregistered on every path.
+ *  5. No capable client connected: failure rather than a throw.
+ *  6. `includeScreenshot: false` drops the screenshot from the result.
+ *  7. Actor binding: another user's client is never selected by default, an
+ *     explicit clientId owned by another user is rejected, a caller with no
+ *     actor principal reaches nothing, and two same-user clients are
+ *     ambiguous rather than fanned out to.
+ */
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Module mocks (must precede the real imports)
+
+interface MockClient {
+  clientId: string;
+  capabilities: string[];
+  actorPrincipalId?: string;
+}
+
+const ACTOR = "principal-a";
+const OTHER_ACTOR = "principal-b";
+
+const sentMessages: Record<string, unknown>[] = [];
+let mockClients: MockClient[] = [];
+
+mock.module("../assistant-event-hub.js", () => ({
+  broadcastMessage: (msg: Record<string, unknown>) => {
+    sentMessages.push(msg);
+  },
+  assistantEventHub: {
+    getMostRecentClientByCapability: (cap: string) =>
+      mockClients.find((c) => c.capabilities.includes(cap)),
+    listClientsByCapability: (cap: string) =>
+      mockClients.filter((c) => c.capabilities.includes(cap)),
+    getClientById: (id: string) => mockClients.find((c) => c.clientId === id),
+    getActorPrincipalIdForClient: (id: string) =>
+      mockClients.find((c) => c.clientId === id)?.actorPrincipalId,
+  },
+}));
+
+// Real imports (after mocks)
+
+const pendingInteractions = await import("../pending-interactions.js");
+const { observeHostScreen } = await import("../host-observe.js");
+const { ROUTES } = await import("../routes/host-cu-routes.js");
+
+const hostCuResultRoute = ROUTES.find(
+  (r) => r.operationId === "host_cu_result",
+);
+
+/**
+ * Deliver a client observation through the real `/v1/host-cu-result` route,
+ * with the identity headers the targeted client sends.
+ */
+async function postResult(
+  body: Record<string, unknown>,
+  headers: Record<string, string> = {
+    "x-vellum-client-id": "mac-1",
+    "x-vellum-actor-principal-id": ACTOR,
+  },
+): Promise<void> {
+  await hostCuResultRoute?.handler({ body, headers });
+}
+
+/** The requestId of the single `host_cu_request` broadcast so far. */
+function sentRequestId(): string {
+  const request = sentMessages.find((m) => m.type === "host_cu_request");
+  expect(request).toBeDefined();
+  return request?.requestId as string;
+}
+
+/** Observe as the actor that owns `mac-1` in the default fixture. */
+function observe(
+  options: Partial<Parameters<typeof observeHostScreen>[0]> = {},
+) {
+  return observeHostScreen({ sourceActorPrincipalId: ACTOR, ...options });
+}
+
+describe("observeHostScreen", () => {
+  beforeEach(() => {
+    sentMessages.length = 0;
+    mockClients = [
+      {
+        clientId: "mac-1",
+        capabilities: ["host_cu"],
+        actorPrincipalId: ACTOR,
+      },
+    ];
+    pendingInteractions.clear();
+  });
+
+  afterEach(() => {
+    pendingInteractions.clear();
+  });
+
+  test("resolves with the AX tree from a posted client result", async () => {
+    const observation = observe();
+
+    const request = sentMessages.find((m) => m.type === "host_cu_request");
+    expect(request?.toolName).toBe("computer_use_observe");
+    expect(request?.input).toEqual({});
+    expect(request?.conversationId).toBe("");
+
+    const requestId = sentRequestId();
+    expect(pendingInteractions.get(requestId)?.kind).toBe("host_cu");
+    expect(pendingInteractions.get(requestId)?.targetClientId).toBe("mac-1");
+
+    await postResult({
+      requestId,
+      axTree: "Window [1]\nButton [2]",
+      screenshot: "base64png",
+      screenWidthPt: 1440,
+      screenHeightPt: 900,
+    });
+
+    expect(await observation).toEqual({
+      ok: true,
+      axTree: "Window [1]\nButton [2]",
+      screenshot: "base64png",
+      screenWidthPt: 1440,
+      screenHeightPt: 900,
+    });
+    expect(pendingInteractions.getAll()).toHaveLength(0);
+  });
+
+  test("times out cleanly and unregisters the pending interaction", async () => {
+    const result = await observe({ timeoutMs: 20 });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.timedOut).toBe(true);
+      expect(result.reason).toContain("Timed out after 20ms");
+    }
+    expect(pendingInteractions.getAll()).toHaveLength(0);
+    expect(sentMessages.some((m) => m.type === "host_cu_cancel")).toBe(true);
+  });
+
+  test("tolerates a late result posted after the timeout", async () => {
+    const result = await observe({ timeoutMs: 20 });
+    expect(result.ok).toBe(false);
+
+    // The route 404s on an unknown requestId; a late post must not throw past
+    // that, and must not resurrect the already-settled request.
+    await expect(postResult({ requestId: sentRequestId() })).rejects.toThrow();
+    expect(pendingInteractions.getAll()).toHaveLength(0);
+  });
+
+  test("surfaces executionError as a structured failure", async () => {
+    const observation = observe();
+    await postResult({
+      requestId: sentRequestId(),
+      executionError: "Accessibility permission not granted",
+      axTree: "Window [1]",
+    });
+
+    const result = await observation;
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe("Accessibility permission not granted");
+      expect(result.timedOut).toBeUndefined();
+    }
+    expect(pendingInteractions.getAll()).toHaveLength(0);
+  });
+
+  test("fails without throwing when no capable client is connected", async () => {
+    mockClients = [];
+
+    const result = await observe();
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toContain("No connected client");
+    }
+    expect(sentMessages).toHaveLength(0);
+    expect(pendingInteractions.getAll()).toHaveLength(0);
+  });
+
+  test("drops the screenshot when includeScreenshot is false", async () => {
+    const observation = observe({ includeScreenshot: false });
+    await postResult({
+      requestId: sentRequestId(),
+      axTree: "Window [1]",
+      screenshot: "base64png",
+      screenshotWidthPx: 2880,
+      screenshotHeightPx: 1800,
+    });
+
+    expect(await observation).toEqual({ ok: true, axTree: "Window [1]" });
+  });
+
+  describe("actor binding", () => {
+    test("never selects another actor's client by default", async () => {
+      mockClients = [
+        {
+          clientId: "mac-2",
+          capabilities: ["host_cu"],
+          actorPrincipalId: OTHER_ACTOR,
+        },
+      ];
+
+      const result = await observe();
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.reason).toContain("No connected client");
+      }
+      expect(sentMessages).toHaveLength(0);
+      expect(pendingInteractions.getAll()).toHaveLength(0);
+    });
+
+    test("rejects an explicit clientId owned by another actor", async () => {
+      mockClients.push({
+        clientId: "mac-2",
+        capabilities: ["host_cu"],
+        actorPrincipalId: OTHER_ACTOR,
+      });
+
+      const result = await observe({ clientId: "mac-2" });
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.reason).toContain("different user");
+      }
+      expect(sentMessages).toHaveLength(0);
+      expect(pendingInteractions.getAll()).toHaveLength(0);
+    });
+
+    test("rejects a caller with no actor principal", async () => {
+      const result = await observeHostScreen({
+        sourceActorPrincipalId: undefined,
+        clientId: "mac-1",
+      });
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.reason).toContain("no authenticated actor");
+      }
+      expect(sentMessages).toHaveLength(0);
+    });
+
+    test("rejects a client that registered without an actor principal", async () => {
+      mockClients = [{ clientId: "mac-1", capabilities: ["host_cu"] }];
+
+      const result = await observe({ clientId: "mac-1" });
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.reason).toContain("without an authenticated user");
+      }
+      expect(sentMessages).toHaveLength(0);
+    });
+
+    test("refuses to fan out across two clients owned by the actor", async () => {
+      mockClients.push({
+        clientId: "mac-3",
+        capabilities: ["host_cu"],
+        actorPrincipalId: ACTOR,
+      });
+
+      const result = await observe();
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.reason).toContain("Specify target_client_id");
+      }
+      expect(sentMessages).toHaveLength(0);
+    });
+
+    test("succeeds on the same-actor path with an explicit clientId", async () => {
+      mockClients.push({
+        clientId: "mac-2",
+        capabilities: ["host_cu"],
+        actorPrincipalId: OTHER_ACTOR,
+      });
+
+      const observation = observe({ clientId: "mac-1" });
+      await postResult({ requestId: sentRequestId(), axTree: "Window [1]" });
+
+      expect(await observation).toEqual({ ok: true, axTree: "Window [1]" });
+    });
+
+    test("rejects a result submitted by another actor's client", async () => {
+      const observation = observe({ timeoutMs: 200 });
+      const requestId = sentRequestId();
+
+      await expect(
+        postResult(
+          { requestId, axTree: "Window [1]" },
+          {
+            "x-vellum-client-id": "mac-1",
+            "x-vellum-actor-principal-id": OTHER_ACTOR,
+          },
+        ),
+      ).rejects.toThrow();
+
+      const result = await observation;
+      expect(result.ok).toBe(false);
+    });
+  });
+});

package/src/runtime/channel-readiness-service.ts

@@ -3,12 +3,14 @@ import { z } from "zod";
 
 import { resolveTwilioPhoneNumber } from "../calls/twilio-config.js";
 import { hasTwilioCredentials } from "../calls/twilio-rest.js";
+import { CHANNEL_METADATA } from "../channels/types.js";
 import { getNestedValue, loadRawConfig } from "../config/loader.js";
 import { hasWebhookRoutingConfigured } from "../config/webhook-routing.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { resolveWhatsAppDisplayNumber } from "./channel-invite-transports/whatsapp.js";
 import type {
+  ChannelHealth,
   ChannelId,
   ChannelProbe,
   ChannelProbeContext,
@@ -247,12 +249,19 @@ const telegramProbe: ChannelProbe = {
       health.status === "unknown" ||
       health.status === "unverified";
     const result = check(
+      // Published identifier. Installed skill copies and external clients
+      // search readiness responses for this name, and they do not upgrade in
+      // lockstep with the daemon, so renaming it silently breaks their
+      // delivery gate while Telegram is healthy.
       "webhook_delivery",
       health.status === "healthy" || indeterminate,
       "Telegram is delivering to this assistant",
       health.detail,
     );
-    return [indeterminate ? { ...result, indeterminate: true } : result];
+    const operational = { ...result, kind: "operational" as const };
+    return [
+      indeterminate ? { ...operational, indeterminate: true } : operational,
+    ];
   },
 };
 
@@ -354,6 +363,96 @@ const whatsappProbe: ChannelProbe = {
 
 // ── Slack Probe ─────────────────────────────────────────────────────────────
 
+/**
+ * Ask the gateway whether a socket-backed channel's connection is receiving.
+ *
+ * One function for every such channel, matching the IPC route it reads, which
+ * is keyed by channel for the same reason: the question and the answer are the
+ * same wherever a socket carries inbound. A channel whose ingress is not a
+ * gateway-owned socket answers `unsupported`, which reads as indeterminate
+ * rather than a fault, so asking is always safe.
+ *
+ * Distinct from the credential checks: valid tokens establish that the
+ * provider would accept us, not that anything is arriving. A socket can be
+ * open at the transport layer and deliver nothing.
+ *
+ * Three outcomes, matching the Telegram probe:
+ *
+ *   - `connected` is the only verified pass.
+ *   - `disconnected` is a failure with a concrete cause.
+ *   - `not_configured`, `unsupported` and an unreachable gateway are
+ *     indeterminate. None is evidence of a fault, so none may show the channel
+ *     as broken; none is evidence of delivery either, so none may make it
+ *     ready.
+ *
+ * `lastLivenessAt` is reported and never gated on: a connection's first
+ * keepalive is a full interval after it opens, so requiring one would call
+ * every healthy reconnect broken.
+ *
+ * Declared `operational`, so it decides the channel's health rather than its
+ * setup progress: a dead socket means a configured channel is down, not a
+ * half-configured one.
+ *
+ * It runs among the local checks purely for freshness. It costs one IPC round
+ * trip to the gateway beside us rather than a call to Slack, and the remote
+ * bucket is cached for {@link REMOTE_TTL_MS}, far longer than a socket takes
+ * to die and recover. Placement is a cost decision here; `kind` carries the
+ * meaning.
+ */
+async function checkSocketInboundDelivery(
+  channel: ChannelId,
+): Promise<ReadinessCheckResult> {
+  // The channel's own display name, so a socket-backed channel added later
+  // needs no string decision here. Falls back to the id for a channel with no
+  // metadata entry, which is every channel clients are not offered.
+  const label = CHANNEL_METADATA[channel]?.label ?? channel;
+  // Imported here rather than at module scope, matching the Telegram probe:
+  // the gateway IPC client pulls in a module graph that unrelated consumers of
+  // this service should not have to mock.
+  const { readChannelSocketHealth } =
+    await import("../channels/gateway-channel-socket-health.js");
+
+  let health;
+  try {
+    health = await readChannelSocketHealth(channel);
+  } catch {
+    return {
+      name: "inbound_delivery",
+      kind: "operational",
+      passed: true,
+      message: `Could not reach the gateway to read the ${label} connection state`,
+      indeterminate: true,
+    };
+  }
+
+  if (health.status === "not_configured" || health.status === "unsupported") {
+    return {
+      name: "inbound_delivery",
+      kind: "operational",
+      passed: true,
+      message:
+        health.status === "not_configured"
+          ? `${label} is not connected, because its credentials are not configured`
+          : `${label} does not report a gateway-owned socket`,
+      indeterminate: true,
+    };
+  }
+
+  const lastProof =
+    health.lastLivenessAt === undefined
+      ? "no keepalive answered yet on this connection"
+      : `last keepalive ${new Date(health.lastLivenessAt).toISOString()}`;
+  return {
+    ...check(
+      "inbound_delivery",
+      health.status === "connected",
+      `${label} is delivering to this assistant (${lastProof})`,
+      `${label} holds no live connection, so inbound messages are not reaching this assistant`,
+    ),
+    kind: "operational",
+  };
+}
+
 const slackProbe: ChannelProbe = {
   channel: "slack",
   async runLocalChecks(): Promise<ReadinessCheckResult[]> {
@@ -370,6 +469,7 @@ const slackProbe: ChannelProbe = {
         "app_token",
         "Slack app token",
       ),
+      await checkSocketInboundDelivery("slack"),
     ];
   },
   async runRemoteChecks(): Promise<ReadinessCheckResult[]> {
@@ -448,6 +548,77 @@ const slackProbe: ChannelProbe = {
   },
 };
 
+/**
+ * Whether Discord admits anything in the guilds it has joined.
+ *
+ * A configuration check rather than an operational one, and the distinction
+ * carries the meaning. An empty allow-list is a setup step nobody finished,
+ * not a channel that broke: direct messages reach the assistant either way,
+ * because a message with no guild never meets this gate. Reporting it as
+ * failing health would send an operator to look for an outage that is not
+ * there, and reporting it as ready would claim delivery while every guild
+ * message is dropped.
+ *
+ * An unreachable gateway is indeterminate, matching the socket check beside
+ * it: nobody looked, so nothing is claimed either way.
+ */
+async function checkDiscordGuildAdmission(): Promise<ReadinessCheckResult> {
+  const { readDiscordAdmission } =
+    await import("../channels/gateway-discord-admission.js");
+
+  let admitted;
+  try {
+    admitted = (await readDiscordAdmission()).admittedChannelCount;
+  } catch {
+    return {
+      name: "guild_admission",
+      passed: true,
+      message: "Could not reach the gateway to read Discord's allow-list",
+      indeterminate: true,
+    };
+  }
+
+  return check(
+    "guild_admission",
+    admitted > 0,
+    `Discord may act in ${admitted} channel${admitted === 1 ? "" : "s"}`,
+    "Discord is in no channel's allow-list, so every guild message is dropped. Add channel ids to `discord.allowedChannelIds`",
+  );
+}
+
+// ── Discord Probe ───────────────────────────────────────────────────────────
+
+/**
+ * Discord readiness.
+ *
+ * One credential and one socket, which is the whole of it. Discord holds a
+ * Gateway connection rather than receiving webhooks, so there is no ingress
+ * routing to check: nothing has to reach this deployment from outside for
+ * inbound to work.
+ *
+ * No remote check either, and that is a decision rather than an omission. The
+ * remote bucket exists to ask a provider whether it would accept us, which for
+ * Slack is worth asking separately because its socket authenticates with a
+ * different token than its sends. Discord uses one bot token for both, so a
+ * live Gateway connection already proves the token the sends will use, and a
+ * call to `GET /users/@me` would restate it a cache interval later.
+ */
+const discordProbe: ChannelProbe = {
+  channel: "discord",
+  async runLocalChecks(): Promise<ReadinessCheckResult[]> {
+    return [
+      await checkCredential(
+        "bot_token",
+        "discord_channel",
+        "bot_token",
+        "Discord bot token",
+      ),
+      await checkSocketInboundDelivery("discord"),
+      await checkDiscordGuildAdmission(),
+    ];
+  },
+};
+
 // ── Service ─────────────────────────────────────────────────────────────────
 
 export class ChannelReadinessService {
@@ -519,14 +690,7 @@ export class ChannelReadinessService {
       // itself live on the strength of a check that never ran.
       const verified = (c: ReadinessCheckResult): boolean =>
         c.passed && !c.indeterminate;
-      const allLocalPassed = localChecks.every(verified);
-      const allRemotePassed =
-        remoteChecks && remoteChecksAffectReadiness
-          ? remoteChecks.every(verified)
-          : true;
-      const ready = allLocalPassed && allRemotePassed;
-
-      // setupStatus: considers all checks (credentials + infrastructure)
+
       const consideredChecks = [
         ...localChecks,
         ...(remoteChecks && remoteChecksAffectReadiness ? remoteChecks : []),
@@ -537,13 +701,38 @@ export class ChannelReadinessService {
       // progress reports an untouched workspace as `incomplete`, which is what
       // sends the Channels UI down the "finish setup" path instead of the
       // normal setup flow.
-      const anyCheckPassed = consideredChecks.some(verified);
-      const setupStatus: SetupStatus = !anyCheckPassed
+      // Two axes, not one ladder. Setup progress derives from configuration
+      // checks and health from operational ones, because "is this configured"
+      // and "is it working" have different answers and different remedies. A
+      // fully configured channel whose delivery is failing is not half set
+      // up, and reporting it as incomplete sends its owner to fix the one
+      // thing that is not broken.
+      const configurationChecks = consideredChecks.filter(
+        (c) => (c.kind ?? "configuration") === "configuration",
+      );
+      const operationalChecks = consideredChecks.filter(
+        (c) => c.kind === "operational",
+      );
+
+      const setupStatus: SetupStatus = !configurationChecks.some(verified)
         ? "not_configured"
-        : ready
+        : configurationChecks.every(verified)
           ? "ready"
           : "incomplete";
 
+      // Absent, not "unknown", when the channel asks no operational question.
+      // Nothing was measured, so nothing is claimed, and readiness rests on
+      // configuration alone. Collapsing that into `unknown` would report every
+      // channel without a delivery check as unverifiable.
+      const health: ChannelHealth | undefined =
+        operationalChecks.length === 0
+          ? undefined
+          : operationalChecks.some((c) => !c.passed)
+            ? "failing"
+            : operationalChecks.every(verified)
+              ? "ok"
+              : "unknown";
+
       const reasons: Array<{ code: string; text: string }> = [];
       for (const check of localChecks) {
         if (!check.passed) {
@@ -560,8 +749,12 @@ export class ChannelReadinessService {
 
       const snapshot: ChannelReadinessSnapshot = {
         channel: ch,
-        ready,
+        ready:
+          setupStatus === "ready" &&
+          health !== "failing" &&
+          health !== "unknown",
         setupStatus,
+        health,
         checkedAt:
           remoteChecks && cached && !remoteChecksFreshlyFetched
             ? cached.checkedAt
@@ -618,7 +811,13 @@ export class ChannelReadinessService {
 
 // ── Factory ─────────────────────────────────────────────────────────────────
 
-/** Create a service instance with built-in Voice, Telegram, Email, WhatsApp, and Slack probes registered. */
+/**
+ * A service with every built-in probe registered.
+ *
+ * The registrations below are the list; naming them here as well gives the set
+ * a second home that drifts the moment a channel is added, which is what it
+ * did.
+ */
 export function createReadinessService(): ChannelReadinessService {
   const service = new ChannelReadinessService();
   service.registerProbe(voiceProbe);
@@ -626,5 +825,6 @@ export function createReadinessService(): ChannelReadinessService {
   service.registerProbe(emailProbe);
   service.registerProbe(whatsappProbe);
   service.registerProbe(slackProbe);
+  service.registerProbe(discordProbe);
   return service;
 }