@vellumai/assistant 0.11.0-staging.1 → 0.11.0-staging.3

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:
@@ -29334,7 +29345,9 @@ paths:
           required: false
           schema:
             type: string
-          description: Parent conversation ID (required)
+          description:
+            The subagent's own conversation ID. Fallback only — when the daemon knows the subagent (live or
+            rehydrated), it resolves the conversation itself and this parameter is ignored.
       responses:
         "200":
           description: Successful response
@@ -29397,6 +29410,10 @@ paths:
                         - type
                         - content
                       additionalProperties: false
+                  label:
+                    type: string
+                  parentToolUseId:
+                    type: string
                 required:
                   - subagentId
                   - events
@@ -29489,8 +29506,9 @@ paths:
       operationId: subagents_reconcile_get
       summary: Reconcile subagent live status
       description:
-        Returns the live in-memory status of all subagents known to the daemon for a given parent conversation.
-        Subagents not in the response are orphaned.
+        Returns the live in-memory status of all subagents known to the daemon for a given parent conversation,
+        with the identity fields a client needs to rebuild a store entry it never saw spawn (label, the subagent's own
+        conversation id, and the spawning tool-use id). Subagents not in the response are orphaned.
       tags:
         - subagents
       parameters:
@@ -29517,6 +29535,12 @@ paths:
                       properties:
                         status:
                           type: string
+                        label:
+                          type: string
+                        conversationId:
+                          type: string
+                        parentToolUseId:
+                          type: string
                       required:
                         - status
                       additionalProperties: false
@@ -31536,7 +31560,8 @@ paths:
       summary: Register a webhook callback URL
       description:
         Resolves a stable callback URL for a webhook type. On platform-managed assistants, registers the route with
-        the platform gateway. On self-hosted assistants, uses the configured ingress.publicBaseUrl.
+        the platform gateway. Otherwise uses the configured ingress.publicBaseUrl, falling back to the platform gateway
+        when no ingress is configured and the assistant is connected to the platform.
       tags:
         - webhooks
       requestBody:

package/package.json

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

package/src/__tests__/app-conversation-ids-backfill.test.ts

@@ -11,6 +11,7 @@ import {
 } from "../apps/app-store.js";
 import { getDb } from "../persistence/db-connection.js";
 import { initializeDb } from "../persistence/db-init.js";
+import { migrateBackfillAppConversationLineage } from "../persistence/migrations/354-backfill-app-conversation-lineage.js";
 import { rawRun } from "../persistence/raw-query.js";
 
 // Initialize db once for all tests
@@ -57,15 +58,18 @@ function insertMessage(
 }
 
 /** Insert a conversation row so FK constraints are satisfied. */
-function insertConversation(id: string): void {
+function insertConversation(id: string, parentConversationId?: string): void {
   const now = Date.now();
   rawRun(
     "test:insertConversation",
-    `INSERT OR IGNORE INTO conversations (id, title, created_at, updated_at) VALUES (?, ?, ?, ?)`,
+    `INSERT OR IGNORE INTO conversations (
+      id, title, created_at, updated_at, parent_conversation_id
+    ) VALUES (?, ?, ?, ?, ?)`,
     id,
     "test",
     now,
     now,
+    parentConversationId ?? null,
   );
 }
 
@@ -272,3 +276,30 @@ describe("backfillAppConversationIds", () => {
     expect(loaded?.conversationIds).toEqual([existingConvId, backfillConvId]);
   });
 });
+
+describe("migrateBackfillAppConversationLineage", () => {
+  test("adds inherited ancestors to existing direct app associations", () => {
+    const app = createApp(makeAppParams("Lineage App"));
+    const rootConversationId = "conv-lineage-root";
+    const parentConversationId = "conv-lineage-parent";
+    const childConversationId = "conv-lineage-child";
+    insertConversation(rootConversationId);
+    insertConversation(parentConversationId, rootConversationId);
+    insertConversation(childConversationId, parentConversationId);
+    addAppConversationId(app.id, childConversationId);
+
+    migrateBackfillAppConversationLineage();
+    migrateBackfillAppConversationLineage();
+
+    const loaded = getApp(app.id);
+    expect(loaded?.conversationIds).toEqual([
+      childConversationId,
+      parentConversationId,
+      rootConversationId,
+    ]);
+    expect(loaded?.inheritedConversationIds).toEqual([
+      parentConversationId,
+      rootConversationId,
+    ]);
+  });
+});

package/src/__tests__/app-conversation-ids.test.ts

@@ -7,8 +7,16 @@ import {
   addAppConversationId,
   createApp,
   getApp,
+  isDirectAppConversation,
+  linkAppToConversationLineage,
   listAppsByConversation,
 } from "../apps/app-store.js";
+import {
+  deleteConversation,
+  removeSubagentConversation,
+  setConversation,
+  setSubagentConversation,
+} from "../daemon/conversation-registry.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -16,6 +24,41 @@ import {
 
 let testDataDir: string;
 
+/**
+ * The registry stores live `Conversation` instances; lineage resolution only
+ * reads `parentConversationId`, so a minimal stand-in is enough.
+ */
+type RegistryConversation = Parameters<typeof setConversation>[1];
+
+const registeredTopLevel: string[] = [];
+const registeredSubagents: [string, RegistryConversation][] = [];
+
+function stubConversation(parentConversationId?: string): RegistryConversation {
+  return { parentConversationId } as unknown as RegistryConversation;
+}
+
+/** Register a resident top-level conversation, optionally forked from a parent. */
+function registerConversation(id: string, parentId?: string): void {
+  setConversation(id, stubConversation(parentId));
+  registeredTopLevel.push(id);
+}
+
+/** Register a live subagent conversation forked from `parentId`. */
+function registerSubagent(id: string, parentId: string): void {
+  const conversation = stubConversation(parentId);
+  setSubagentConversation(id, conversation);
+  registeredSubagents.push([id, conversation]);
+}
+
+function clearRegisteredConversations(): void {
+  for (const id of registeredTopLevel.splice(0)) {
+    deleteConversation(id);
+  }
+  for (const [id, conversation] of registeredSubagents.splice(0)) {
+    removeSubagentConversation(id, conversation);
+  }
+}
+
 function freshTempDir(): string {
   return join(
     tmpdir(),
@@ -41,6 +84,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
+  clearRegisteredConversations();
   if (existsSync(testDataDir)) {
     rmSync(testDataDir, { recursive: true, force: true });
   }
@@ -149,3 +193,163 @@ describe("listAppsByConversation", () => {
     expect(result).toEqual([]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// linkAppToConversationLineage
+// ---------------------------------------------------------------------------
+
+describe("linkAppToConversationLineage", () => {
+  test("an app created in a forked conversation carries the fork and its parent", () => {
+    registerConversation("conv-visible");
+    registerSubagent("conv-fork", "conv-visible");
+
+    const app = createApp(makeAppParams("Continuation App"));
+    linkAppToConversationLineage(app.id, "conv-fork");
+
+    expect(getApp(app.id)?.conversationIds).toEqual([
+      "conv-fork",
+      "conv-visible",
+    ]);
+  });
+
+  test("the user-visible ancestor lists an app created by a background subagent", () => {
+    registerConversation("conv-visible");
+    registerSubagent("conv-fork", "conv-visible");
+
+    const app = createApp(makeAppParams("Continuation App"));
+    linkAppToConversationLineage(app.id, "conv-fork");
+
+    const visible = listAppsByConversation("conv-visible");
+    expect(visible).toHaveLength(1);
+    expect(visible[0].id).toBe(app.id);
+  });
+
+  test("walks nested subagents up to the user-visible thread", () => {
+    registerConversation("conv-visible");
+    registerSubagent("conv-outer", "conv-visible");
+    registerSubagent("conv-inner", "conv-outer");
+
+    const app = createApp(makeAppParams("Nested App"));
+    linkAppToConversationLineage(app.id, "conv-inner");
+
+    expect(getApp(app.id)?.conversationIds).toEqual([
+      "conv-inner",
+      "conv-outer",
+      "conv-visible",
+    ]);
+  });
+
+  test("re-linking the same lineage is idempotent", () => {
+    registerConversation("conv-visible");
+    registerSubagent("conv-fork", "conv-visible");
+
+    const app = createApp(makeAppParams("Repeat App"));
+    linkAppToConversationLineage(app.id, "conv-fork");
+    linkAppToConversationLineage(app.id, "conv-fork");
+
+    expect(getApp(app.id)?.conversationIds).toEqual([
+      "conv-fork",
+      "conv-visible",
+    ]);
+  });
+
+  test("a lineage of one behaves exactly like addAppConversationId", () => {
+    registerConversation("conv-plain");
+
+    const linked = createApp(makeAppParams("Linked App"));
+    const direct = createApp(makeAppParams("Direct App"));
+    linkAppToConversationLineage(linked.id, "conv-plain");
+    addAppConversationId(direct.id, "conv-plain");
+
+    expect(getApp(linked.id)?.conversationIds).toEqual(["conv-plain"]);
+    expect(getApp(direct.id)?.conversationIds).toEqual(
+      getApp(linked.id)?.conversationIds,
+    );
+    expect(listAppsByConversation("conv-plain")).toHaveLength(2);
+  });
+
+  test("an unregistered conversation links only itself", () => {
+    const app = createApp(makeAppParams("Orphan App"));
+    linkAppToConversationLineage(app.id, "conv-gone");
+
+    expect(getApp(app.id)?.conversationIds).toEqual(["conv-gone"]);
+  });
+
+  test("a non-existent app is a no-op", () => {
+    registerConversation("conv-visible");
+    registerSubagent("conv-fork", "conv-visible");
+
+    expect(() =>
+      linkAppToConversationLineage("nonexistent-id", "conv-fork"),
+    ).not.toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Direct vs inherited associations
+// ---------------------------------------------------------------------------
+
+describe("isDirectAppConversation", () => {
+  test("the seed conversation is direct and its ancestors are inherited", () => {
+    registerConversation("conv-visible");
+    registerSubagent("conv-fork", "conv-visible");
+
+    const app = createApp(makeAppParams("Continuation App"));
+    linkAppToConversationLineage(app.id, "conv-fork");
+
+    const loaded = getApp(app.id)!;
+    expect(loaded.inheritedConversationIds).toEqual(["conv-visible"]);
+    expect(isDirectAppConversation(loaded, "conv-fork")).toBe(true);
+    expect(isDirectAppConversation(loaded, "conv-visible")).toBe(false);
+  });
+
+  test("an inherited association still lists the app in the ancestor thread", () => {
+    registerConversation("conv-visible");
+    registerSubagent("conv-fork", "conv-visible");
+
+    const app = createApp(makeAppParams("Continuation App"));
+    linkAppToConversationLineage(app.id, "conv-fork");
+
+    expect(listAppsByConversation("conv-visible").map((a) => a.id)).toEqual([
+      app.id,
+    ]);
+  });
+
+  test("a record carrying no inherited list treats every association as direct", () => {
+    const app = createApp(makeAppParams("Plain App"));
+    addAppConversationId(app.id, "conv-plain");
+
+    const loaded = getApp(app.id)!;
+    expect(loaded.inheritedConversationIds).toBeUndefined();
+    expect(isDirectAppConversation(loaded, "conv-plain")).toBe(true);
+  });
+
+  test("a direct association supersedes an earlier inherited one", () => {
+    registerConversation("conv-visible");
+    registerSubagent("conv-fork", "conv-visible");
+
+    const app = createApp(makeAppParams("Adopted App"));
+    linkAppToConversationLineage(app.id, "conv-fork");
+    // The user later works on the same app in the thread they can see.
+    expect(addAppConversationId(app.id, "conv-visible")).toBe(false);
+
+    const loaded = getApp(app.id)!;
+    expect(loaded.conversationIds).toEqual(["conv-fork", "conv-visible"]);
+    expect(loaded.inheritedConversationIds).toEqual([]);
+    expect(isDirectAppConversation(loaded, "conv-visible")).toBe(true);
+  });
+
+  test("an inherited link never demotes an existing direct association", () => {
+    registerConversation("conv-visible");
+    registerSubagent("conv-fork", "conv-visible");
+
+    const app = createApp(makeAppParams("Foreground App"));
+    addAppConversationId(app.id, "conv-visible");
+    linkAppToConversationLineage(app.id, "conv-fork");
+
+    const loaded = getApp(app.id)!;
+    expect(loaded.conversationIds).toEqual(["conv-visible", "conv-fork"]);
+    expect(loaded.inheritedConversationIds).toBeUndefined();
+    expect(isDirectAppConversation(loaded, "conv-visible")).toBe(true);
+  });
+});

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" });