@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/__tests__/mode-session-wire.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, test } from "bun:test";
+
+import { AssistantTextDeltaEventSchema } from "../api/events/assistant-text-delta.js";
+import { AssistantThinkingDeltaEventSchema } from "../api/events/assistant-thinking-delta.js";
+import { AssistantTurnStartEventSchema } from "../api/events/assistant-turn-start.js";
+import { GenerationHandoffEventSchema } from "../api/events/generation-handoff.js";
+import { MessageCompleteEventSchema } from "../api/events/message-complete.js";
+import { ToolResultEventSchema } from "../api/events/tool-result.js";
+import { ToolUseStartEventSchema } from "../api/events/tool-use-start.js";
+import { UserMessageEchoEventSchema } from "../api/events/user-message-echo.js";
+import {
+  ModeSessionDescriptorSchema,
+  ModeSessionSchema,
+} from "../api/mode-session.js";
+import { ConversationMessageSchema } from "../api/responses/conversation-message.js";
+import { messageMetadataSchema } from "../persistence/conversation-crud.js";
+
+const owner = { mode: "browser", id: "session-123" } as const;
+
+describe("mode session wire contract", () => {
+  test("accepts canonical membership on history and row-boundary events", () => {
+    expect(ModeSessionSchema.parse(owner)).toEqual(owner);
+    expect(
+      ConversationMessageSchema.parse({
+        id: "message-123",
+        role: "assistant",
+        timestamp: new Date(0).toISOString(),
+        attachments: [],
+        contentBlocks: [],
+        modeSession: owner,
+        modeSessionActivity: { firstAt: 100, lastAt: 150 },
+      }).modeSession,
+    ).toEqual(owner);
+
+    const boundaryEvents = [
+      UserMessageEchoEventSchema.parse({
+        type: "user_message_echo",
+        text: "Continue",
+        modeSession: owner,
+      }),
+      AssistantTurnStartEventSchema.parse({
+        type: "assistant_turn_start",
+        messageId: "message-123",
+        modeSession: owner,
+      }),
+      ToolUseStartEventSchema.parse({
+        type: "tool_use_start",
+        toolName: "browser_navigate",
+        input: {},
+        modeSession: owner,
+      }),
+      ToolResultEventSchema.parse({
+        type: "tool_result",
+        toolName: "browser_navigate",
+        result: "Complete",
+        modeSession: owner,
+      }),
+      MessageCompleteEventSchema.parse({
+        type: "message_complete",
+        modeSession: owner,
+      }),
+      GenerationHandoffEventSchema.parse({
+        type: "generation_handoff",
+        queuedCount: 1,
+        modeSession: owner,
+      }),
+    ];
+    expect(
+      boundaryEvents.every((event) => event.modeSession?.id === owner.id),
+    ).toBe(true);
+  });
+
+  test("keeps text and thinking deltas free of session fields", () => {
+    expect(
+      AssistantTextDeltaEventSchema.parse({
+        type: "assistant_text_delta",
+        text: "Working",
+        modeSession: owner,
+      }),
+    ).not.toHaveProperty("modeSession");
+    expect(
+      AssistantThinkingDeltaEventSchema.parse({
+        type: "assistant_thinking_delta",
+        thinking: "Checking",
+        modeSession: owner,
+      }),
+    ).not.toHaveProperty("modeSession");
+  });
+
+  test("exposes runtime state only for active summaries", () => {
+    const summary = {
+      id: "session-123",
+      conversationId: "conv-123",
+      mode: "browser",
+      status: "active",
+      sourceStartedAt: 100,
+      firstIncludedAt: null,
+      firstIncludedMessageId: null,
+      lastActivityAt: 100,
+      lastOwnedMessageId: null,
+      endedAt: null,
+      endReason: null,
+      revision: 1,
+    } as const;
+    expect(
+      ModeSessionDescriptorSchema.parse({
+        summary,
+        runtimeState: "waiting",
+      }).runtimeState,
+    ).toBe("waiting");
+    expect(
+      ModeSessionDescriptorSchema.safeParse({
+        summary: {
+          ...summary,
+          status: "completed",
+          endedAt: 120,
+          endReason: "settled",
+        },
+        runtimeState: "finishing",
+      }).success,
+    ).toBe(false);
+  });
+
+  test("types canonical metadata while preserving unrelated keys", () => {
+    expect(
+      messageMetadataSchema.parse({
+        modeSession: owner,
+        futureMetadata: { value: true },
+      }),
+    ).toEqual({
+      modeSession: owner,
+      futureMetadata: { value: true },
+    });
+    expect(
+      messageMetadataSchema.parse({
+        modeSession: { mode: "unknown", id: "session-123" },
+        futureMetadata: { value: true },
+      }),
+    ).toEqual({ futureMetadata: { value: true } });
+  });
+});

package/src/__tests__/notification-guardian-path.test.ts

@@ -160,6 +160,7 @@ describe("ASK_GUARDIAN notification path", () => {
     ensureConversation(convId);
 
     const session = createCallSession({
+      direction: "inbound",
       conversationId: convId,
       provider: "twilio",
       fromNumber: "+15550001111",
@@ -220,6 +221,7 @@ describe("ASK_GUARDIAN notification path", () => {
     };
 
     const session = createCallSession({
+      direction: "inbound",
       conversationId: convId,
       provider: "twilio",
       fromNumber: "+15550001111",
@@ -263,6 +265,7 @@ describe("ASK_GUARDIAN notification path", () => {
     };
 
     const session = createCallSession({
+      direction: "inbound",
       conversationId: convId,
       provider: "twilio",
       fromNumber: "+15550001111",
@@ -308,6 +311,7 @@ describe("ASK_GUARDIAN notification path", () => {
     };
 
     const session = createCallSession({
+      direction: "inbound",
       conversationId: convId,
       provider: "twilio",
       fromNumber: "+15550001111",
@@ -338,6 +342,7 @@ describe("ASK_GUARDIAN notification path", () => {
     ensureConversation(convId);
 
     const session = createCallSession({
+      direction: "inbound",
       conversationId: convId,
       provider: "twilio",
       fromNumber: "+15550001111",
@@ -370,6 +375,7 @@ describe("ASK_GUARDIAN notification path", () => {
     const sharedConvId = "conv-guardian-shared-thread";
 
     const session = createCallSession({
+      direction: "inbound",
       conversationId: convId,
       provider: "twilio",
       fromNumber: "+15550001111",
@@ -463,6 +469,7 @@ describe("ASK_GUARDIAN notification path", () => {
     };
 
     const session = createCallSession({
+      direction: "inbound",
       conversationId: convId,
       provider: "twilio",
       fromNumber: "+15550001111",

package/src/__tests__/notification-telegram-adapter.test.ts

@@ -183,7 +183,7 @@ describe("TelegramAdapter", () => {
 
     await adapter.send(
       makePayload({
-        sourceEventName: "watcher.escalation",
+        sourceEventName: "watcher.notification",
         copy: {
           title: " ",
           body: "",
@@ -191,7 +191,7 @@ describe("TelegramAdapter", () => {
       }),
       makeDestination(),
     );
-    expect(sendCalls[2]?.text).toBe("watcher escalation");
+    expect(sendCalls[2]?.text).toBe("watcher notification");
   });
 
   // ── Access request inline keyboard tests ──────────────────────────────

package/src/__tests__/notification-vellum-adapter.test.ts

@@ -35,6 +35,7 @@ import type {
   ChannelDeliveryPayload,
   ChannelDestination,
 } from "../notifications/types.js";
+import type { BroadcastMessageOptions } from "../runtime/assistant-event-hub.js";
 
 function makePayload(
   overrides?: Partial<ChannelDeliveryPayload>,
@@ -362,3 +363,36 @@ describe("VellumAdapter update", () => {
     expect(result.error).toBe("DB write failed");
   });
 });
+
+describe("VellumAdapter guardian scoping", () => {
+  function captureOptions(): {
+    adapter: VellumAdapter;
+    options: Array<BroadcastMessageOptions | undefined>;
+  } {
+    const options: Array<BroadcastMessageOptions | undefined> = [];
+    const adapter = new VellumAdapter((_msg, _conversationId, opts) => {
+      options.push(opts);
+    });
+    return { adapter, options };
+  }
+
+  test("a guardian-sensitive intent is delivered only to the guardian's connections", async () => {
+    const { adapter, options } = captureOptions();
+    await adapter.send(
+      makePayload({ sourceEventName: "guardian.question", urgency: "high" }),
+      makeDestination({ metadata: { guardianPrincipalId: "principal-g" } }),
+    );
+
+    expect(options).toEqual([{ targetActorPrincipalId: "principal-g" }]);
+  });
+
+  test("an ordinary intent is broadcast to every connection", async () => {
+    const { adapter, options } = captureOptions();
+    await adapter.send(
+      makePayload({ sourceEventName: "schedule.notify" }),
+      makeDestination({ metadata: { guardianPrincipalId: "principal-g" } }),
+    );
+
+    expect(options).toEqual([{ targetActorPrincipalId: undefined }]);
+  });
+});

package/src/__tests__/oauth-apps-routes.test.ts

@@ -75,6 +75,7 @@ mock.module("../oauth/oauth-store.js", () => ({
           identityBody: null,
           identityFormat: null,
           identityOkField: null,
+          responseOkField: null,
           featureFlag: null,
           createdAt: 1735689500000,
           updatedAt: 1735689550000,

package/src/__tests__/oauth-commands-routes.test.ts

@@ -32,6 +32,7 @@ interface MockProviderRow {
   pingMethod: string | null;
   pingHeaders: string | null;
   pingBody: string | null;
+  responseOkField: string | null;
 }
 
 const baseProvider: MockProviderRow = {
@@ -44,6 +45,7 @@ const baseProvider: MockProviderRow = {
   pingMethod: null,
   pingHeaders: null,
   pingBody: null,
+  responseOkField: null,
 };
 
 let mockProviders: Record<string, MockProviderRow> = {};
@@ -586,6 +588,37 @@ describe("POST oauth/ping", () => {
     expect(result.status).toBe(401);
     expect(result.hint).toContain("oauth connect");
   });
+
+  // Slack's auth.test refuses a revoked token inside an HTTP 200, so a ping
+  // that read only the status would report a dead bot credential as healthy.
+  test("a 2xx ping whose body reports failure in the declared ok field is not ok", async () => {
+    const seed = PROVIDER_SEED_DATA.slack_channel;
+    mockProviders.slack_channel = {
+      ...baseProvider,
+      provider: "slack_channel",
+      pingUrl: seed.pingUrl ?? null,
+      responseOkField: seed.responseOkField ?? null,
+    };
+    mockResolveResponse = {
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: { ok: false, error: "invalid_auth" },
+    };
+    const result = (await getRoute("POST", "oauth/ping").handler(
+      makeArgs({ body: { provider: "slack_channel" } }),
+    )) as {
+      ok: boolean;
+      status: number;
+      error: string;
+      body?: unknown;
+      hint?: string;
+    };
+    expect(result.ok).toBe(false);
+    expect(result.status).toBe(200);
+    expect(result.error).toContain("ok: false");
+    expect(result.body).toEqual({ ok: false, error: "invalid_auth" });
+    expect(result.hint).toContain("oauth connect");
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -665,51 +698,47 @@ describe("POST oauth/request", () => {
     expect(result.body).toEqual({ hello: "world" });
   });
 
-  // The recovery hint on a 401/403 follows the credential's kind. A channel
-  // bot's token is stored by the channel's setup, so the OAuth status and
-  // connect commands cannot repair it; the hint must name the channel's own
-  // diagnostics, through whichever door the request came.
-  test("401 as a channel bot points at the channel's diagnostics, never the OAuth commands", async () => {
-    mockProviders.slack_channel = {
-      ...baseProvider,
-      provider: "slack_channel",
-      authorizeUrl: "urn:manual-token",
-      managedServiceConfigKey: null,
-      baseUrl: "https://slack.com/api",
-    };
+  // The hint's wording is pinned in oauth-request-hints.test.ts. Here only
+  // the facts the route hands the composer are proved to arrive: the
+  // response headers, the base the request resolved against, and the bot
+  // channel resolved from the provider key.
+  test("hands the composer the response, the resolved base, and the identity", async () => {
+    mockProviders.slack_channel = seededProvider("slack_channel");
     mockResolveResponse = {
-      status: 401,
-      headers: { "content-type": "application/json" },
-      body: { ok: false, error: "invalid_auth" },
+      status: 403,
+      headers: { "content-type": "text/html; charset=utf-8" },
+      body: "<html><title>Slack</title></html>",
     };
-    const result = (await getRoute("POST", "oauth/request").handler(
+    const asBot = (await getRoute("POST", "oauth/request").handler(
       makeArgs({
-        body: { provider: "slack_channel", url: "/conversations.history" },
+        body: {
+          provider: "slack_channel",
+          url: "https://files.slack.com/files-pri/T0123-F0456/download/shot.png",
+        },
       }),
     )) as { ok: boolean; status: number; hint?: string };
-    expect(result.ok).toBe(false);
-    expect(result.status).toBe(401);
-    expect(result.hint).toContain("slack bot credential");
-    expect(result.hint).toContain("assistant channels get slack");
-    expect(result.hint).not.toContain("oauth status");
-    expect(result.hint).not.toContain("oauth connect");
-  });
+    expect(asBot.ok).toBe(false);
+    expect(asBot.status).toBe(403);
+    // An absolute URL's own origin is the resolved base.
+    expect(asBot.hint).toContain("from files.slack.com");
+    expect(asBot.hint).toContain("assistant channels get slack");
 
-  test("403 as a person's OAuth integration keeps the OAuth recovery steps", async () => {
+    // A relative path resolves against the provider's base.
     mockResolveResponse = {
-      status: 403,
-      headers: { "content-type": "application/json" },
-      body: { error: "forbidden" },
+      status: 404,
+      headers: { "content-type": "text/html; charset=UTF-8" },
+      body: "<html><title>Error 404 (Not Found)</title></html>",
     };
-    const result = (await getRoute("POST", "oauth/request").handler(
+    const relative = (await getRoute("POST", "oauth/request").handler(
       makeArgs({
-        body: { provider: "google", url: "https://api.google.com/v1/me" },
+        body: {
+          provider: "google",
+          url: "/calendar/v3/calendars/primary/events",
+        },
       }),
-    )) as { ok: boolean; status: number; hint?: string };
-    expect(result.status).toBe(403);
-    expect(result.hint).toContain("assistant oauth status google");
-    expect(result.hint).toContain("oauth connect");
-    expect(result.hint).not.toContain("channels get");
+    )) as { ok: boolean; hint?: string };
+    expect(relative.ok).toBe(false);
+    expect(relative.hint).toContain('base URL "https://api.google.com"');
   });
 
   test("passes a pre-parsed string body through to the connection unchanged", async () => {
@@ -917,6 +946,7 @@ describe("POST oauth/request", () => {
       managedServiceConfigKey: null,
       baseUrl: seed.baseUrl ?? null,
       injectionTemplates: JSON.stringify(seed.injectionTemplates),
+      responseOkField: seed.responseOkField ?? null,
     };
   }
 
@@ -1050,97 +1080,80 @@ describe("POST oauth/request", () => {
     ]);
   });
 
-  test("attaches reconnect hint on 401 response", async () => {
-    mockResolveResponse = { status: 401, headers: {}, body: { error: "no" } };
-    const result = (await getRoute("POST", "oauth/request").handler(
-      makeArgs({
-        body: { provider: "google", url: "https://api.google.com/v1/me" },
-      }),
-    )) as { ok: boolean; hint?: string };
-    expect(result.ok).toBe(false);
-    expect(result.hint).toContain("oauth status");
+  test("rejects unregistered client_id in BYO mode", async () => {
+    // No entry in mockApps for google:client-x
+    await expect(
+      getRoute("POST", "oauth/request").handler(
+        makeArgs({
+          body: {
+            provider: "google",
+            url: "https://api.google.com/v1/me",
+            client_id: "client-x",
+          },
+        }),
+      ),
+    ).rejects.toBeInstanceOf(NotFoundError);
   });
 
-  test("attaches wrong-host/path hint on HTML 404 for a relative path", async () => {
+  // Slack documents that every Web API response carries a top-level boolean
+  // `ok`, false on failure, under a successful status. The provider row
+  // declares that field, and the door reads it, so a refused call is not
+  // reported as a success to the caller.
+  test("a 2xx whose body reports failure in the provider's declared ok field is not ok", async () => {
+    mockProviders.slack_channel = seededProvider("slack_channel");
     mockResolveResponse = {
-      status: 404,
-      headers: { "content-type": "text/html; charset=UTF-8" },
-      body: "<html><title>Error 404 (Not Found)</title></html>",
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: { ok: false, error: "not_in_channel" },
     };
     const result = (await getRoute("POST", "oauth/request").handler(
       makeArgs({
         body: {
-          provider: "google",
-          url: "/calendar/v3/calendars/primary/events",
+          provider: "slack_channel",
+          url: "/chat.postMessage",
+          parsed_data: { channel: "C1", text: "digest" },
         },
       }),
-    )) as { ok: boolean; status: number; hint?: string };
+    )) as { ok: boolean; status: number; body: unknown; hint?: string };
     expect(result.ok).toBe(false);
-    expect(result.status).toBe(404);
-    expect(result.hint).toContain("HTML");
-    // Reports the resolved base URL the relative path was joined onto.
-    expect(result.hint).toContain("https://api.google.com");
-    // Steers the caller toward an absolute URL.
-    expect(result.hint).toContain("absolute URL");
+    expect(result.status).toBe(200);
+    expect(result.body).toEqual({ ok: false, error: "not_in_channel" });
+    expect(result.hint).toContain("ok: false");
   });
 
-  test("does not attach HTML-404 hint when a 404 body is JSON", async () => {
+  test("a body without the declared ok field leaves the status as the verdict", async () => {
+    // A file download from the same credential answers with bytes, not the
+    // envelope, and must not read as a refusal.
+    mockProviders.slack_channel = seededProvider("slack_channel");
     mockResolveResponse = {
-      status: 404,
-      headers: { "content-type": "application/json" },
-      body: { error: "not found" },
+      status: 200,
+      headers: { "content-type": "image/png" },
+      body: Buffer.from([0x89, 0x50, 0x4e, 0x47]),
     };
     const result = (await getRoute("POST", "oauth/request").handler(
       makeArgs({
-        body: { provider: "google", url: "/v1/missing" },
+        body: {
+          provider: "slack_channel",
+          url: "https://files.slack.com/files-pri/T0123-F0456/download/shot.png",
+        },
       }),
-    )) as { ok: boolean; status: number; hint?: string };
-    expect(result.ok).toBe(false);
-    expect(result.status).toBe(404);
+    )) as { ok: boolean; hint?: string };
+    expect(result.ok).toBe(true);
     expect(result.hint).toBeUndefined();
   });
 
-  test("HTML-404 hint reports an absolute URL's own host as the resolved base", async () => {
-    mockProviders.google = {
-      ...baseProvider,
-      injectionTemplates: JSON.stringify([
-        {
-          hostPattern: "www.googleapis.com",
-          injectionType: "header",
-          headerName: "Authorization",
-          valuePrefix: "Bearer ",
-        },
-      ]),
-    };
+  test("a provider that declares no ok field is judged by status alone", async () => {
     mockResolveResponse = {
-      status: 404,
-      headers: { "content-type": "text/html" },
-      body: "<html>nope</html>",
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: { ok: false, error: "not_an_envelope" },
     };
     const result = (await getRoute("POST", "oauth/request").handler(
       makeArgs({
-        body: {
-          provider: "google",
-          url: "https://www.googleapis.com/calendar/v3/nope",
-        },
+        body: { provider: "google", url: "https://api.google.com/v1/me" },
       }),
-    )) as { hint?: string };
-    expect(result.hint).toContain("https://www.googleapis.com");
-  });
-
-  test("rejects unregistered client_id in BYO mode", async () => {
-    // No entry in mockApps for google:client-x
-    await expect(
-      getRoute("POST", "oauth/request").handler(
-        makeArgs({
-          body: {
-            provider: "google",
-            url: "https://api.google.com/v1/me",
-            client_id: "client-x",
-          },
-        }),
-      ),
-    ).rejects.toBeInstanceOf(NotFoundError);
+    )) as { ok: boolean };
+    expect(result.ok).toBe(true);
   });
 });
 

package/src/__tests__/oauth-connect-orchestrator.test.ts

@@ -105,6 +105,7 @@ type ProviderRow = {
   identityResponsePaths: string | null;
   identityFormat: string | null;
   identityOkField: string | null;
+  responseOkField: string | null;
   featureFlag: string | null;
   createdAt: number;
   updatedAt: number;
@@ -184,6 +185,7 @@ function makeProviderRow(
     identityResponsePaths: null,
     identityFormat: null,
     identityOkField: null,
+    responseOkField: null,
     featureFlag: null,
     createdAt: now,
     updatedAt: now,

package/src/__tests__/oauth-provider-serializer.test.ts

@@ -47,6 +47,7 @@ function makeRow(overrides: Partial<OAuthProviderRow> = {}): OAuthProviderRow {
     identityResponsePaths: null,
     identityFormat: null,
     identityOkField: null,
+    responseOkField: null,
     featureFlag: null,
     createdAt: now,
     updatedAt: now,
@@ -291,11 +292,23 @@ describe("serializeProviderSummary", () => {
       supports_managed_mode: true,
       managed_service_is_paid: false,
       feature_flag: null,
+      category: "productivity",
       tenant_host: null,
       acts_as: "user",
     });
   });
 
+  test("files the provider under its seeded category", () => {
+    // The category is catalog metadata the seed carries, not a column, so a
+    // provider a user registered by hand has none.
+    const category = (provider: string) =>
+      serializeProviderSummary(makeRow({ provider }))!.category;
+
+    expect(category("hubspot")).toBe("sales");
+    expect(category("calendly")).toBe("meetings");
+    expect(category("custom-provider")).toBeNull();
+  });
+
   test("exposes the tenant host a per-tenant provider needs at connect", () => {
     // Shopify's OAuth endpoints live on the merchant's own host, so a client
     // has to collect it before the managed flow can start. The summary is the

package/src/__tests__/oauth-providers-routes.test.ts

@@ -38,6 +38,7 @@ const mockListProviders = mock(() => [
     identityBody: null,
     identityFormat: null,
     identityOkField: null,
+    responseOkField: null,
     identityResponsePaths: null,
     featureFlag: null,
     createdAt: 1735689500000,
@@ -80,6 +81,7 @@ const mockListProviders = mock(() => [
     identityBody: null,
     identityFormat: null,
     identityOkField: null,
+    responseOkField: null,
     identityResponsePaths: null,
     featureFlag: null,
     createdAt: 1735689600000,
@@ -178,6 +180,7 @@ describe("GET /v1/oauth/providers", () => {
       "supports_managed_mode",
       "managed_service_is_paid",
       "feature_flag",
+      "category",
       "tenant_host",
       "acts_as",
     ];

package/src/__tests__/outbound-slack-persistence.test.ts

@@ -185,6 +185,7 @@ import {
 } from "../daemon/conversation-agent-loop-handlers.js";
 import { readSlackMetadataFromMessageMetadata } from "../messaging/providers/slack/message-metadata.js";
 import { deliverReplyViaCallback } from "../runtime/channel-reply-delivery.js";
+import { mockUnownedModeSessions } from "./helpers/mock-conversation.js";
 import { setConfig } from "./helpers/set-config.js";
 
 // ── Helpers ────────────────────────────────────────────────────────────────
@@ -216,6 +217,7 @@ function makeDeps(
         sourceThreadId: overrides.sourceThreadId,
       },
       clientTimezone: overrides.clientTimezone,
+      modeSessions: mockUnownedModeSessions(),
     } as unknown as EventHandlerDeps["ctx"],
     onEvent: (_msg: AssistantEvent) => {},
     reqId: "test-req-id",