@vellumai/vellum-gateway 0.4.29 → 0.4.30

package/ARCHITECTURE.md

@@ -122,9 +122,9 @@ Runtime health is exposed directly by the gateway at `GET /v1/health` and forwar
 | `gateway/src/http/routes/runtime-health-proxy.ts` | Runtime health proxy handler and upstream forwarding            |
 | `gateway/src/index.ts`                            | Route registration and bearer-auth enforcement for `/v1/health` |
 
-### Telegram + Ingress Control-Plane Proxies
+### Telegram + Contacts Control-Plane Proxies
 
-Telegram integration setup/config endpoints and ingress members/invites endpoints are also exposed directly by the gateway and forwarded to runtime handlers even when the broad runtime proxy is disabled.
+Telegram integration setup/config endpoints and contacts/invites endpoints are also exposed directly by the gateway and forwarded to runtime handlers even when the broad runtime proxy is disabled.
 
 **Forwarded Telegram endpoints:**
 
@@ -134,16 +134,17 @@ Telegram integration setup/config endpoints and ingress members/invites endpoint
 | POST            | `/v1/integrations/telegram/commands` |
 | POST            | `/v1/integrations/telegram/setup`    |
 
-**Forwarded ingress endpoints:**
+**Forwarded contact & invite endpoints:**
 
-| Method   | Path                                  |
-| -------- | ------------------------------------- |
-| GET/POST | `/v1/ingress/members`                 |
-| DELETE   | `/v1/ingress/members/:memberId`       |
-| POST     | `/v1/ingress/members/:memberId/block` |
-| GET/POST | `/v1/ingress/invites`                 |
-| DELETE   | `/v1/ingress/invites/:inviteId`       |
-| POST     | `/v1/ingress/invites/redeem`          |
+| Method   | Path                             |
+| -------- | -------------------------------- |
+| GET/POST | `/v1/contacts`                   |
+| GET      | `/v1/contacts/:contactId`        |
+| POST     | `/v1/contacts/merge`             |
+| PATCH    | `/v1/contacts/channels/:id`      |
+| GET/POST | `/v1/contacts/invites`           |
+| DELETE   | `/v1/contacts/invites/:inviteId` |
+| POST     | `/v1/contacts/invites/redeem`    |
 
 **Authentication boundary:**
 
@@ -153,11 +154,11 @@ Telegram integration setup/config endpoints and ingress members/invites endpoint
 
 **Key source files:**
 
-| File                                                      | Purpose                                                                                              |
-| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `gateway/src/http/routes/telegram-control-plane-proxy.ts` | Telegram control-plane proxy handlers and upstream forwarding                                        |
-| `gateway/src/http/routes/ingress-control-plane-proxy.ts`  | Ingress control-plane proxy handlers and upstream forwarding                                         |
-| `gateway/src/index.ts`                                    | Route registration and bearer-auth enforcement for `/v1/integrations/telegram/*` and `/v1/ingress/*` |
+| File                                                      | Purpose                                                                                                       |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `gateway/src/http/routes/telegram-control-plane-proxy.ts` | Telegram control-plane proxy handlers and upstream forwarding                                                 |
+| `gateway/src/http/routes/contacts-control-plane-proxy.ts` | Contacts control-plane proxy handlers and upstream forwarding                                                 |
+| `gateway/src/index.ts`                                    | Route registration and bearer-auth enforcement for `/v1/integrations/telegram/*` and `/v1/contacts/invites/*` |
 
 ### Twilio Control-Plane Proxy
 
@@ -567,10 +568,10 @@ If no guardian binding exists for the channel, escalation fails closed -- the me
 
 | Module                                           | Purpose                                                                   |
 | ------------------------------------------------ | ------------------------------------------------------------------------- |
-| `assistant/src/memory/ingress-invite-store.ts`   | CRUD for invite tokens with SHA-256 hashing and expiry                    |
+| `assistant/src/memory/invite-store.ts`           | CRUD for invite tokens with SHA-256 hashing and expiry                    |
 | `assistant/src/contacts/contact-store.ts`        | Contact and channel lookups (findContactChannel, guardian bindings)       |
 | `assistant/src/contacts/contacts-write.ts`       | Contact and channel writes (upsert, policy changes, invite redemption)    |
-| `assistant/src/daemon/handlers/config-inbox.ts`  | IPC handlers for ingress invite and member contracts                      |
+| `assistant/src/daemon/handlers/config-inbox.ts`  | IPC handlers for invite and member contracts                              |
 | `assistant/src/runtime/routes/channel-routes.ts` | ACL enforcement point -- member lookup, policy check, escalation creation |
 
 ### Telegram Credential Flow

package/README.md

@@ -223,12 +223,13 @@ The gateway serves as the single public ingress point for all external callbacks
 | `/v1/integrations/telegram/config`          | GET/POST/DELETE | Authenticated control-plane proxy for Telegram integration config                                                                                                                       |
 | `/v1/integrations/telegram/commands`        | POST            | Authenticated control-plane proxy for Telegram command registration                                                                                                                     |
 | `/v1/integrations/telegram/setup`           | POST            | Authenticated control-plane proxy for Telegram setup orchestration                                                                                                                      |
-| `/v1/ingress/members`                       | GET/POST        | Authenticated control-plane proxy for listing/upserting ingress members                                                                                                                 |
-| `/v1/ingress/members/:id`                   | DELETE          | Authenticated control-plane proxy for revoking an ingress member                                                                                                                        |
-| `/v1/ingress/members/:id/block`             | POST            | Authenticated control-plane proxy for blocking an ingress member                                                                                                                        |
-| `/v1/ingress/invites`                       | GET/POST        | Authenticated control-plane proxy for listing/creating ingress invites                                                                                                                  |
-| `/v1/ingress/invites/:id`                   | DELETE          | Authenticated control-plane proxy for revoking an ingress invite                                                                                                                        |
-| `/v1/ingress/invites/redeem`                | POST            | Authenticated control-plane proxy for redeeming an ingress invite                                                                                                                       |
+| `/v1/contacts`                              | GET/POST        | Authenticated control-plane proxy for listing/searching and creating/updating contacts                                                                                                  |
+| `/v1/contacts/:id`                          | GET             | Authenticated control-plane proxy for retrieving a contact by ID                                                                                                                        |
+| `/v1/contacts/merge`                        | POST            | Authenticated control-plane proxy for merging two contacts                                                                                                                              |
+| `/v1/contacts/channels/:id`                 | PATCH           | Authenticated control-plane proxy for updating a contact channel's status/policy                                                                                                        |
+| `/v1/contacts/invites`                      | GET/POST        | Authenticated control-plane proxy for listing/creating contact invites                                                                                                                  |
+| `/v1/contacts/invites/:id`                  | DELETE          | Authenticated control-plane proxy for revoking a contact invite                                                                                                                         |
+| `/v1/contacts/invites/redeem`               | POST            | Authenticated control-plane proxy for redeeming a contact invite                                                                                                                        |
 | `/v1/health`                                | GET             | Authenticated runtime health proxy (`/v1/health` on runtime)                                                                                                                            |
 | `/healthz`                                  | GET             | Liveness probe                                                                                                                                                                          |
 | `/readyz`                                   | GET             | Readiness probe                                                                                                                                                                         |
@@ -299,7 +300,7 @@ When `INGRESS_PUBLIC_BASE_URL` is configured, the gateway prioritizes it as the
 
 ## Default Mode: Dedicated Routes Only
 
-By default, the broad runtime proxy is disabled. Dedicated gateway-managed routes (webhooks, delivery endpoints, explicit control-plane proxies such as `/v1/integrations/guardian/*`, `/v1/integrations/telegram/*`, and `/v1/ingress/*`, plus the authenticated runtime health route `/v1/health`) remain available, but arbitrary runtime passthrough routes return `404` unless `GATEWAY_RUNTIME_PROXY_ENABLED=true`.
+By default, the broad runtime proxy is disabled. Dedicated gateway-managed routes (webhooks, delivery endpoints, explicit control-plane proxies such as `/v1/integrations/guardian/*`, `/v1/integrations/telegram/*`, and `/v1/contacts/invites/*`, plus the authenticated runtime health route `/v1/health`) remain available, but arbitrary runtime passthrough routes return `404` unless `GATEWAY_RUNTIME_PROXY_ENABLED=true`.
 
 ## Runtime Proxy Mode
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.4.29",
+  "version": "0.4.30",
   "type": "module",
   "exports": {
     "./twilio/verify": "./src/twilio/verify.ts",

package/src/__tests__/block-kit-builder.test.ts

@@ -0,0 +1,58 @@
+import { describe, test, expect } from "bun:test";
+import { BlockKitBuilder } from "../slack/block-kit-builder.js";
+
+describe("block-kit-builder", () => {
+  describe("static entry points", () => {
+    test("BlockKitBuilder.section() creates a mrkdwn section block", () => {
+      expect(BlockKitBuilder.section("hello").toBlocks()).toEqual([
+        { type: "section", text: { type: "mrkdwn", text: "hello" } },
+      ]);
+    });
+
+    test("BlockKitBuilder.divider() creates a divider block", () => {
+      expect(BlockKitBuilder.divider().toBlocks()).toEqual([
+        { type: "divider" },
+      ]);
+    });
+
+    test("BlockKitBuilder.header() creates a plain_text header block", () => {
+      expect(BlockKitBuilder.header("Title").toBlocks()).toEqual([
+        {
+          type: "header",
+          text: { type: "plain_text", text: "Title", emoji: true },
+        },
+      ]);
+    });
+  });
+
+  describe("BlockKitBuilder", () => {
+    test("builds blocks via fluent API", () => {
+      const blocks = new BlockKitBuilder()
+        .header("Welcome")
+        .section("Some *bold* text")
+        .divider()
+        .section("More content")
+        .toBlocks();
+
+      expect(blocks).toEqual([
+        {
+          type: "header",
+          text: { type: "plain_text", text: "Welcome", emoji: true },
+        },
+        {
+          type: "section",
+          text: { type: "mrkdwn", text: "Some *bold* text" },
+        },
+        { type: "divider" },
+        { type: "section", text: { type: "mrkdwn", text: "More content" } },
+      ]);
+    });
+
+    test("toBlocks() returns consistent results", () => {
+      const builder = new BlockKitBuilder().section("test");
+      const blocks1 = builder.toBlocks();
+      const blocks2 = builder.toBlocks();
+      expect(blocks1).toEqual(blocks2);
+    });
+  });
+});

package/src/__tests__/{ingress-control-plane-proxy.test.ts → contacts-control-plane-proxy.test.ts}

@@ -17,8 +17,8 @@ mock.module("../fetch.js", () => ({
   fetchImpl: (...args: Parameters<FetchFn>) => fetchMock(...args),
 }));
 
-const { createIngressControlPlaneProxyHandler } =
-  await import("../http/routes/ingress-control-plane-proxy.js");
+const { createContactsControlPlaneProxyHandler } =
+  await import("../http/routes/contacts-control-plane-proxy.js");
 
 function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
   const merged: GatewayConfig = {
@@ -71,8 +71,8 @@ afterEach(() => {
   fetchMock = mock(async () => new Response());
 });
 
-describe("ingress control-plane proxy", () => {
-  test("forwards ingress endpoints to the runtime", async () => {
+describe("contacts control-plane proxy", () => {
+  test("forwards contact endpoints to the runtime", async () => {
     const captured: string[] = [];
     fetchMock = mock(async (input: string | URL | Request) => {
       captured.push(String(input));
@@ -82,59 +82,76 @@ describe("ingress control-plane proxy", () => {
       });
     });
 
-    const handler = createIngressControlPlaneProxyHandler(makeConfig());
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
 
-    await handler.handleListMembers(
-      new Request(
-        "http://localhost:7830/v1/ingress/members?sourceChannel=telegram",
-      ),
+    await handler.handleListContacts(
+      new Request("http://localhost:7830/v1/contacts?limit=10"),
     );
-    await handler.handleUpsertMember(
-      new Request("http://localhost:7830/v1/ingress/members", {
-        method: "POST",
-      }),
+    await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", { method: "POST" }),
     );
-    await handler.handleRevokeMember(
-      new Request("http://localhost:7830/v1/ingress/members/mbr_123", {
-        method: "DELETE",
-      }),
-      "mbr_123",
+    await handler.handleGetContact(
+      new Request("http://localhost:7830/v1/contacts/ct_1"),
+      "ct_1",
     );
-    await handler.handleBlockMember(
-      new Request("http://localhost:7830/v1/ingress/members/mbr_123/block", {
+    await handler.handleMergeContacts(
+      new Request("http://localhost:7830/v1/contacts/merge", {
         method: "POST",
       }),
-      "mbr_123",
     );
+    await handler.handleUpdateContactChannel(
+      new Request("http://localhost:7830/v1/contacts/channels/ch_1", {
+        method: "PATCH",
+      }),
+      "ch_1",
+    );
+
+    expect(captured).toEqual([
+      "http://localhost:7821/v1/contacts?limit=10",
+      "http://localhost:7821/v1/contacts",
+      "http://localhost:7821/v1/contacts/ct_1",
+      "http://localhost:7821/v1/contacts/merge",
+      "http://localhost:7821/v1/contacts/channels/ch_1",
+    ]);
+  });
+
+  test("forwards invite endpoints to the runtime", async () => {
+    const captured: string[] = [];
+    fetchMock = mock(async (input: string | URL | Request) => {
+      captured.push(String(input));
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    });
+
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+
     await handler.handleListInvites(
-      new Request("http://localhost:7830/v1/ingress/invites?status=active"),
+      new Request("http://localhost:7830/v1/contacts/invites?status=active"),
     );
     await handler.handleCreateInvite(
-      new Request("http://localhost:7830/v1/ingress/invites", {
+      new Request("http://localhost:7830/v1/contacts/invites", {
         method: "POST",
       }),
     );
     await handler.handleRedeemInvite(
-      new Request("http://localhost:7830/v1/ingress/invites/redeem", {
+      new Request("http://localhost:7830/v1/contacts/invites/redeem", {
         method: "POST",
       }),
     );
     await handler.handleRevokeInvite(
-      new Request("http://localhost:7830/v1/ingress/invites/inv_123", {
+      new Request("http://localhost:7830/v1/contacts/invites/inv_123", {
         method: "DELETE",
       }),
       "inv_123",
     );
 
     expect(captured).toEqual([
-      "http://localhost:7821/v1/ingress/members?sourceChannel=telegram",
-      "http://localhost:7821/v1/ingress/members",
-      "http://localhost:7821/v1/ingress/members/mbr_123",
-      "http://localhost:7821/v1/ingress/members/mbr_123/block",
-      "http://localhost:7821/v1/ingress/invites?status=active",
-      "http://localhost:7821/v1/ingress/invites",
-      "http://localhost:7821/v1/ingress/invites/redeem",
-      "http://localhost:7821/v1/ingress/invites/inv_123",
+      "http://localhost:7821/v1/contacts/invites?status=active",
+      "http://localhost:7821/v1/contacts/invites",
+      "http://localhost:7821/v1/contacts/invites/redeem",
+      "http://localhost:7821/v1/contacts/invites/inv_123",
     ]);
   });
 
@@ -147,9 +164,9 @@ describe("ingress control-plane proxy", () => {
       },
     );
 
-    const handler = createIngressControlPlaneProxyHandler(makeConfig());
-    const res = await handler.handleUpsertMember(
-      new Request("http://localhost:7830/v1/ingress/members", {
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleCreateInvite(
+      new Request("http://localhost:7830/v1/contacts/invites", {
         method: "POST",
         headers: {
           authorization: "Bearer caller-token",
@@ -178,9 +195,9 @@ describe("ingress control-plane proxy", () => {
       );
     });
 
-    const handler = createIngressControlPlaneProxyHandler(makeConfig());
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
     const res = await handler.handleCreateInvite(
-      new Request("http://localhost:7830/v1/ingress/invites", {
+      new Request("http://localhost:7830/v1/contacts/invites", {
         method: "POST",
       }),
     );
@@ -200,11 +217,11 @@ describe("ingress control-plane proxy", () => {
       );
     });
 
-    const handler = createIngressControlPlaneProxyHandler(
+    const handler = createContactsControlPlaneProxyHandler(
       makeConfig({ runtimeTimeoutMs: 100 }),
     );
-    const res = await handler.handleListMembers(
-      new Request("http://localhost:7830/v1/ingress/members"),
+    const res = await handler.handleListInvites(
+      new Request("http://localhost:7830/v1/contacts/invites"),
     );
 
     expect(res.status).toBe(504);

package/src/__tests__/contacts-control-plane-route-match.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test";
+import { matchContactsControlPlaneRoute } from "../http/routes/contacts-control-plane-route-match.js";
+
+describe("matchContactsControlPlaneRoute", () => {
+  test("matches contact CRUD routes", () => {
+    expect(matchContactsControlPlaneRoute("/v1/contacts", "GET")).toEqual({
+      kind: "listContacts",
+    });
+    expect(matchContactsControlPlaneRoute("/v1/contacts", "POST")).toEqual({
+      kind: "upsertContact",
+    });
+    expect(matchContactsControlPlaneRoute("/v1/contacts/merge", "POST")).toEqual(
+      { kind: "mergeContacts" },
+    );
+    expect(
+      matchContactsControlPlaneRoute("/v1/contacts/channels/ch_1", "PATCH"),
+    ).toEqual({ kind: "updateContactChannel", channelId: "ch_1" });
+    expect(matchContactsControlPlaneRoute("/v1/contacts/ct_1", "GET")).toEqual({
+      kind: "getContact",
+      contactId: "ct_1",
+    });
+  });
+
+  test("returns null for unsupported methods on contact routes", () => {
+    expect(matchContactsControlPlaneRoute("/v1/contacts", "DELETE")).toBeNull();
+    // GET /v1/contacts/channels/ch_1 does not match (PATCH only)
+    expect(
+      matchContactsControlPlaneRoute("/v1/contacts/channels/ch_1", "GET"),
+    ).toBeNull();
+  });
+
+  test("GET /v1/contacts/merge falls through to getContact", () => {
+    // No GET handler for /merge, so the contactId catch-all picks it up
+    expect(matchContactsControlPlaneRoute("/v1/contacts/merge", "GET")).toEqual({
+      kind: "getContact",
+      contactId: "merge",
+    });
+  });
+
+  test("matches redeem invite only for POST", () => {
+    expect(
+      matchContactsControlPlaneRoute("/v1/contacts/invites/redeem", "POST"),
+    ).toEqual({
+      kind: "redeemInvite",
+    });
+
+    // DELETE should treat `redeem` as an invite ID so revoke routing still works.
+    expect(
+      matchContactsControlPlaneRoute("/v1/contacts/invites/redeem", "DELETE"),
+    ).toEqual({
+      kind: "revokeInvite",
+      inviteId: "redeem",
+    });
+  });
+
+  test("matches contacts invite routes", () => {
+    expect(
+      matchContactsControlPlaneRoute("/v1/contacts/invites", "GET"),
+    ).toEqual({
+      kind: "listInvites",
+    });
+    expect(
+      matchContactsControlPlaneRoute("/v1/contacts/invites", "POST"),
+    ).toEqual({
+      kind: "createInvite",
+    });
+    expect(
+      matchContactsControlPlaneRoute("/v1/contacts/invites/inv_1", "DELETE"),
+    ).toEqual({
+      kind: "revokeInvite",
+      inviteId: "inv_1",
+    });
+  });
+
+  test("returns null for unsupported method/path combinations", () => {
+    expect(
+      matchContactsControlPlaneRoute("/v1/contacts/invites/redeem", "GET"),
+    ).toBeNull();
+    expect(
+      matchContactsControlPlaneRoute("/v1/contacts/invites/inv_1", "POST"),
+    ).toBeNull();
+    expect(
+      matchContactsControlPlaneRoute("/v1/ingress/unknown", "GET"),
+    ).toBeNull();
+  });
+});

package/src/__tests__/schema.test.ts

@@ -64,12 +64,13 @@ describe("/schema route", () => {
     expect(body.paths["/v1/integrations/telegram/config"]).toBeDefined();
     expect(body.paths["/v1/integrations/telegram/commands"]).toBeDefined();
     expect(body.paths["/v1/integrations/telegram/setup"]).toBeDefined();
-    expect(body.paths["/v1/ingress/members"]).toBeDefined();
-    expect(body.paths["/v1/ingress/members/{memberId}"]).toBeDefined();
-    expect(body.paths["/v1/ingress/members/{memberId}/block"]).toBeDefined();
-    expect(body.paths["/v1/ingress/invites"]).toBeDefined();
-    expect(body.paths["/v1/ingress/invites/redeem"]).toBeDefined();
-    expect(body.paths["/v1/ingress/invites/{inviteId}"]).toBeDefined();
+    expect(body.paths["/v1/contacts"]).toBeDefined();
+    expect(body.paths["/v1/contacts/merge"]).toBeDefined();
+    expect(body.paths["/v1/contacts/channels/{channelId}"]).toBeDefined();
+    expect(body.paths["/v1/contacts/{contactId}"]).toBeDefined();
+    expect(body.paths["/v1/contacts/invites"]).toBeDefined();
+    expect(body.paths["/v1/contacts/invites/redeem"]).toBeDefined();
+    expect(body.paths["/v1/contacts/invites/{inviteId}"]).toBeDefined();
     expect(body.paths["/v1/integrations/guardian/challenge"]).toBeDefined();
     expect(body.paths["/v1/integrations/guardian/status"]).toBeDefined();
     expect(
@@ -170,24 +171,4 @@ describe("buildSchema()", () => {
     });
     expect(telegramDeliver.anyOf).toContainEqual({ required: ["chatAction"] });
   });
-
-  test("ingress member block request body is optional", () => {
-    const schema = buildSchema() as {
-      paths: Record<
-        string,
-        {
-          post?: {
-            requestBody?: {
-              required?: boolean;
-            };
-          };
-        }
-      >;
-    };
-
-    const ingressMemberBlockPost =
-      schema.paths["/v1/ingress/members/{memberId}/block"]?.post;
-    expect(ingressMemberBlockPost).toBeDefined();
-    expect(ingressMemberBlockPost?.requestBody?.required).toBe(false);
-  });
 });

package/src/__tests__/slack-app-home.test.ts

@@ -0,0 +1,155 @@
+import { describe, test, expect } from "bun:test";
+import { buildAppHomeView, type AppHomeContext } from "../slack/app-home.js";
+
+describe("buildAppHomeView", () => {
+  test("returns a home-type view", () => {
+    const ctx: AppHomeContext = { connected: true };
+    const view = buildAppHomeView(ctx);
+    expect(view.type).toBe("home");
+  });
+
+  test("includes header block with 'Vellum Assistant'", () => {
+    const ctx: AppHomeContext = { connected: true };
+    const view = buildAppHomeView(ctx);
+    const header = view.blocks.find((b) => b.type === "header");
+    expect(header).toBeDefined();
+    expect(header!.type === "header" && header!.text.text).toBe(
+      "Vellum Assistant",
+    );
+  });
+
+  test("shows green status when connected", () => {
+    const ctx: AppHomeContext = { connected: true };
+    const view = buildAppHomeView(ctx);
+    const statusBlock = view.blocks.find(
+      (b) =>
+        b.type === "section" &&
+        b.text.type === "mrkdwn" &&
+        b.text.text.includes("Status"),
+    );
+    expect(statusBlock).toBeDefined();
+    if (statusBlock && statusBlock.type === "section") {
+      expect(statusBlock.text.text).toContain(":large_green_circle:");
+      expect(statusBlock.text.text).toContain("Connected");
+    }
+  });
+
+  test("shows red status when disconnected", () => {
+    const ctx: AppHomeContext = { connected: false };
+    const view = buildAppHomeView(ctx);
+    const statusBlock = view.blocks.find(
+      (b) =>
+        b.type === "section" &&
+        b.text.type === "mrkdwn" &&
+        b.text.text.includes("Status"),
+    );
+    expect(statusBlock).toBeDefined();
+    if (statusBlock && statusBlock.type === "section") {
+      expect(statusBlock.text.text).toContain(":red_circle:");
+      expect(statusBlock.text.text).toContain("Disconnected");
+    }
+  });
+
+  test("includes workspace name when provided", () => {
+    const ctx: AppHomeContext = {
+      connected: true,
+      workspaceName: "My Workspace",
+    };
+    const view = buildAppHomeView(ctx);
+    const connectionBlock = view.blocks.find(
+      (b) =>
+        b.type === "section" &&
+        b.text.type === "mrkdwn" &&
+        b.text.text.includes("Connection Info"),
+    );
+    expect(connectionBlock).toBeDefined();
+    if (connectionBlock && connectionBlock.type === "section") {
+      expect(connectionBlock.text.text).toContain("My Workspace");
+    }
+  });
+
+  test("includes bot username when provided", () => {
+    const ctx: AppHomeContext = {
+      connected: true,
+      botUsername: "vellum-bot",
+    };
+    const view = buildAppHomeView(ctx);
+    const connectionBlock = view.blocks.find(
+      (b) =>
+        b.type === "section" &&
+        b.text.type === "mrkdwn" &&
+        b.text.text.includes("Connection Info"),
+    );
+    expect(connectionBlock).toBeDefined();
+    if (connectionBlock && connectionBlock.type === "section") {
+      expect(connectionBlock.text.text).toContain("@vellum-bot");
+    }
+  });
+
+  test("omits workspace line when not provided", () => {
+    const ctx: AppHomeContext = { connected: true };
+    const view = buildAppHomeView(ctx);
+    const connectionBlock = view.blocks.find(
+      (b) =>
+        b.type === "section" &&
+        b.text.type === "mrkdwn" &&
+        b.text.text.includes("Connection Info"),
+    );
+    expect(connectionBlock).toBeDefined();
+    if (connectionBlock && connectionBlock.type === "section") {
+      expect(connectionBlock.text.text).not.toContain("Workspace:");
+    }
+  });
+
+  test("omits bot line when not provided", () => {
+    const ctx: AppHomeContext = { connected: true };
+    const view = buildAppHomeView(ctx);
+    const connectionBlock = view.blocks.find(
+      (b) =>
+        b.type === "section" &&
+        b.text.type === "mrkdwn" &&
+        b.text.text.includes("Connection Info"),
+    );
+    expect(connectionBlock).toBeDefined();
+    if (connectionBlock && connectionBlock.type === "section") {
+      expect(connectionBlock.text.text).not.toContain("Bot:");
+    }
+  });
+
+  test("includes capabilities section", () => {
+    const ctx: AppHomeContext = { connected: true };
+    const view = buildAppHomeView(ctx);
+    const capBlock = view.blocks.find(
+      (b) =>
+        b.type === "section" &&
+        b.text.type === "mrkdwn" &&
+        b.text.text.includes("Capabilities"),
+    );
+    expect(capBlock).toBeDefined();
+    if (capBlock && capBlock.type === "section") {
+      expect(capBlock.text.text).toContain("Mention me");
+      expect(capBlock.text.text).toContain("direct message");
+      expect(capBlock.text.text).toContain("threads");
+    }
+  });
+
+  test("includes dividers between sections", () => {
+    const ctx: AppHomeContext = { connected: true };
+    const view = buildAppHomeView(ctx);
+    const dividers = view.blocks.filter((b) => b.type === "divider");
+    expect(dividers.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("all blocks have valid types", () => {
+    const ctx: AppHomeContext = {
+      connected: true,
+      botUsername: "bot",
+      workspaceName: "ws",
+    };
+    const view = buildAppHomeView(ctx);
+    const validTypes = new Set(["header", "section", "divider", "actions"]);
+    for (const block of view.blocks) {
+      expect(validTypes.has(block.type)).toBe(true);
+    }
+  });
+});