@vellumai/assistant 0.4.56 → 0.5.0

package/src/runtime/routes/btw-routes.ts

@@ -12,6 +12,8 @@
  * No messages are persisted. `conversation.processing` is never set or checked.
  */
 
+import { existsSync, readFileSync } from "node:fs";
+
 import { buildToolDefinitions } from "../../daemon/conversation-tool-setup.js";
 import { getConversationByKey } from "../../memory/conversation-key-store.js";
 import { buildSystemPrompt } from "../../prompts/system-prompt.js";
@@ -21,13 +23,45 @@ import {
 } from "../../providers/provider-send-message.js";
 import { checkIngressForSecrets } from "../../security/secret-ingress.js";
 import { getLogger } from "../../util/logger.js";
+import { getWorkspacePromptPath } from "../../util/platform.js";
 import type { AuthContext } from "../auth/types.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
 import type { SendMessageDeps } from "../http-types.js";
+import { getCachedIntro, setCachedIntro } from "./identity-intro-cache.js";
 
 const log = getLogger("btw-routes");
 
+/** Conversation key used by the client for identity intro generation. */
+const IDENTITY_INTRO_KEY = "identity-intro";
+
+/**
+ * Parse the `## Identity Intro` section from SOUL.md.
+ * Returns the first non-empty line under that heading, or null.
+ */
+function readSoulIdentityIntro(): string | null {
+  try {
+    const soulPath = getWorkspacePromptPath("SOUL.md");
+    if (!existsSync(soulPath)) return null;
+    const content = readFileSync(soulPath, "utf-8");
+
+    let inSection = false;
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (/^#+\s/.test(trimmed)) {
+        inSection = trimmed.toLowerCase().includes("identity intro");
+        continue;
+      }
+      if (inSection && trimmed.length > 0) {
+        return trimmed;
+      }
+    }
+  } catch {
+    // Fall through — no SOUL.md intro available
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Handler
 // ---------------------------------------------------------------------------
@@ -77,6 +111,43 @@ async function handleBtw(
     );
   }
 
+  // ----- Identity intro fast-path -----
+  // When the client requests the identity intro, check SOUL.md first (persisted
+  // during onboarding), then the LLM-generated cache. Only fall through to a
+  // live LLM call when neither source has a value.
+  if (conversationKey === IDENTITY_INTRO_KEY) {
+    const soulIntro = readSoulIdentityIntro();
+    const fastText = soulIntro ?? getCachedIntro()?.text;
+    if (fastText) {
+      log.debug(
+        soulIntro
+          ? "Returning SOUL.md identity intro"
+          : "Returning cached identity intro",
+      );
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(
+            encoder.encode(
+              `event: btw_text_delta\ndata: ${JSON.stringify({ text: fastText })}\n\n`,
+            ),
+          );
+          controller.enqueue(
+            encoder.encode(`event: btw_complete\ndata: {}\n\n`),
+          );
+          controller.close();
+        },
+      });
+      return new Response(stream, {
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+        },
+      });
+    }
+  }
+
   // Look up an existing conversation — never create one.  BTW is ephemeral
   // (the file header promises "No messages are persisted"), so we must not
   // call getOrCreateConversation which would insert a DB row.  When no
@@ -116,6 +187,9 @@ async function handleBtw(
             ? conversation.systemPrompt
             : buildSystemPrompt({ excludeBootstrap: true });
 
+          const isIntroRequest = conversationKey === IDENTITY_INTRO_KEY;
+          let textDeltaCount = 0;
+          let collectedText = "";
           await conversation.provider.sendMessage(
             messages,
             tools,
@@ -128,6 +202,8 @@ async function handleBtw(
               },
               onEvent: (event) => {
                 if (event.type === "text_delta") {
+                  textDeltaCount++;
+                  if (isIntroRequest) collectedText += event.text;
                   controller.enqueue(
                     encoder.encode(
                       `event: btw_text_delta\ndata: ${JSON.stringify({ text: event.text })}\n\n`,
@@ -139,6 +215,23 @@ async function handleBtw(
             },
           );
 
+          if (textDeltaCount === 0) {
+            log.warn(
+              { conversationKey, messageCount: messages.length },
+              "btw side-chain completed with no text deltas",
+            );
+          }
+
+          // Cache the generated identity intro for subsequent requests.
+          if (isIntroRequest && collectedText.trim()) {
+            try {
+              setCachedIntro(collectedText.trim());
+              log.debug("Cached identity intro text");
+            } catch {
+              // Non-fatal — next request will regenerate.
+            }
+          }
+
           controller.enqueue(
             encoder.encode(`event: btw_complete\ndata: {}\n\n`),
           );

package/src/runtime/routes/channel-verification-routes.ts

@@ -21,6 +21,7 @@ import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
 import {
   cancelOutbound,
+  deliverVerificationSlack,
   normalizeTelegramDestination,
   resendOutbound,
   startOutbound,
@@ -118,12 +119,20 @@ export async function handleCreateVerificationSession(
       verificationRateLimiter.recordFailure(rateLimitKey);
     }
 
+    // Dispatch Slack DM delivery from the daemon process (not sandboxed).
+    if (result._pendingSlackDm) {
+      const { userId, text, assistantId: aid } = result._pendingSlackDm;
+      deliverVerificationSlack(userId, text, aid);
+    }
+
     const status = result.success
       ? 200
       : result.error === "rate_limited"
         ? 429
         : 400;
-    return Response.json(result, { status });
+    // Strip internal field from the response
+    const { _pendingSlackDm: _, ...publicResult } = result;
+    return Response.json(publicResult, { status });
   }
 
   // Inbound challenge path
@@ -167,12 +176,20 @@ export async function handleResendVerificationSession(
     channel: body.channel,
     originConversationId: body.originConversationId,
   });
+
+  // Dispatch Slack DM delivery from the daemon process (not sandboxed).
+  if (result._pendingSlackDm) {
+    const { userId, text, assistantId: aid } = result._pendingSlackDm;
+    deliverVerificationSlack(userId, text, aid);
+  }
+
   const status = result.success
     ? 200
     : result.error === "rate_limited"
       ? 429
       : 400;
-  return Response.json(result, { status });
+  const { _pendingSlackDm: _, ...publicResult } = result;
+  return Response.json(publicResult, { status });
 }
 
 /**

package/src/runtime/routes/conversation-management-routes.ts

@@ -4,6 +4,7 @@
  * POST   /v1/conversations/switch         — switch to an existing conversation
  * PATCH  /v1/conversations/:id/name       — rename a conversation
  * DELETE /v1/conversations                 — clear all conversations
+ * POST   /v1/conversations/:id/wipe       — wipe conversation and revert memory
  * DELETE /v1/conversations/:id            — delete a single conversation
  * POST   /v1/conversations/:id/cancel     — cancel generation
  * POST   /v1/conversations/:id/undo       — undo last message
@@ -14,6 +15,7 @@
 import {
   batchSetDisplayOrders,
   deleteConversation,
+  wipeConversation,
 } from "../../memory/conversation-crud.js";
 import {
   resolveConversationId,
@@ -121,6 +123,57 @@ export function conversationManagementRouteDefinitions(
         return new Response(null, { status: 204 });
       },
     },
+    {
+      endpoint: "conversations/:id/wipe",
+      method: "POST",
+      policyKey: "conversations/wipe",
+      handler: async ({ params }) => {
+        const resolvedId = resolveConversationId(params.id);
+        if (!resolvedId) {
+          return httpError(
+            "NOT_FOUND",
+            `Conversation ${params.id} not found`,
+            404,
+          );
+        }
+        deps.destroyConversation(resolvedId);
+        const result = wipeConversation(resolvedId);
+        // Enqueue Qdrant vector cleanup jobs
+        for (const segId of result.segmentIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "segment",
+            targetId: segId,
+          });
+        }
+        for (const itemId of result.orphanedItemIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "item",
+            targetId: itemId,
+          });
+        }
+        for (const summaryId of result.deletedSummaryIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "summary",
+            targetId: summaryId,
+          });
+        }
+        log.info(
+          {
+            conversationId: resolvedId,
+            unsuperseded: result.unsupersededItemIds.length,
+            summariesDeleted: result.deletedSummaryIds.length,
+            jobsCancelled: result.cancelledJobCount,
+          },
+          "Wiped conversation and reverted memory changes",
+        );
+        return Response.json({
+          wiped: true,
+          unsupersededItems: result.unsupersededItemIds.length,
+          deletedSummaries: result.deletedSummaryIds.length,
+          cancelledJobs: result.cancelledJobCount,
+        });
+      },
+    },
     {
       endpoint: "conversations/:id",
       method: "DELETE",
@@ -163,7 +216,8 @@ export function conversationManagementRouteDefinitions(
       method: "POST",
       policyKey: "conversations/cancel",
       handler: ({ params }) => {
-        deps.cancelGeneration(params.id);
+        const resolvedId = resolveConversationId(params.id) ?? params.id;
+        deps.cancelGeneration(resolvedId);
         return new Response(null, { status: 202 });
       },
     },

package/src/runtime/routes/conversation-query-routes.ts

@@ -200,7 +200,7 @@ export function conversationQueryRouteDefinitions(
             requestId: params.id,
           });
         }
-        if (result.reason === "session_not_found") {
+        if (result.reason === "conversation_not_found") {
           return httpError("NOT_FOUND", "Conversation not found", 404);
         }
         return httpError("NOT_FOUND", "Queued message not found", 404);

package/src/runtime/routes/conversation-routes.ts

@@ -35,6 +35,7 @@ import {
   createCanonicalGuardianRequest,
   generateCanonicalRequestCode,
   listPendingRequestsByConversationScope,
+  resolveCanonicalGuardianRequest,
 } from "../../memory/canonical-guardian-store.js";
 import {
   addMessage,
@@ -58,6 +59,7 @@ import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
 import type { AuthContext } from "../auth/types.js";
 import { bridgeConfirmationRequestToGuardian } from "../confirmation-request-guardian-bridge.js";
 import { routeGuardianReply } from "../guardian-reply-router.js";
+import { healGuardianBindingDrift } from "../guardian-vellum-migration.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
 import type {
@@ -492,16 +494,16 @@ function makeHubPublisher(
     }
 
     // ServerMessage is a large union; conversationId exists on most but not all variants.
-    const msgSessionId =
+    const msgConversationId =
       "conversationId" in msg &&
       typeof (msg as { conversationId?: unknown }).conversationId === "string"
         ? (msg as { conversationId: string }).conversationId
         : undefined;
-    const resolvedSessionId = msgSessionId ?? conversationId;
+    const resolvedConversationId = msgConversationId ?? conversationId;
     const event = buildAssistantEvent(
       DAEMON_INTERNAL_ASSISTANT_ID,
       msg,
-      resolvedSessionId,
+      resolvedConversationId,
     );
     hubChain = (async () => {
       await hubChain;
@@ -646,12 +648,44 @@ export async function handleSendMessage(
   // the same trust resolution pipeline that channel ingress uses.
   if (authContext.actorPrincipalId) {
     const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
-    const trustCtx = resolveTrustContext({
+    let trustCtx = resolveTrustContext({
       assistantId,
       sourceChannel: "vellum",
       conversationExternalId: "local",
       actorExternalId: authContext.actorPrincipalId,
     });
+    if (trustCtx.trustClass === "unknown") {
+      // Attempt to heal guardian binding drift: after a DB reset the
+      // guardian binding gets a new vellum-principal-* UUID while the
+      // client still holds a valid JWT with the old one. The signing
+      // key survives the reset, so the JWT is authentic — just stale.
+      const healed = healGuardianBindingDrift(authContext.actorPrincipalId);
+      if (healed) {
+        trustCtx = resolveTrustContext({
+          assistantId,
+          sourceChannel: "vellum",
+          conversationExternalId: "local",
+          actorExternalId: authContext.actorPrincipalId,
+        });
+        log.info(
+          {
+            actorPrincipalId: authContext.actorPrincipalId,
+            trustClass: trustCtx.trustClass,
+          },
+          "Trust re-resolved after guardian binding drift heal",
+        );
+      } else {
+        log.warn(
+          {
+            actorPrincipalId: authContext.actorPrincipalId,
+            sourceChannel,
+            trustClass: trustCtx.trustClass,
+            principalType: authContext.principalType,
+          },
+          "JWT-verified actor resolved to unknown trust class — possible guardian binding drift (e.g. DB reset without re-bootstrap)",
+        );
+      }
+    }
     conversation.setTrustContext(withSourceChannel(sourceChannel, trustCtx));
   } else {
     // Service principals (svc_gateway) or tokens without an actor ID
@@ -811,6 +845,11 @@ export async function handleSendMessage(
             state: "denied" as const,
             source: "auto_deny" as const,
           });
+          // Sync canonical guardian request status so stale "pending" DB
+          // records don't get matched by later guardian reply routing.
+          resolveCanonicalGuardianRequest(interaction.requestId, "pending", {
+            status: "denied",
+          });
         }
       }
       conversation.denyAllPendingConfirmations();
@@ -842,6 +881,11 @@ export async function handleSendMessage(
           state: "denied" as const,
           source: "auto_deny" as const,
         });
+        // Sync canonical guardian request status so stale "pending" DB
+        // records don't get matched by later guardian reply routing.
+        resolveCanonicalGuardianRequest(interaction.requestId, "pending", {
+          status: "denied",
+        });
       }
     }
     conversation.denyAllPendingConfirmations();
@@ -931,7 +975,7 @@ export async function handleSendMessage(
       );
 
       // Defer event publishing to next tick so the HTTP response reaches the
-      // client first. This ensures the client's serverToLocalSessionMap is
+      // client first. This ensures the client's serverToLocalConversationMap is
       // populated before SSE events arrive, preventing dropped events in new
       // desktop conversations.
       //

package/src/runtime/routes/conversation-starter-routes.ts

@@ -0,0 +1,207 @@
+/**
+ * Route handlers for conversation starter endpoints.
+ *
+ * GET /v1/conversation-starters — list conversation starters (chips)
+ */
+
+import { and, desc, eq, inArray, like } from "drizzle-orm";
+
+import { getDb } from "../../memory/db.js";
+import { enqueueMemoryJob } from "../../memory/jobs-store.js";
+import { rawGet } from "../../memory/raw-query.js";
+import { conversationStarters, memoryJobs } from "../../memory/schema.js";
+import type { RouteDefinition } from "../http-router.js";
+
+// ---------------------------------------------------------------------------
+// Strongest-first ordering — maximize category diversity so the top four
+// chips form a coherent, non-repetitive row.
+// ---------------------------------------------------------------------------
+
+interface StarterItem {
+  id: string;
+  label: string;
+  prompt: string;
+  category: string | null;
+  batch: number;
+}
+
+/**
+ * Re-order starters so adjacent items have distinct categories wherever
+ * possible. Within each category, preserve the original (batch-desc) order.
+ * This is deterministic — same input always produces the same output.
+ */
+export function orderStrongestFirst<T extends StarterItem>(items: T[]): T[] {
+  if (items.length <= 1) return items;
+
+  // Group by category, preserving original order within each group
+  const byCategory = new Map<string, T[]>();
+  for (const item of items) {
+    const cat = item.category ?? "other";
+    let group = byCategory.get(cat);
+    if (!group) {
+      group = [];
+      byCategory.set(cat, group);
+    }
+    group.push(item);
+  }
+
+  // Prefer categories with the most remaining items so the row stays varied
+  // early without burying the dominant themes entirely.
+  const sortedGroups = [...byCategory.entries()]
+    .sort((a, b) => b[1].length - a[1].length)
+    .map(([, group]) => ({ items: group, idx: 0 }));
+
+  const result: T[] = [];
+  const seenCategories = new Set<string>();
+  let lastCategory: string | null = null;
+
+  while (result.length < items.length) {
+    let picked = false;
+    const availableGroups = sortedGroups.filter(
+      (group) => group.idx < group.items.length,
+    );
+
+    const unseenGroups = availableGroups.filter((group) => {
+      const category = group.items[group.idx]?.category ?? "other";
+      return category !== lastCategory && !seenCategories.has(category);
+    });
+
+    const nextGroups =
+      unseenGroups.length > 0
+        ? unseenGroups
+        : availableGroups.filter((group) => {
+            const category = group.items[group.idx]?.category ?? "other";
+            return category !== lastCategory;
+          });
+
+    // First pass: prefer unseen categories, then avoid adjacent duplicates.
+    for (const group of nextGroups) {
+      if (group.idx >= group.items.length) continue;
+      const candidate = group.items[group.idx];
+      const cat = candidate.category ?? "other";
+      result.push(candidate);
+      group.idx++;
+      seenCategories.add(cat);
+      lastCategory = cat;
+      picked = true;
+      break;
+    }
+
+    // Fallback: if all remaining items share the same category, just pick next
+    if (!picked) {
+      for (const group of availableGroups) {
+        if (group.idx < group.items.length) {
+          const candidate = group.items[group.idx];
+          const cat = candidate.category ?? "other";
+          result.push(candidate);
+          group.idx++;
+          seenCategories.add(cat);
+          lastCategory = cat;
+          picked = true;
+          break;
+        }
+      }
+    }
+
+    if (!picked) break;
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// GET /v1/conversation-starters
+// ---------------------------------------------------------------------------
+
+function handleListConversationStarters(url: URL): Response {
+  const limitParam = Math.min(
+    Math.max(1, Number(url.searchParams.get("limit") ?? 4)),
+    20,
+  );
+  const offsetParam = Math.max(0, Number(url.searchParams.get("offset") ?? 0));
+  const scopeId = url.searchParams.get("scope_id") ?? "default";
+
+  const db = getDb();
+
+  // Fetch chips (ranked by model, newest batch first)
+  const rawItems = db
+    .select({
+      id: conversationStarters.id,
+      label: conversationStarters.label,
+      prompt: conversationStarters.prompt,
+      category: conversationStarters.category,
+      batch: conversationStarters.generationBatch,
+    })
+    .from(conversationStarters)
+    .where(
+      and(
+        eq(conversationStarters.scopeId, scopeId),
+        eq(conversationStarters.cardType, "chip"),
+      ),
+    )
+    .orderBy(
+      desc(conversationStarters.generationBatch),
+      desc(conversationStarters.createdAt),
+    )
+    .limit(limitParam)
+    .offset(offsetParam)
+    .all();
+
+  const countRow = rawGet<{ c: number }>(
+    `SELECT COUNT(*) AS c FROM conversation_starters WHERE scope_id = ? AND card_type = 'chip'`,
+    scopeId,
+  );
+  const total = countRow?.c ?? 0;
+
+  // If starters exist, return them immediately.
+  if (total > 0) {
+    return Response.json({
+      starters: orderStrongestFirst(rawItems),
+      total,
+      status: "ready",
+    });
+  }
+
+  // No starters — check whether we have memory items to generate from.
+  const memoryCount = rawGet<{ c: number }>(
+    `SELECT COUNT(*) AS c FROM memory_items WHERE status = 'active' AND scope_id = ?`,
+    scopeId,
+  );
+
+  if (!memoryCount || memoryCount.c === 0) {
+    return Response.json({ starters: [], total: 0, status: "empty" });
+  }
+
+  // Memory items exist but no starters yet — ensure a generation job is queued.
+  const existing = db
+    .select({ id: memoryJobs.id })
+    .from(memoryJobs)
+    .where(
+      and(
+        eq(memoryJobs.type, "generate_conversation_starters"),
+        inArray(memoryJobs.status, ["pending", "running"]),
+        like(memoryJobs.payload, `%"scopeId":"${scopeId}"%`),
+      ),
+    )
+    .get();
+
+  if (!existing) {
+    enqueueMemoryJob("generate_conversation_starters", { scopeId });
+  }
+
+  return Response.json({ starters: [], total: 0, status: "generating" });
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export function conversationStarterRouteDefinitions(): RouteDefinition[] {
+  return [
+    {
+      endpoint: "conversation-starters",
+      method: "GET",
+      handler: (ctx) => handleListConversationStarters(ctx.url),
+    },
+  ];
+}

package/src/runtime/routes/guardian-bootstrap-routes.ts

@@ -19,6 +19,7 @@ import { getLogger } from "../../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
 import { mintCredentialPair } from "../auth/credential-service.js";
 import { httpError } from "../http-errors.js";
+import { isPrivateAddress } from "../middleware/auth.js";
 
 /** Bun server shape needed for requestIP -- avoids importing the full Bun type. */
 type ServerWithRequestIP = {
@@ -71,30 +72,33 @@ function ensureGuardianPrincipal(assistantId: string): {
   return { guardianPrincipalId, isNew: true };
 }
 
-/** Loopback addresses — used to gate the bootstrap endpoint to local-only. */
-const LOOPBACK_ADDRESSES = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
-
 /**
  * Handle POST /v1/guardian/init
  *
  * Body: { platform: 'macos', deviceId: string }
  * Returns: { guardianPrincipalId, accessToken, isNew }
  *
- * This endpoint is loopback-only (macOS local use only). iOS devices
- * obtain actor tokens exclusively through the QR pairing flow.
+ * This endpoint is restricted to private-network peers (loopback, RFC 1918,
+ * Docker bridge, etc.). iOS devices obtain actor tokens exclusively through
+ * the QR pairing flow.
  */
 export async function handleGuardianBootstrap(
   req: Request,
   server: ServerWithRequestIP,
 ): Promise<Response> {
-  // Reject proxied requests — bootstrap is local-only
-  if (req.headers.get("x-forwarded-for") && !isHttpAuthDisabled()) {
+  // Reject requests forwarded from public networks. The gateway sets
+  // x-forwarded-for to the real client IP; if that IP is on a private
+  // network (loopback, Docker bridge, RFC 1918) the request is still
+  // considered local. Only reject when the forwarded IP is public.
+  const forwarded = req.headers.get("x-forwarded-for");
+  const forwardedIp = forwarded ? forwarded.split(",")[0].trim() : null;
+  if (forwardedIp && !isPrivateAddress(forwardedIp) && !isHttpAuthDisabled()) {
     return httpError("FORBIDDEN", "Bootstrap endpoint is local-only", 403);
   }
 
-  // Reject non-loopback peers
+  // Reject non-private-network peers (allows loopback, Docker bridge, etc.)
   const peerIp = server.requestIP(req)?.address;
-  if ((!peerIp || !LOOPBACK_ADDRESSES.has(peerIp)) && !isHttpAuthDisabled()) {
+  if ((!peerIp || !isPrivateAddress(peerIp)) && !isHttpAuthDisabled()) {
     return httpError("FORBIDDEN", "Bootstrap endpoint is local-only", 403);
   }