@vellumai/assistant 0.12.0-staging.1 → 0.12.0

package/src/notifications/__tests__/proactive-home-thread.test.ts

@@ -0,0 +1,111 @@
+import { beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// A proactive post into a thread must be recorded in the conversation the
+// thread's replies resolve to, so the record and the replies meet. These
+// cases run the real resolvers against the test workspace's database, so
+// the home and the reply's resolution are compared, not restated. The sync
+// publisher is observed, since a conversation minted here has to reach the
+// conversation list on its own.
+
+const listChanged = mock((_reason: string) => {});
+const actualSync = await import("../../runtime/sync/resource-sync-events.js");
+mock.module("../../runtime/sync/resource-sync-events.js", () => ({
+  ...actualSync,
+  publishConversationListChanged: listChanged,
+}));
+
+const { getOrCreateConversation } =
+  await import("../../persistence/conversation-key-store.js");
+const { initializeDb } = await import("../../persistence/db-init.js");
+const { buildScopedConversationKey, resolveInboundConversation } =
+  await import("../../persistence/delivery-crud.js");
+const { resolveProactiveHomeConversation } =
+  await import("../conversation-pairing.js");
+
+const homeParams = {
+  source: "notification",
+  conversationType: "background" as const,
+  title: "Messages to a chat",
+};
+
+beforeAll(async () => {
+  await initializeDb();
+});
+
+beforeEach(() => {
+  listChanged.mockClear();
+});
+
+describe("a post into a thread lives where the thread's replies arrive", () => {
+  test("telegram topic: the topic's own conversation, minted and announced when absent, found afterwards", async () => {
+    const home = await resolveProactiveHomeConversation({
+      ...homeParams,
+      sourceChannel: "telegram",
+      externalChatId: "555000111",
+      threadId: "42",
+    });
+    expect(home.createdNewConversation).toBe(true);
+    expect(listChanged).toHaveBeenCalledTimes(1);
+    expect(listChanged).toHaveBeenCalledWith("created");
+
+    const reply = resolveInboundConversation("telegram", "555000111", "42");
+    expect(reply.conversationId).toBe(home.conversationId);
+
+    listChanged.mockClear();
+    const again = await resolveProactiveHomeConversation({
+      ...homeParams,
+      sourceChannel: "telegram",
+      externalChatId: "555000111",
+      threadId: "42",
+    });
+    expect(again).toEqual({
+      conversationId: home.conversationId,
+      createdNewConversation: false,
+    });
+    expect(listChanged).not.toHaveBeenCalled();
+  });
+
+  test("slack thread with a conversation of its own: that conversation, never the flat channel's", async () => {
+    const flat = getOrCreateConversation(
+      buildScopedConversationKey("slack", "C0THREADED"),
+    );
+    const threaded = getOrCreateConversation(
+      buildScopedConversationKey("slack", "C0THREADED", "1700000000.000500"),
+    );
+    const home = await resolveProactiveHomeConversation({
+      ...homeParams,
+      sourceChannel: "slack",
+      externalChatId: "C0THREADED",
+      threadId: "1700000000.000500",
+    });
+    expect(home.conversationId).toBe(threaded.conversationId);
+    expect(home.conversationId).not.toBe(flat.conversationId);
+    expect(listChanged).not.toHaveBeenCalled();
+  });
+
+  test("a thread-less delivery keeps the chat-level home", async () => {
+    const first = await resolveProactiveHomeConversation({
+      ...homeParams,
+      sourceChannel: "telegram",
+      externalChatId: "555000222",
+    });
+    const second = await resolveProactiveHomeConversation({
+      ...homeParams,
+      sourceChannel: "telegram",
+      externalChatId: "555000222",
+    });
+    expect(first.createdNewConversation).toBe(true);
+    expect(listChanged).toHaveBeenCalledTimes(1);
+    expect(second).toEqual({
+      conversationId: first.conversationId,
+      createdNewConversation: false,
+    });
+    const topic = await resolveProactiveHomeConversation({
+      ...homeParams,
+      sourceChannel: "telegram",
+      externalChatId: "555000222",
+      threadId: "7",
+    });
+    expect(topic.conversationId).not.toBe(first.conversationId);
+  });
+});

package/src/notifications/conversation-pairing.ts

@@ -31,7 +31,7 @@
 
 import type { ConversationStrategy } from "../channels/config.js";
 import { getConversationStrategy } from "../channels/config.js";
-import type { ChannelId } from "../channels/types.js";
+import { type ChannelId, isChannelId } from "../channels/types.js";
 import { isAssistantInitiatedThreadsEnabled } from "../config/assistant-initiated-threads-gate.js";
 import {
   addMessage,
@@ -42,11 +42,18 @@ import {
   ASSISTANT_INITIATED_SOURCE,
   type ConversationCreateType,
 } from "../persistence/conversation-types.js";
+import {
+  findInboundConversationId,
+  resolveInboundConversation,
+} from "../persistence/delivery-crud.js";
 import {
   getBindingByChannelChat,
   upsertOutboundBinding,
 } from "../persistence/external-conversation-store.js";
-import { publishConversationMessagesChanged } from "../runtime/sync/resource-sync-events.js";
+import {
+  publishConversationListChanged,
+  publishConversationMessagesChanged,
+} from "../runtime/sync/resource-sync-events.js";
 import { getLogger } from "../util/logger.js";
 import { withSqliteRetry } from "../util/sqlite-retry.js";
 import {
@@ -483,10 +490,17 @@ export async function pairDeliveryWithConversation(
 
 /**
  * Where a chat's proactive posts live: the conversation a delivery to
- * (`sourceChannel`, `externalChatId`) is recorded in once the channel
- * acknowledges it.
+ * (`sourceChannel`, `externalChatId`), and `threadId` when the post lands
+ * in a thread, is recorded in once the channel acknowledges it.
+ *
+ * A delivery into a thread lives where the thread's replies arrive: the
+ * conversation ingress resolves for that (channel, chat, thread), found,
+ * aliased from the flat channel where Slack's thread evidence allows, or
+ * minted the way ingress mints it on the first reply. Inbound conversations
+ * on Slack and Telegram are keyed per thread, so any other home would put
+ * the post in a conversation its replies never reach.
  *
- * Resolution order:
+ * Resolution order for a thread-less delivery:
  * 1. The chat's inbound conversation, when the person has messaged in this
  *    chat and the inbound pipeline bound it at the un-prefixed key. Posting
  *    there keeps the notification in the history the person's replies land
@@ -514,9 +528,36 @@ export async function resolveProactiveHomeConversation(params: {
   title: string;
   groupId?: string;
   scheduleJobId?: string;
+  /** The thread the post lands in, as the channel resolved it. */
+  threadId?: string | null;
 }): Promise<{ conversationId: string; createdNewConversation: boolean }> {
   const { sourceChannel, externalChatId } = params;
 
+  const threadId = params.threadId?.trim();
+  if (threadId) {
+    const existing = findInboundConversationId(
+      sourceChannel,
+      externalChatId,
+      threadId,
+    );
+    if (existing) {
+      return { conversationId: existing, createdNewConversation: false };
+    }
+    const minted = resolveInboundConversation(
+      sourceChannel,
+      externalChatId,
+      threadId,
+      isChannelId(sourceChannel) ? { origin: sourceChannel } : undefined,
+    );
+    // The record that follows invalidates only the conversation's messages;
+    // a conversation that did not exist a moment ago has to reach the list.
+    publishConversationListChanged("created");
+    return {
+      conversationId: minted.conversationId,
+      createdNewConversation: true,
+    };
+  }
+
   const inboundBinding = getBindingByChannelChat(sourceChannel, externalChatId);
   if (inboundBinding) {
     const inboundConversation = getConversation(inboundBinding.conversationId);
@@ -575,6 +616,7 @@ export async function resolveProactiveHomeConversation(params: {
     sourceChannel: notificationChannel(sourceChannel),
     externalChatId,
   });
+  publishConversationListChanged("created");
   return { conversationId: conversation.id, createdNewConversation: true };
 }
 

package/src/notifications/delivered-post-record.ts

@@ -33,6 +33,8 @@ export interface DeliveredChannelPost {
   channel: ChannelId;
   /** Channel-native id of the chat the post landed in. */
   externalChatId: string;
+  /** The thread or topic the post landed in, absent when it is not in one. */
+  threadId?: string;
   /** The text the adapter sent, as the channel received it. */
   text: string;
   /** The message id the channel assigned when it acknowledged the post. */
@@ -56,6 +58,7 @@ export async function recordDeliveredChannelPost(
   const envelope: ProviderMessageMetadata = {
     source: post.channel,
     conversationExternalId: post.externalChatId,
+    ...(post.threadId ? { threadId: post.threadId } : {}),
     eventKind: "message",
   };
   const row = await addMessage(post.conversationId, "assistant", post.text, {

package/src/persistence/__tests__/slack-thread-root-evidence.test.ts

@@ -0,0 +1,102 @@
+import { beforeAll, describe, expect, test } from "bun:test";
+
+import { addMessage } from "../conversation-crud.js";
+import { getOrCreateConversation } from "../conversation-key-store.js";
+import { initializeDb } from "../db-init.js";
+import {
+  buildScopedConversationKey,
+  recordOutboundPost,
+  resolveInboundConversation,
+} from "../delivery-crud.js";
+
+// A Slack thread may continue the conversation that lives on the flat
+// channel key. The evidence for that includes the thread's root being a
+// post the assistant made from that conversation, resolved through the
+// outbound-post index the post-send reconciliation writes, so a reply under
+// the assistant's own top-level post lands where the post is recorded.
+
+beforeAll(async () => {
+  await initializeDb();
+});
+
+/** Record a delivered post the way the post-send reconciliation does. */
+async function recordFlatPost(
+  chatId: string,
+  providerMessageIds: readonly string[],
+): Promise<{ conversationId: string }> {
+  const flat = getOrCreateConversation(
+    buildScopedConversationKey("slack", chatId),
+  );
+  const [firstId] = providerMessageIds;
+  const row = await addMessage(flat.conversationId, "assistant", "posted", {
+    skipIndexing: true,
+    metadata: {
+      providerMeta: JSON.stringify({
+        source: "slack",
+        conversationExternalId: chatId,
+        messageId: firstId,
+        eventKind: "message",
+      }),
+    },
+  });
+  for (const providerMessageId of providerMessageIds) {
+    recordOutboundPost({
+      sourceChannel: "slack",
+      externalChatId: chatId,
+      providerMessageId,
+      messageId: row.id,
+      conversationId: flat.conversationId,
+    });
+  }
+  return flat;
+}
+
+describe("slack thread evidence", () => {
+  test("a thread rooted at the assistant's own flat post continues the flat conversation", async () => {
+    const flat = await recordFlatPost("C0ROOTED", ["1700000000.000900"]);
+    const reply = resolveInboundConversation(
+      "slack",
+      "C0ROOTED",
+      "1700000000.000900",
+    );
+    expect(reply.conversationId).toBe(flat.conversationId);
+  });
+
+  test("a thread rooted at a later chunk of a split post continues it too", async () => {
+    const flat = await recordFlatPost("C0SPLIT", [
+      "1700000000.000910",
+      "1700000000.000911",
+    ]);
+    const reply = resolveInboundConversation(
+      "slack",
+      "C0SPLIT",
+      "1700000000.000911",
+    );
+    expect(reply.conversationId).toBe(flat.conversationId);
+  });
+
+  test("a post recorded for another chat is not evidence for this one", async () => {
+    await recordFlatPost("C0SOMEWHEREELSE", ["1700000000.000902"]);
+    const flat = getOrCreateConversation(
+      buildScopedConversationKey("slack", "C0OTHERCHAT"),
+    );
+    const reply = resolveInboundConversation(
+      "slack",
+      "C0OTHERCHAT",
+      "1700000000.000902",
+    );
+    expect(reply.conversationId).not.toBe(flat.conversationId);
+  });
+
+  test("a thread with no evidence in the flat conversation is its own conversation", async () => {
+    const flat = getOrCreateConversation(
+      buildScopedConversationKey("slack", "C0UNRELATED"),
+    );
+    const reply = resolveInboundConversation(
+      "slack",
+      "C0UNRELATED",
+      "1700000000.000901",
+    );
+    expect(reply.conversationId).not.toBe(flat.conversationId);
+  });
+});

package/src/persistence/conversation-crud.ts

@@ -22,6 +22,10 @@ import {
 import { v4 as uuid, v7 as uuidv7 } from "uuid";
 import { z } from "zod";
 
+import {
+  forgetActivationConversation,
+  forgetAllActivationConversations,
+} from "../activation/progress-store.js";
 import type { ChannelId, InterfaceId } from "../channels/types.js";
 import { parseChannelId, parseInterfaceId } from "../channels/types.js";
 import { CHANNEL_IDS, isChannelId } from "../channels/types.js";
@@ -228,6 +232,29 @@ function purgeWatchTimelineForDeletedConversation(id: string): void {
   }
 }
 
+/**
+ * Release a deleted conversation from the activation checklist.
+ *
+ * The checklist records which task was launched into which conversation in a
+ * workspace file the cascade never reaches, so a delete that skipped this
+ * would leave the task's row stuck on Working, pointing at a conversation the
+ * user can no longer open and offering no way to launch the task again. A
+ * finished task keeps its record and only loses the dead link.
+ *
+ * Fired from the shared primitive so every delete caller cleans up, and
+ * best-effort for the same reason as the rest of the post-transaction
+ * cleanup: the conversation row is already gone, so throwing here would turn
+ * a completed delete into an error the caller cannot usefully retry.
+ */
+function forgetActivationLinkForDeletedConversation(id: string): void {
+  void forgetActivationConversation(id).catch((err: unknown) => {
+    log.warn(
+      { err, conversationId: id },
+      "Failed to release a deleted conversation from the activation checklist",
+    );
+  });
+}
+
 function deletePendingTelemetryEventsForConversation(id: string): void {
   const telemetry = getTelemetryDb({ createIfMissing: false });
   if (!telemetry || !dedicatedTableExists(telemetry, "telemetry_events")) {
@@ -2307,6 +2334,7 @@ export function deleteConversation(id: string): DeletedMemoryIds {
   }
 
   purgeWatchTimelineForDeletedConversation(id);
+  forgetActivationLinkForDeletedConversation(id);
 
   // Notify `conversation-deleted` hooks (e.g. the memory plugin failing its
   // still-pending jobs for this conversation). Fire-and-forget from this
@@ -2459,6 +2487,7 @@ export async function deleteConversationGently(
   }
 
   purgeWatchTimelineForDeletedConversation(id);
+  forgetActivationLinkForDeletedConversation(id);
 
   // Notify `conversation-deleted` hooks — fire-and-forget, same contract as
   // the synchronous delete primitive.
@@ -4089,6 +4118,16 @@ export async function clearAll(): Promise<{
 
   void clearAllConversationIds();
 
+  // The wipe took every conversation the checklist could be pointing at, so
+  // release all of them at once rather than one delete at a time. Same
+  // best-effort contract as the per-conversation path.
+  void forgetAllActivationConversations().catch((err: unknown) => {
+    log.warn(
+      { err },
+      "clearAll: failed to release conversations from the activation checklist",
+    );
+  });
+
   return { conversations: convCount, messages: msgCount };
 }
 

package/src/persistence/delivery-crud.ts

@@ -142,6 +142,19 @@ function legacySlackConversationHasThreadEvidence(
     return true;
   }
 
+  // A thread rooted at the assistant's own post continues the conversation
+  // the post was recorded in. Every id a delivered post was acknowledged
+  // under is in the outbound index, split posts included, so this lookup
+  // is exact and not bounded by the scan below.
+  const rooted = findMessageByProviderMessageId(
+    "slack",
+    externalChatId,
+    sourceThreadId,
+  );
+  if (rooted?.conversationId === conversationId) {
+    return true;
+  }
+
   let offset = 0;
   while (offset < SLACK_LEGACY_THREAD_EVIDENCE_MAX_SCAN) {
     const remaining = SLACK_LEGACY_THREAD_EVIDENCE_MAX_SCAN - offset;

package/src/plugins/AGENTS.md

@@ -25,5 +25,6 @@ Calling the assistant's service APIs from a default plugin (e.g. `persistence/co
 A plugin's HTTP routes live on disk under `<pluginDir>/routes/` and are served in the plugin's own namespace at `/x/plugins/<plugin-name>/<path>`. They are **not** a `Plugin` contribution slot and are not wired through the loader or bootstrap — the `/x/*` route dispatcher (`runtime/routes/user-route-dispatcher.ts`) resolves each request against the filesystem at request time, exactly like the workspace `/x/*` user routes it shares code with.
 
 - **Namespace reservation**: the `plugins/<name>/` prefix under `/x/` resolves only against `<workspaceDir>/plugins/<name>/routes/`. A request there never falls back to a workspace `routes/plugins/…` file, so plugins can't collide with workspace routes or each other. A missing file 404s; nothing is registered ahead of time.
+- **Reserved sub-namespace**: `notices/` under a plugin's namespace is served to the gateway's service principal only (`GATEWAY_PRINCIPALS`). `runtime/routes/user-routes.ts` registers it ahead of the `x/:path*` catch-all, and both the HTTP router and the gateway's IPC proxy take the first match, so the policy holds only while that order does. Those definitions match the plain spelling only; the `x/:path*` catch-all refuses every other spelling that resolves into the namespace (percent-encoded, doubled slashes, `.` segments, case variants) via `isPluginNoticeRoutePath`, so the reservation cannot be respelled around. The gateway posts its admission-denied notice there (`PLUGIN_ADMISSION_DENIED_NOTICE_PATH` in `@vellumai/gateway-client`, built from `PLUGIN_NOTICES_ROUTE_PREFIX`). Anything else the gateway must tell a plugin goes under the same prefix, never under a path an actor client can reach.
 - **Authoring**: each route file exports named HTTP-method functions (`export async function GET(request) {…}`), mirroring the workspace user-route convention. Nested directories and `index` files map to sub-paths (`routes/webhooks/incoming.ts` → `/x/plugins/<name>/webhooks/incoming`; `routes/index.ts` → the namespace root). Files are lazily loaded and mtime-cache-busted.
 - **Runtime access**: handlers receive the shared `UserRouteContext` (event hub, conversation posting) as a second argument, and may also reach singletons through their `@vellumai/plugin-api` imports.

package/src/runtime/auth/__tests__/route-policy.test.ts

@@ -350,6 +350,43 @@ describe("ROUTES policy declarations", () => {
     expect(route!.policy!.requiredScopes).toContain("ingress.write");
   });
 
+  test("a plugin's notices/ namespace is gateway-only, ahead of the /x catch-all", async () => {
+    // Both routers take the first definition that matches, and the gateway's
+    // IPC proxy compiles the schema in ROUTES order, so the reservation holds
+    // only while every notice definition precedes its catch-all sibling.
+    const { ROUTES } = await import("../../routes/index.js");
+    const methods = [
+      "GET",
+      "POST",
+      "PUT",
+      "PATCH",
+      "DELETE",
+      "HEAD",
+      "OPTIONS",
+    ];
+    const endpoints = [
+      "x/plugins/:plugin/notices",
+      "x/plugins/:plugin/notices/:path*",
+    ];
+    for (const method of methods) {
+      const catchAll = ROUTES.findIndex(
+        (r) => r.endpoint === "x/:path*" && r.method === method,
+      );
+      expect(catchAll).toBeGreaterThan(-1);
+      for (const endpoint of endpoints) {
+        const notice = ROUTES.findIndex(
+          (r) => r.endpoint === endpoint && r.method === method,
+        );
+        expect(notice).toBeGreaterThan(-1);
+        expect(catchAll).toBeGreaterThan(notice);
+        const policy = ROUTES[notice]!.policy;
+        expect(policy).not.toBeNull();
+        expect(policy!.allowedPrincipalTypes).toEqual(["svc_gateway"]);
+        expect(policy!.requiredScopes).toContain("internal.write");
+      }
+    }
+  });
+
   test("internal/twilio/voice-webhook is gateway-only", async () => {
     const { ROUTES } = await import("../../routes/index.js");
     const route = ROUTES.find(