@vellumai/assistant 0.11.0-staging.2 → 0.11.0

package/docs/architecture/memory.md

@@ -123,6 +123,13 @@ build can never drift. The same predicate gates procedural-memory-as-skills,
 so both v3-tier features honor the Memory opt-out identically. `GET /v1/memory-graph-node` serves node detail,
 including `buffer:` ids for pending entries.
 
+`GET /v1/memory/stats` also reports `tier` (`memoryTier()`: `off` / `v1` /
+`v2` / `v3`), which is what lets the web Memory tab explain an unavailable
+graph instead of stating a bare "not available": `off` is the user's own
+Memory opt-out and points at Settings, while `v1`/`v2` point at the v3
+migration. `graph_supported` is exactly `tier === "v3"`, so the capability
+bit and its explanation are derived from one gate.
+
 ## Capture beyond `remember`
 
 - **Retrospective** (`memory-retrospective-*.ts`): periodic per-conversation

package/openapi.yaml

@@ -17747,7 +17747,9 @@ paths:
         "Return a cheap count of concept pages from the cached memory page index, for glanceable surfaces like the
         identity Memory card. Counts concept pages only and never builds the memory-concept graph. Also reports
         graph_supported: whether the memory-concept graph is available for this assistant (memory enabled and v3 live),
-        so callers can gate the graph entry point without building the graph."
+        so callers can gate the graph entry point without building the graph, plus tier: the coarse memory tier
+        explaining why the graph is unavailable (off = the user's Memory opt-out, v1/v2 = a legacy engine that has not
+        migrated to v3)."
       tags:
         - memory
       responses:
@@ -17764,9 +17766,18 @@ paths:
                   graph_supported:
                     type: boolean
                     description: Whether the memory-concept graph is available (memory enabled and v3 live)
+                  tier:
+                    type: string
+                    enum:
+                      - off
+                      - v1
+                      - v2
+                      - v3
+                    description: Coarse memory tier for this assistant; graph_supported is exactly tier === 'v3'
                 required:
                   - concepts
                   - graph_supported
+                  - tier
                 additionalProperties: false
   /v1/memory/v2/backfill:
     post:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.0-staging.2",
+  "version": "0.11.0",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/channel-readiness-service.test.ts

@@ -6,6 +6,8 @@ import { setConfig } from "./helpers/set-config.js";
 let mockSecureKeys: Record<string, string>;
 let mockHasTwilioCredentials: boolean;
 let mockGetIsPlatform: boolean;
+/** Platform credentials present: base URL + assistant ID + assistant API key. */
+let mockPlatformConnected: boolean;
 
 mock.module("../calls/twilio-rest.js", () => ({
   getPhoneNumberSid: async () => null,
@@ -24,7 +26,22 @@ mock.module("../config/env-registry.js", () => ({
   getIsPlatform: () => mockGetIsPlatform,
 }));
 
-mock.module("../inbound/platform-callback-registration.js", () => ({}));
+// Spread the real module: replacing it wholesale drops the exports peer test
+// files import from it, which breaks their named-import validation whenever
+// this mock wins evaluation in a combined run.
+const actualRegistration =
+  await import("../inbound/platform-callback-registration.js");
+mock.module("../inbound/platform-callback-registration.js", () => ({
+  ...actualRegistration,
+  resolvePlatformCallbackRegistrationContext: async () => ({
+    isPlatform: mockGetIsPlatform,
+    platformBaseUrl: "https://api.vellum.ai",
+    assistantId: mockPlatformConnected ? "assistant-123" : "",
+    hasAssistantApiKey: mockPlatformConnected,
+    authHeader: mockPlatformConnected ? "Api-Key secret" : null,
+    enabled: mockPlatformConnected,
+  }),
+}));
 
 mock.module("../security/secure-keys.js", () => ({
   getSecureKeyAsync: async (key: string) => mockSecureKeys[key] ?? null,
@@ -85,6 +102,7 @@ describe("ChannelReadinessService", () => {
     mockSecureKeys = {};
     mockHasTwilioCredentials = false;
     mockGetIsPlatform = false;
+    mockPlatformConnected = false;
   });
 
   test("local checks run on every call (no caching of local results)", async () => {
@@ -278,6 +296,94 @@ describe("ChannelReadinessService", () => {
     });
   });
 
+  test("telegram readiness accepts a platform-connected assistant with no ingress", async () => {
+    // LUM-2882: `webhooks register telegram` resolves a platform callback URL
+    // in this configuration, so reporting missing ingress here would hide a
+    // registration that is really in place (or really broken).
+    mockPlatformConnected = true;
+    mockSecureKeys[credentialKey("telegram", "bot_token")] = "123:abc";
+    mockSecureKeys[credentialKey("telegram", "webhook_secret")] = "secret";
+
+    const readiness = createReadinessService();
+    const [snapshot] = await readiness.getReadiness("telegram");
+
+    expect(snapshot.ready).toBe(true);
+    expect(snapshot.localChecks).toContainEqual({
+      name: "ingress",
+      passed: true,
+      message: "Managed platform callback routing is configured",
+    });
+  });
+
+  test("phone readiness accepts a platform-connected assistant with no ingress", async () => {
+    mockPlatformConnected = true;
+    mockHasTwilioCredentials = true;
+    setConfig("twilio", { phoneNumber: "+15550123" });
+
+    const readiness = createReadinessService();
+    const [snapshot] = await readiness.getReadiness("phone");
+
+    expect(snapshot.ready).toBe(true);
+    expect(snapshot.localChecks).toContainEqual({
+      name: "ingress",
+      passed: true,
+      message: "Managed platform callback routing is configured",
+    });
+  });
+
+  test("configured ingress beats the platform-connected fallback", async () => {
+    // Any logged-in local assistant holds platform credentials for the LLM
+    // proxy. Reporting managed routing here would mislabel a webhook that
+    // `webhooks register` resolves to the self-hosted URL.
+    mockPlatformConnected = true;
+    mockSecureKeys[credentialKey("telegram", "bot_token")] = "123:abc";
+    mockSecureKeys[credentialKey("telegram", "webhook_secret")] = "secret";
+    setConfig("ingress", { publicBaseUrl: "https://tunnel.example.com" });
+
+    const readiness = createReadinessService();
+    const [snapshot] = await readiness.getReadiness("telegram");
+
+    expect(snapshot.ready).toBe(true);
+    expect(snapshot.localChecks).toContainEqual({
+      name: "ingress",
+      passed: true,
+      message: "Public ingress URL is configured",
+    });
+  });
+
+  test("explicit ingress opt-out blocks the platform-connected fallback", async () => {
+    // Switching ingress off is a decision not to accept inbound webhooks, not
+    // an invitation to route them through the platform instead.
+    mockPlatformConnected = true;
+    mockSecureKeys[credentialKey("telegram", "bot_token")] = "123:abc";
+    mockSecureKeys[credentialKey("telegram", "webhook_secret")] = "secret";
+    setConfig("ingress", { enabled: false });
+
+    const readiness = createReadinessService();
+    const [snapshot] = await readiness.getReadiness("telegram");
+
+    expect(snapshot.ready).toBe(false);
+    expect(snapshot.reasons).toContainEqual({
+      code: "ingress",
+      text: "No public ingress URL or managed callback route is configured",
+    });
+  });
+
+  test("email readiness ignores platform connectivity", async () => {
+    // Email passes `allowManagedCallbacks: false`, so the managed tiers are
+    // not offered to it and only a real ingress URL counts.
+    mockPlatformConnected = true;
+
+    const readiness = createReadinessService();
+    const [snapshot] = await readiness.getReadiness("email");
+
+    expect(snapshot.localChecks).toContainEqual({
+      name: "ingress",
+      passed: false,
+      message: "Public ingress URL is not configured or disabled",
+    });
+  });
+
   test("phone readiness accepts configured public ingress", async () => {
     mockHasTwilioCredentials = true;
     setConfig("twilio", { phoneNumber: "+15550123" });

package/src/__tests__/platform-callback-registration.test.ts

@@ -33,8 +33,14 @@ mock.module("../security/secure-keys.js", () => ({
 const originalFetch = globalThis.fetch;
 const originalEnvCredential = process.env.ASSISTANT_API_KEY;
 
-const { registerCallbackRoute, resolvePlatformCallbackRegistrationContext } =
-  await import("../inbound/platform-callback-registration.js");
+const {
+  registerCallbackRoute,
+  resolveCallbackUrl,
+  resolvePlatformCallbackRegistrationContext,
+} = await import("../inbound/platform-callback-registration.js");
+
+const { PublicIngressDisabledError } =
+  await import("../inbound/public-ingress-urls.js");
 
 describe("platform callback registration", () => {
   beforeEach(() => {
@@ -150,3 +156,127 @@ describe("platform callback registration", () => {
     ).resolves.toBe("https://platform.example.com/v1/gateway/callbacks/x/");
   });
 });
+
+/**
+ * `resolveCallbackUrl` drives Twilio voice/status callbacks and OAuth redirect
+ * URIs. Its tier order has to match `handleWebhooksRegister` in
+ * `runtime/routes/webhook-routes.ts` and `hasWebhookRoutingConfigured` in
+ * `config/webhook-routing.ts` (LUM-2882).
+ */
+describe("resolveCallbackUrl resolution order", () => {
+  const PLATFORM_URL = "https://platform.example.com/v1/gateway/callbacks/x/";
+
+  /** Stand in for a URL builder that cannot resolve a public ingress URL. */
+  function noIngress(): string {
+    throw new Error(
+      "No public base URL configured. Set ingress.publicBaseUrl in config.",
+    );
+  }
+
+  /** Stand in for a URL builder reached while ingress is switched off. */
+  function ingressDisabled(): string {
+    throw new PublicIngressDisabledError();
+  }
+
+  function seedPlatformCredentials(): void {
+    mockSecureKeys[credentialKey("vellum", "platform_base_url")] =
+      "https://platform.example.com";
+    mockSecureKeys[credentialKey("vellum", "platform_assistant_id")] =
+      "11111111-2222-4333-8444-555555555555";
+    mockSecureKeys[credentialKey("vellum", "assistant_api_key")] =
+      "ast-managed-key";
+  }
+
+  let registerCalls: number;
+
+  beforeEach(() => {
+    mockIsPlatform = false;
+    mockPlatformBaseUrl = "";
+    mockPlatformAssistantId = "";
+    mockSecureKeys = {};
+    delete process.env.ASSISTANT_API_KEY;
+    registerCalls = 0;
+    globalThis.fetch = mock(async () => {
+      registerCalls++;
+      return new Response(
+        JSON.stringify({
+          callback_url: PLATFORM_URL,
+          callback_path: "webhooks/twilio/voice",
+          type: "twilio_voice",
+          assistant_id: "11111111-2222-4333-8444-555555555555",
+        }),
+        { status: 201, headers: { "content-type": "application/json" } },
+      );
+    }) as unknown as typeof fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test("platform pods register with the platform gateway", async () => {
+    mockIsPlatform = true;
+    seedPlatformCredentials();
+
+    // The direct supplier is never evaluated on a pod: there is no ingress of
+    // its own to advertise, and evaluating it would throw.
+    await expect(
+      resolveCallbackUrl(noIngress, "webhooks/twilio/voice", "twilio_voice"),
+    ).resolves.toBe(PLATFORM_URL);
+    expect(registerCalls).toBe(1);
+  });
+
+  test("a configured ingress wins over platform connectivity", async () => {
+    seedPlatformCredentials();
+
+    await expect(
+      resolveCallbackUrl(
+        () => "https://tunnel.example.com/webhooks/twilio/voice",
+        "webhooks/twilio/voice",
+        "twilio_voice",
+      ),
+    ).resolves.toBe("https://tunnel.example.com/webhooks/twilio/voice");
+    expect(registerCalls).toBe(0);
+  });
+
+  test("a platform-connected assistant with no ingress registers with the platform", async () => {
+    // LUM-2882: this used to return the direct builder's throw because the
+    // platform branch was gated on IS_PLATFORM, which is only true on a pod.
+    seedPlatformCredentials();
+
+    await expect(
+      resolveCallbackUrl(noIngress, "webhooks/twilio/voice", "twilio_voice"),
+    ).resolves.toBe(PLATFORM_URL);
+    expect(registerCalls).toBe(1);
+  });
+
+  test("query parameters are appended to the platform URL", async () => {
+    seedPlatformCredentials();
+
+    await expect(
+      resolveCallbackUrl(noIngress, "webhooks/twilio/voice", "twilio_voice", {
+        callSessionId: "conv-xyz",
+      }),
+    ).resolves.toBe(`${PLATFORM_URL}?callSessionId=conv-xyz`);
+  });
+
+  test("an explicit ingress opt-out is not routed around", async () => {
+    seedPlatformCredentials();
+
+    await expect(
+      resolveCallbackUrl(
+        ingressDisabled,
+        "webhooks/twilio/voice",
+        "twilio_voice",
+      ),
+    ).rejects.toThrow("Public ingress is disabled");
+    expect(registerCalls).toBe(0);
+  });
+
+  test("without platform credentials the ingress error surfaces unchanged", async () => {
+    await expect(
+      resolveCallbackUrl(noIngress, "webhooks/twilio/voice", "twilio_voice"),
+    ).rejects.toThrow("No public base URL configured");
+    expect(registerCalls).toBe(0);
+  });
+});

package/src/__tests__/plugin-import-boundary-guard.test.ts

@@ -103,6 +103,12 @@ const BASELINE: Record<string, readonly string[]> = {
     "../../../../config/assistant-feature-flags.js",
     "../../../../config/default-profile-catalog.js",
     "../../../../config/loader.js",
+    // Sibling of the already-sanctioned memory-v3-gate: `memoryTier()` is
+    // defined as fully derived from that module's predicates, and the stats
+    // route reports both (`graph_supported` is exactly `tier === "v3"`).
+    // Re-deriving the tier inside the plugin would reintroduce exactly the
+    // drift the shared module exists to prevent. No plugin-api equivalent.
+    "../../../../config/memory-tier.js",
     "../../../../config/memory-v3-gate.js",
     "../../../../config/schema.js",
     "../../../../config/schemas/memory-v2.js",

package/src/__tests__/telegram-config.test.ts

@@ -1,5 +1,11 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
+import {
+  invalidateConfigCache,
+  loadRawConfig,
+  saveRawConfig,
+  setNestedValue,
+} from "../config/loader.js";
 import { credentialKey } from "../security/credential-key.js";
 
 let secureKeyStore: Record<string, string> = {};
@@ -8,9 +14,28 @@ let oauthConnectionStore: Record<
   { id: string; status: string; accountInfo?: string | null }
 > = {};
 const syncCalls: Array<{ provider: string; accountInfo?: string }> = [];
+let platformContextEnabled = false;
 
+const registerCallbackRouteMock = mock(
+  async (callbackPath: string, _type: string) =>
+    `https://gateway.vellum.ai/assistant-123/${callbackPath}`,
+);
+
+// Spread the real module: it is a shared barrel and replacing it wholesale
+// breaks unrelated importers pulled in by the module under test.
+const actualPlatformCallbackRegistration =
+  await import("../inbound/platform-callback-registration.js");
 mock.module("../inbound/platform-callback-registration.js", () => ({
-  registerCallbackRoute: async () => {},
+  ...actualPlatformCallbackRegistration,
+  registerCallbackRoute: registerCallbackRouteMock,
+  resolvePlatformCallbackRegistrationContext: async () => ({
+    isPlatform: false,
+    platformBaseUrl: platformContextEnabled ? "https://api.vellum.ai" : "",
+    assistantId: platformContextEnabled ? "assistant-123" : "",
+    hasAssistantApiKey: platformContextEnabled,
+    authHeader: platformContextEnabled ? "Api-Key secret" : null,
+    enabled: platformContextEnabled,
+  }),
 }));
 
 mock.module("../daemon/handlers/shared.js", () => ({
@@ -77,13 +102,37 @@ mock.module("../tools/credentials/metadata-store.js", () => ({
 
 const originalFetch = globalThis.fetch;
 
-import { getTelegramConfig } from "../daemon/handlers/config-telegram.js";
+const { getTelegramConfig, setTelegramConfig } =
+  await import("../daemon/handlers/config-telegram.js");
+
+function mockTelegramApi(): typeof fetch {
+  return (async (input: RequestInfo | URL) => {
+    const url = String(input);
+    if (url.includes("/getMe")) {
+      return new Response(
+        JSON.stringify({ ok: true, result: { id: 42, username: "testbot" } }),
+        { status: 200 },
+      );
+    }
+    return new Response(JSON.stringify({ ok: true }), { status: 200 });
+  }) as typeof fetch;
+}
+
+function setIngressPublicBaseUrl(url: string): void {
+  const raw = loadRawConfig();
+  setNestedValue(raw, "ingress.publicBaseUrl", url);
+  saveRawConfig(raw);
+  invalidateConfigCache();
+}
 
 describe("Telegram config handler", () => {
   beforeEach(() => {
     secureKeyStore = {};
     oauthConnectionStore = {};
     syncCalls.length = 0;
+    platformContextEnabled = false;
+    registerCallbackRouteMock.mockClear();
+    setIngressPublicBaseUrl("");
     globalThis.fetch = originalFetch;
   });
 
@@ -105,4 +154,49 @@ describe("Telegram config handler", () => {
     ]);
     expect(oauthConnectionStore["telegram"]?.accountInfo).toBe("@testbot");
   });
+
+  // A platform-connected local assistant (IS_PLATFORM unset, valid platform
+  // credentials, no public ingress) receives Telegram webhooks only through
+  // managed platform callbacks, so saving the bot token must register the
+  // route.
+  test("set registers the platform callback route for a platform-connected local assistant", async () => {
+    platformContextEnabled = true;
+    globalThis.fetch = mockTelegramApi();
+
+    const result = await setTelegramConfig(
+      "123456789:AAtesttoken_testtoken_testtoken_test",
+    );
+
+    expect(result.success).toBe(true);
+    expect(registerCallbackRouteMock).toHaveBeenCalledWith(
+      "webhooks/telegram",
+      "telegram",
+    );
+  });
+
+  test("set does not register a platform callback route when not platform-connected", async () => {
+    globalThis.fetch = mockTelegramApi();
+
+    const result = await setTelegramConfig(
+      "123456789:AAtesttoken_testtoken_testtoken_test",
+    );
+
+    expect(result.success).toBe(true);
+    expect(registerCallbackRouteMock).not.toHaveBeenCalled();
+  });
+
+  // A logged-in local assistant holds platform credentials for the LLM proxy,
+  // so credential presence must not override an explicitly configured ingress.
+  test("set does not register a platform callback route when a public ingress is configured", async () => {
+    platformContextEnabled = true;
+    setIngressPublicBaseUrl("https://abc.ngrok.io");
+    globalThis.fetch = mockTelegramApi();
+
+    const result = await setTelegramConfig(
+      "123456789:AAtesttoken_testtoken_testtoken_test",
+    );
+
+    expect(result.success).toBe(true);
+    expect(registerCallbackRouteMock).not.toHaveBeenCalled();
+  });
 });