@vellumai/vellum-gateway 0.8.2 → 0.8.4

package/src/http/routes/a2a-routes.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect, mock, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// --- Workspace dir mock -----------------------------------------------------
+
+let testWorkspaceDir: string;
+
+mock.module("../../credential-reader.js", () => ({
+  getWorkspaceDir: () => testWorkspaceDir,
+}));
+
+// Import after mocks are registered
+const { createAgentCardHandler } = await import("./a2a-routes.js");
+
+// --- Helpers ---------------------------------------------------------------
+
+function makeConfigFileCache(overrides?: {
+  a2aEnabled?: boolean;
+  publicBaseUrl?: string;
+}) {
+  const data: Record<string, Record<string, unknown>> = {
+    a2a: { enabled: overrides?.a2aEnabled ?? false },
+    ingress: {
+      publicBaseUrl: overrides?.publicBaseUrl ?? "https://example.com",
+    },
+  };
+
+  return {
+    getBoolean: (section: string, field: string) => {
+      const val = data[section]?.[field];
+      return typeof val === "boolean" ? val : undefined;
+    },
+    getString: (section: string, field: string) => {
+      const val = data[section]?.[field];
+      return typeof val === "string" ? val : undefined;
+    },
+  } as import("../../config-file-cache.js").ConfigFileCache;
+}
+
+// --- Setup / teardown -------------------------------------------------------
+
+beforeEach(() => {
+  testWorkspaceDir = mkdtempSync(join(tmpdir(), "a2a-test-"));
+});
+
+afterEach(() => {
+  rmSync(testWorkspaceDir, { recursive: true, force: true });
+});
+
+// --- Tests -----------------------------------------------------------------
+
+describe("Agent Card", () => {
+  it("returns 404 when A2A is not enabled", async () => {
+    const configFile = makeConfigFileCache({ a2aEnabled: false });
+    const handler = createAgentCardHandler(configFile);
+
+    const res = await handler(
+      new Request("http://localhost:7830/.well-known/agent-card.json"),
+    );
+
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain("not enabled");
+  });
+
+  it("serves agent card with fallback name when no IDENTITY.md", async () => {
+    const configFile = makeConfigFileCache({
+      a2aEnabled: true,
+      publicBaseUrl: "https://my-assistant.example.com",
+    });
+    const handler = createAgentCardHandler(configFile);
+
+    const res = await handler(
+      new Request("http://localhost:7830/.well-known/agent-card.json"),
+    );
+
+    expect(res.status).toBe(200);
+    const card = (await res.json()) as {
+      name: string;
+      supported_interfaces: Array<{ url: string }>;
+      capabilities: { push_notifications: boolean };
+    };
+    expect(card.name).toBe("Vellum Assistant");
+    expect(card.supported_interfaces[0].url).toBe(
+      "https://my-assistant.example.com/a2a/message:send",
+    );
+    expect(card.capabilities.push_notifications).toBe(true);
+  });
+
+  it("reads assistant name from IDENTITY.md", async () => {
+    const promptsDir = join(testWorkspaceDir, "prompts");
+    mkdirSync(promptsDir, { recursive: true });
+    writeFileSync(
+      join(promptsDir, "IDENTITY.md"),
+      "**Name:** Alice\n\nA helpful research assistant.",
+    );
+
+    const configFile = makeConfigFileCache({
+      a2aEnabled: true,
+      publicBaseUrl: "https://alice.example.com",
+    });
+    const handler = createAgentCardHandler(configFile);
+
+    const res = await handler(
+      new Request("http://localhost:7830/.well-known/agent-card.json"),
+    );
+
+    expect(res.status).toBe(200);
+    const card = (await res.json()) as { name: string; description: string };
+    expect(card.name).toBe("Alice");
+    expect(card.description).toBe("Alice — a Vellum AI assistant");
+  });
+
+  it("returns 503 when no public base URL is configured", async () => {
+    const configFile = makeConfigFileCache({
+      a2aEnabled: true,
+      publicBaseUrl: "",
+    });
+    const handler = createAgentCardHandler(configFile);
+
+    const res = await handler(
+      new Request("http://localhost:7830/.well-known/agent-card.json"),
+    );
+
+    expect(res.status).toBe(503);
+  });
+});

package/src/http/routes/a2a-routes.ts

@@ -0,0 +1,121 @@
+/**
+ * A2A agent card discovery endpoint:
+ * - GET /.well-known/agent-card.json — agent card for peer discovery
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { ConfigFileCache } from "../../config-file-cache.js";
+import { getWorkspaceDir } from "../../credential-reader.js";
+import { getLogger } from "../../logger.js";
+
+const log = getLogger("a2a-routes");
+
+// ── A2A protocol constants (duplicated to avoid cross-package import) ──
+
+const A2A_AGENT_CARD_PATH = "/.well-known/agent-card.json";
+
+// ── Agent card builder ──────────────────────────────────────────────
+
+interface AgentCard {
+  name: string;
+  description: string;
+  version: string;
+  supported_interfaces: Array<{
+    url: string;
+    protocol_binding: string;
+    protocol_version: string;
+  }>;
+  capabilities: {
+    streaming: boolean;
+    push_notifications: boolean;
+    extended_agent_card: boolean;
+  };
+  default_input_modes: string[];
+  default_output_modes: string[];
+  skills: Array<{
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+  }>;
+}
+
+function buildAgentCard(baseUrl: string, assistantName: string): AgentCard {
+  return {
+    name: assistantName,
+    description: `${assistantName} — a Vellum AI assistant`,
+    version: "1.0.0",
+    supported_interfaces: [
+      {
+        url: `${baseUrl}/a2a/message:send`,
+        protocol_binding: "JSONRPC",
+        protocol_version: "1.0",
+      },
+    ],
+    capabilities: {
+      streaming: false,
+      push_notifications: true,
+      extended_agent_card: false,
+    },
+    default_input_modes: ["text/plain"],
+    default_output_modes: ["text/plain"],
+    skills: [
+      {
+        id: "conversation",
+        name: "General conversation",
+        description: "Send a message and receive a response",
+        tags: ["chat"],
+      },
+    ],
+  };
+}
+
+// ── Identity helpers ───────────────────────────────────────────────
+
+function readAssistantName(): string {
+  try {
+    const wsDir = getWorkspaceDir();
+    const identityPath = join(wsDir, "prompts", "IDENTITY.md");
+    if (!existsSync(identityPath)) return "Vellum Assistant";
+    const content = readFileSync(identityPath, "utf-8");
+    const match = content.match(/\*\*Name:\*\*\s*(.+)/);
+    return match?.[1]?.trim() || "Vellum Assistant";
+  } catch {
+    return "Vellum Assistant";
+  }
+}
+
+// ── Route handler factory ──────────────────────────────────────────
+
+export function createAgentCardHandler(configFile: ConfigFileCache) {
+  return async (_req: Request): Promise<Response> => {
+    const enabled = configFile.getBoolean("a2a", "enabled") ?? false;
+    if (!enabled) {
+      return Response.json(
+        { error: "A2A channel is not enabled" },
+        { status: 404 },
+      );
+    }
+
+    const publicBaseUrl =
+      configFile.getString("ingress", "publicBaseUrl") ?? "";
+    if (!publicBaseUrl) {
+      log.warn("Agent card requested but no public base URL configured");
+      return Response.json(
+        { error: "Public ingress URL not configured" },
+        { status: 503 },
+      );
+    }
+
+    const assistantName = readAssistantName();
+    const card = buildAgentCard(publicBaseUrl, assistantName);
+
+    return Response.json(card, {
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+}
+
+export { A2A_AGENT_CARD_PATH };

package/src/http/routes/twilio-voice-verify-callback.ts

@@ -78,14 +78,17 @@ export function createTwilioVoiceVerifyCallbackHandler(
         { callSid, fromNumber },
         "No pending verification session found on callback — forwarding to assistant",
       );
-      return forwardToAssistant(config, params, req.url, caches);
+      return forwardToAssistant(
+        config,
+        params,
+        req.url,
+        validation.validatedCandidateUrl,
+        caches,
+      );
     }
 
     if (!digits) {
-      log.info(
-        { callSid, fromNumber },
-        "No digits entered — re-prompting",
-      );
+      log.info({ callSid, fromNumber }, "No digits entered — re-prompting");
       const actionUrl = buildActionUrl(url, attempt);
       return twimlResponse(
         gatherVerificationTwiml(actionUrl, attempt, session.codeDigits ?? 6),
@@ -113,7 +116,11 @@ export function createTwilioVoiceVerifyCallbackHandler(
       const nextAttempt = attempt + 1;
       const actionUrl = buildActionUrl(url, nextAttempt);
       return twimlResponse(
-        gatherVerificationTwiml(actionUrl, nextAttempt, session.codeDigits ?? 6),
+        gatherVerificationTwiml(
+          actionUrl,
+          nextAttempt,
+          session.codeDigits ?? 6,
+        ),
       );
     }
 
@@ -147,7 +154,10 @@ export function createTwilioVoiceVerifyCallbackHandler(
         );
 
         const existingGuardian = existingPhoneGuardians[0];
-        if (existingGuardian && existingGuardian.externalUserId !== fromNumber) {
+        if (
+          existingGuardian &&
+          existingGuardian.externalUserId !== fromNumber
+        ) {
           log.warn(
             {
               callSid,
@@ -209,7 +219,13 @@ export function createTwilioVoiceVerifyCallbackHandler(
       { callSid, fromNumber },
       "Voice verification complete — forwarding to assistant for call setup",
     );
-    return forwardToAssistant(config, params, req.url, caches);
+    return forwardToAssistant(
+      config,
+      params,
+      req.url,
+      validation.validatedCandidateUrl,
+      caches,
+    );
   };
 }
 
@@ -248,13 +264,17 @@ async function revokeExistingPhoneGuardian(): Promise<void> {
   try {
     const gwDb = getGatewayDb();
     for (const id of ids) {
-      gwDb.update(gwContactChannels)
+      gwDb
+        .update(gwContactChannels)
         .set({ status: "revoked", policy: "deny", updatedAt: now })
         .where(eq(gwContactChannels.id, id))
         .run();
     }
   } catch (gwErr) {
-    log.warn({ err: gwErr }, "Gateway DB revoke dual-write failed (best-effort)");
+    log.warn(
+      { err: gwErr },
+      "Gateway DB revoke dual-write failed (best-effort)",
+    );
   }
 }
 
@@ -276,6 +296,7 @@ async function forwardToAssistant(
   config: GatewayConfig,
   params: Record<string, string>,
   originalUrl: string,
+  validatedPublicUrl?: string,
   caches?: TwilioValidationCaches,
 ): Promise<Response> {
   try {
@@ -288,7 +309,12 @@ async function forwardToAssistant(
       config,
       params,
       originalUrl,
-      resolvePublicBaseWssUrl(config, caches?.configFile, platformAssistantId),
+      resolvePublicBaseWssUrl(
+        config,
+        caches?.configFile,
+        platformAssistantId,
+        validatedPublicUrl,
+      ),
     );
     return new Response(runtimeResponse.body, {
       status: runtimeResponse.status,
@@ -304,7 +330,10 @@ async function forwardToAssistant(
         },
       );
     }
-    log.error({ err }, "Failed to forward voice webhook to runtime after verification");
+    log.error(
+      { err },
+      "Failed to forward voice webhook to runtime after verification",
+    );
     return Response.json({ error: "Internal server error" }, { status: 502 });
   }
 }

package/src/http/routes/twilio-voice-webhook.test.ts

@@ -352,6 +352,61 @@ describe("resolvePublicBaseWssUrl", () => {
     );
   });
 
+  test("uses assistant ID from validated platform callback URL with Velay", () => {
+    const config = {
+      ...baseConfig,
+      velayBaseUrl: "https://velay-staging.vellum.ai",
+    };
+    const result = resolvePublicBaseWssUrl(
+      config,
+      undefined,
+      undefined,
+      "https://staging-platform.vellum.ai/v1/gateway/callbacks/019e2d0d-f355-744c-a12c-d7e7dcefcf1e/webhooks/twilio/voice/?callSessionId=37b47ade-2eaf-469a-bede-6f2454875e6e",
+    );
+    expect(result).toBe(
+      "wss://velay-staging.vellum.ai/019e2d0d-f355-744c-a12c-d7e7dcefcf1e",
+    );
+  });
+
+  test("prefers validated platform callback URL over stale configFile publicBaseUrl", () => {
+    const config = {
+      ...baseConfig,
+      velayBaseUrl: "https://velay-staging.vellum.ai",
+    };
+    const mockConfigFile = {
+      getString: (section: string, key: string) =>
+        section === "ingress" && key === "publicBaseUrl"
+          ? "https://stale-tunnel.example.test"
+          : undefined,
+    } as Parameters<typeof resolvePublicBaseWssUrl>[1];
+    const result = resolvePublicBaseWssUrl(
+      config,
+      mockConfigFile,
+      undefined,
+      "https://staging-platform.vellum.ai/v1/gateway/callbacks/019e2d0d-f355-744c-a12c-d7e7dcefcf1e/webhooks/twilio/voice?callSessionId=sess-1",
+    );
+    expect(result).toBe(
+      "wss://velay-staging.vellum.ai/019e2d0d-f355-744c-a12c-d7e7dcefcf1e",
+    );
+  });
+
+  test("does not use a platform callback URL as the websocket base", () => {
+    const config = {
+      ...baseConfig,
+      velayBaseUrl: "https://velay-staging.vellum.ai",
+    };
+    const mockConfigFile = {
+      getString: (section: string, key: string) =>
+        section === "ingress" && key === "publicBaseUrl"
+          ? "https://staging-platform.vellum.ai/v1/gateway/callbacks/019e2d0d-f355-744c-a12c-d7e7dcefcf1e"
+          : undefined,
+    } as Parameters<typeof resolvePublicBaseWssUrl>[1];
+    const result = resolvePublicBaseWssUrl(config, mockConfigFile, undefined);
+    expect(result).toBe(
+      "wss://velay-staging.vellum.ai/019e2d0d-f355-744c-a12c-d7e7dcefcf1e",
+    );
+  });
+
   test("strips trailing slash from velayBaseUrl before joining assistant ID", () => {
     const config = {
       ...baseConfig,

package/src/http/routes/twilio-voice-webhook.ts

@@ -151,7 +151,10 @@ export function createTwilioVoiceWebhookHandler(
           // The display name is intentionally included: the caller registered
           // this number themselves, so disclosing their own name is expected.
           const unverifiedStatuses = new Set(["unverified", "pending"]);
-          if (callerRecord && unverifiedStatuses.has(callerRecord.channel.status)) {
+          if (
+            callerRecord &&
+            unverifiedStatuses.has(callerRecord.channel.status)
+          ) {
             const isGuardian = callerRecord.contact.role === "guardian";
             log.info(
               {
@@ -197,7 +200,12 @@ export function createTwilioVoiceWebhookHandler(
         config,
         params,
         req.url,
-        resolvePublicBaseWssUrl(config, caches?.configFile, platformAssistantId),
+        resolvePublicBaseWssUrl(
+          config,
+          caches?.configFile,
+          platformAssistantId,
+          validation.validatedCandidateUrl,
+        ),
       );
       return new Response(runtimeResponse.body, {
         status: runtimeResponse.status,

package/src/index.ts

@@ -118,6 +118,10 @@ import { createWorkspaceCommitProxyHandler } from "./http/routes/workspace-commi
 import { createBrainGraphProxyHandler } from "./http/routes/brain-graph-proxy.js";
 import { createLogExportHandler } from "./http/routes/log-export.js";
 import { createLogTailHandler } from "./http/routes/log-tail.js";
+import {
+  createAgentCardHandler,
+  A2A_AGENT_CARD_PATH,
+} from "./http/routes/a2a-routes.js";
 import {
   createTrustRulesListHandler,
   createTrustRulesCreateHandler,
@@ -172,6 +176,7 @@ import {
 import { GatewayIpcServer } from "./ipc/server.js";
 import { contactRoutes } from "./ipc/contact-handlers.js";
 import { featureFlagRoutes } from "./ipc/feature-flag-handlers.js";
+import { slackThreadRoutes } from "./ipc/slack-thread-handlers.js";
 import { thresholdRoutes } from "./ipc/threshold-handlers.js";
 
 import { riskClassificationRoutes } from "./ipc/risk-classification-handlers.js";
@@ -467,6 +472,8 @@ async function main() {
   const handleTrustRulesReset = createTrustRulesResetHandler();
   const handleTrustRulesSuggest = createTrustRulesSuggestHandler();
 
+  const handleAgentCard = createAgentCardHandler(configFileCache);
+
   const audioProxy = createAudioProxyHandler(config);
 
   const backupDeps = {
@@ -505,6 +512,13 @@ async function main() {
   // Auth middleware is applied declaratively per route — no manual
   // requireEdgeAuth/wrapWithAuthFailureTracking calls needed.
   const routes: RouteDefinition[] = [
+    // ── A2A agent card discovery (read-only, unauthenticated per spec) ──
+    {
+      path: A2A_AGENT_CARD_PATH,
+      method: "GET",
+      handler: (req) => handleAgentCard(req),
+    },
+
     // ── Webhooks (unauthenticated, validated by provider-specific mechanisms) ──
     {
       path: "/webhooks/telegram",
@@ -2104,6 +2118,7 @@ async function main() {
     // Fires on initial credential load and whenever vellum credentials change
     // (key rotation, late provisioning).
     if (changed.has("vellum")) {
+      velayTunnelClient?.refreshCredentials("vellum credentials changed");
       registerEmailCallbackRoute({
         credentials: credentialCache,
         configFile: configFileCache,
@@ -2191,6 +2206,7 @@ async function main() {
   const ipcServer = new GatewayIpcServer([
     ...featureFlagRoutes,
     ...contactRoutes,
+    ...slackThreadRoutes,
     ...thresholdRoutes,
     ...riskClassificationRoutes,
     ...createVelayRoutes(velayTunnelClient),

package/src/ipc/slack-thread-handlers.ts

@@ -0,0 +1,39 @@
+/**
+ * IPC route definitions for Slack active-thread listener control.
+ *
+ * The gateway owns Slack Socket Mode listener state, so assistant-side
+ * controls call here instead of writing gateway storage directly.
+ */
+
+import { z } from "zod";
+
+import { SlackStore } from "../db/slack-store.js";
+import type { IpcRoute } from "./server.js";
+
+let store: SlackStore | null = null;
+
+function getStore(): SlackStore {
+  if (!store) {
+    store = new SlackStore();
+  }
+  return store;
+}
+
+const DetachSlackActiveThreadParamsSchema = z.object({
+  channelId: z.string().trim().min(1),
+  threadTs: z.string().trim().min(1),
+});
+
+export const slackThreadRoutes: IpcRoute[] = [
+  {
+    method: "detach_slack_active_thread",
+    schema: DetachSlackActiveThreadParamsSchema,
+    handler: (params?: Record<string, unknown>) => {
+      const { channelId, threadTs } = DetachSlackActiveThreadParamsSchema.parse(
+        params ?? {},
+      );
+      const detached = getStore().detachThread(threadTs, channelId);
+      return { detached, channelId, threadTs };
+    },
+  },
+];

package/src/risk/bash-risk-classifier.test.ts

@@ -1035,6 +1035,30 @@ describe("assistant subcommand classification", () => {
     expect(result.riskLevel).toBe("low");
   });
 
+  test("assistant schedules enable → medium", async () => {
+    const result = await classifier.classify({
+      command: "assistant schedules enable schedule-1",
+      toolName: "bash",
+    });
+    expect(result.riskLevel).toBe("medium");
+  });
+
+  test("assistant schedules disable → medium", async () => {
+    const result = await classifier.classify({
+      command: "assistant schedules disable schedule-1",
+      toolName: "bash",
+    });
+    expect(result.riskLevel).toBe("medium");
+  });
+
+  test("assistant schedules cancel → medium", async () => {
+    const result = await classifier.classify({
+      command: "assistant schedules cancel schedule-1",
+      toolName: "bash",
+    });
+    expect(result.riskLevel).toBe("medium");
+  });
+
   test("assistant schedules execute → medium", async () => {
     const result = await classifier.classify({
       command: "assistant schedules execute schedule-1",

package/src/risk/command-registry/commands/assistant.ts

@@ -192,6 +192,11 @@ const ASSISTANT_SUPPORTED_COMMAND_PATHS = [
   "schedules",
   "schedules list",
   "schedules runs",
+  "schedules create",
+  "schedules enable",
+  "schedules disable",
+  "schedules cancel",
+  "schedules delete",
   "schedules execute",
   "sequence",
   "sequence list",
@@ -261,6 +266,7 @@ const ASSISTANT_SUPPORTED_COMMAND_PATHS = [
   "plugins",
   "plugins install",
   "plugins list",
+  "plugins search",
   "plugins uninstall",
 ] as const;
 
@@ -499,6 +505,33 @@ const riskOverrides: AssistantRiskOverride[] = [
   { path: "platform connect", risk: "low" },
   { path: "platform disconnect", risk: "medium" },
   { path: "platform callback-routes register", risk: "low" },
+  {
+    path: "schedules create",
+    risk: "medium",
+    reason:
+      "Creates a new recurring schedule that fires assistant-side messages",
+  },
+  {
+    path: "schedules enable",
+    risk: "medium",
+    reason: "Enables a schedule and mutates assistant schedule state",
+  },
+  {
+    path: "schedules disable",
+    risk: "medium",
+    reason: "Disables a schedule and mutates assistant schedule state",
+  },
+  {
+    path: "schedules cancel",
+    risk: "medium",
+    reason: "Cancels a pending schedule and mutates assistant schedule state",
+  },
+  {
+    path: "schedules delete",
+    risk: "medium",
+    reason:
+      "Permanently removes a schedule and its run history from assistant state",
+  },
   {
     path: "schedules execute",
     risk: "medium",

package/src/risk/command-registry.test.ts

@@ -599,6 +599,11 @@ describe("command-registry", () => {
       expect(getAssistantPath("inference session list").baseRisk).toBe("low");
       expect(getAssistantPath("schedules list").baseRisk).toBe("low");
       expect(getAssistantPath("schedules runs").baseRisk).toBe("low");
+      expect(getAssistantPath("schedules create").baseRisk).toBe("medium");
+      expect(getAssistantPath("schedules enable").baseRisk).toBe("medium");
+      expect(getAssistantPath("schedules disable").baseRisk).toBe("medium");
+      expect(getAssistantPath("schedules cancel").baseRisk).toBe("medium");
+      expect(getAssistantPath("schedules delete").baseRisk).toBe("medium");
       expect(getAssistantPath("schedules execute").baseRisk).toBe("medium");
     });
   });