@vellumai/assistant 0.7.3 → 0.8.0

package/src/daemon/lifecycle.ts

@@ -7,10 +7,7 @@ import { reconcileCallsOnStartup } from "../calls/call-recovery.js";
 import { setRelayBroadcast } from "../calls/relay-server.js";
 import { TwilioConversationRelayProvider } from "../calls/twilio-provider.js";
 import { setVoiceBridgeDeps } from "../calls/voice-session-bridge.js";
-import {
-  initFeatureFlagOverrides,
-  isAssistantFeatureFlagEnabled,
-} from "../config/assistant-feature-flags.js";
+import { initFeatureFlagOverrides } from "../config/assistant-feature-flags.js";
 import {
   getPlatformAssistantId,
   getRuntimeHttpHost,
@@ -117,7 +114,10 @@ import {
 } from "./guardian-action-generators.js";
 import { backfillSlackInjectionTemplates } from "./handlers/config-slack-channel.js";
 import { installAssistantSymlink } from "./install-symlink.js";
-import { maybeSeedMemoryV2Skills } from "./memory-v2-startup.js";
+import {
+  maybeRebuildMemoryV2Concepts,
+  maybeSeedMemoryV2Skills,
+} from "./memory-v2-startup.js";
 import { processMessage } from "./process-message.js";
 import { runProfilerSweep } from "./profiler-run-store.js";
 import {
@@ -318,21 +318,16 @@ export async function runDaemon(): Promise<void> {
     const signingKey = resolveSigningKey();
     initAuthSigningKey(signingKey);
 
-    // Pre-populate
-    // subsequent sync isAssistantFeatureFlagEnabled() calls have data.
-    // Fired non-blocking so a slow or unreachable gateway doesn't delay
-    // daemon startup (the IPC call has a 3s connect + 5s call timeout
-    // that would otherwise stall the critical path).
-    //
-    // On resolve, retry the v2 skill seed: the synchronous gate at the
-    // skill-seed call site below evaluates the memory-v2-enabled flag
-    // before the gateway has populated overrides, so a cold-boot race
-    // can leave the v2 skill collection unseeded for the lifetime of
-    // the daemon. seedV2SkillEntries is idempotent, so re-running after
-    // overrides land is safe.
-    void initFeatureFlagOverrides()
-      .then(() => maybeSeedMemoryV2Skills(loadConfig()))
-      .catch((err) => log.warn({ err }, "Background feature flag init failed"));
+    // Pre-populate feature flag overrides so subsequent sync
+    // isAssistantFeatureFlagEnabled() calls have data. Fired non-blocking
+    // so a slow or unreachable gateway doesn't delay daemon startup (the
+    // IPC call has a 3s connect + 5s call timeout that would otherwise
+    // stall the critical path).
+    void initFeatureFlagOverrides().catch((err) =>
+      log.warn({ err }, "Background feature flag init failed"),
+    );
+
+    maybeSeedMemoryV2Skills(loadConfig());
 
     seedInterfaceFiles();
 
@@ -741,64 +736,87 @@ export async function runDaemon(): Promise<void> {
       }
 
       if (qdrantStarted) {
-        try {
-          const embeddingSelection = await selectEmbeddingBackend(config);
-          // Sentinel only encodes the dense provider+model identity; sparse
-          // encoder changes never require collection recreation, so they
-          // intentionally do not contribute to the v1 collection identity.
-          const embeddingModel = embeddingSelection.backend
-            ? `${embeddingSelection.backend.provider}:${embeddingSelection.backend.model}`
-            : undefined;
-          const qdrantClient = initQdrantClient({
-            url: qdrantUrl,
-            collection: config.memory.qdrant.collection,
-            vectorSize: config.memory.qdrant.vectorSize,
-            onDisk: config.memory.qdrant.onDisk,
-            quantization: config.memory.qdrant.quantization,
-            embeddingModel,
-          });
+        // Skip the v1 Qdrant collection lifecycle when memory v2 is active —
+        // the v1 collection has no writers (handleRemember returns early) or
+        // readers (graph search is bypassed) under v2, so ensuring/migrating
+        // it just maintains a dead-on-arrival collection. Existing on-disk
+        // collections are left intact so flipping v2 off restores v1 cleanly.
+        if (!config.memory.v2.enabled) {
+          try {
+            const embeddingSelection = await selectEmbeddingBackend(config);
+            // Sentinel only encodes the dense provider+model identity; sparse
+            // encoder changes never require collection recreation, so they
+            // intentionally do not contribute to the v1 collection identity.
+            const embeddingModel = embeddingSelection.backend
+              ? `${embeddingSelection.backend.provider}:${embeddingSelection.backend.model}`
+              : undefined;
+            const qdrantClient = initQdrantClient({
+              url: qdrantUrl,
+              collection: config.memory.qdrant.collection,
+              vectorSize: config.memory.qdrant.vectorSize,
+              onDisk: config.memory.qdrant.onDisk,
+              quantization: config.memory.qdrant.quantization,
+              embeddingModel,
+            });
+
+            // Eagerly ensure the collection exists so we detect migrations
+            // (unnamed→named vectors, dimension/model changes) at startup.
+            // If a destructive migration occurred, enqueue a rebuild_index job
+            // to re-embed all memory items from the SQLite cache.
+            const { migrated } = await qdrantClient.ensureCollection();
+            if (migrated) {
+              enqueueMemoryJob("rebuild_index", {});
+              log.info(
+                "Qdrant collection was migrated — enqueued rebuild_index job",
+              );
+            }
 
-          // Eagerly ensure the collection exists so we detect migrations
-          // (unnamed→named vectors, dimension/model changes) at startup.
-          // If a destructive migration occurred, enqueue a rebuild_index job
-          // to re-embed all memory items from the SQLite cache.
-          const { migrated } = await qdrantClient.ensureCollection();
-          if (migrated) {
-            enqueueMemoryJob("rebuild_index", {});
-            log.info(
-              "Qdrant collection was migrated — enqueued rebuild_index job",
+            log.info("Qdrant vector store initialized");
+          } catch (err) {
+            log.warn(
+              { err },
+              "Qdrant client initialization failed — memory features will be degraded",
             );
           }
+        }
 
-          log.info("Qdrant vector store initialized");
+        // Detect schema drift on the v2 concept-page collection (e.g.
+        // pre-#29823 collections lacking summary_dense / summary_sparse) and
+        // recreate + enqueue a reembed when needed. Awaited inline so the
+        // reembed enqueue happens before the memory worker drains its first
+        // batch; the call's own try/catch keeps any v2-side failure from
+        // blocking the v1 PKB reconcile or BM25 build below.
+        try {
+          await maybeRebuildMemoryV2Concepts(config);
         } catch (err) {
           log.warn(
             { err },
-            "Qdrant client initialization failed — memory features will be degraded",
+            "Memory v2 collection schema check threw — continuing startup",
           );
         }
 
-        // Reconcile the PKB Qdrant index against the on-disk tree. Kept
-        // inside the `qdrantStarted` guard so we don't call
-        // `getQdrantClient()` (which throws "not initialized") on every
-        // startup when Qdrant is unavailable. Fire-and-forget so enqueued
-        // re-index jobs drain in the background and first-turn latency
-        // stays unaffected.
-        void (async () => {
-          try {
-            const { reconcilePkbIndex } =
-              await import("../memory/pkb/pkb-reconcile.js");
-            const { PKB_WORKSPACE_SCOPE } =
-              await import("../memory/pkb/types.js");
-            const pkbRoot = join(getWorkspaceDir(), "pkb");
-            await reconcilePkbIndex(pkbRoot, PKB_WORKSPACE_SCOPE);
-          } catch (err) {
-            log.warn(
-              { err },
-              "PKB index reconciliation failed — continuing startup",
-            );
-          }
-        })();
+        // Reconcile the PKB Qdrant index against the on-disk tree. Gated on
+        // !v2 because PKB is the v1 storage layer; under v2 the v1 collection
+        // is not initialized, so calling `getQdrantClient()` here would throw.
+        // Fire-and-forget so enqueued re-index jobs drain in the background
+        // and first-turn latency stays unaffected.
+        if (!config.memory.v2.enabled) {
+          void (async () => {
+            try {
+              const { reconcilePkbIndex } =
+                await import("../memory/pkb/pkb-reconcile.js");
+              const { PKB_WORKSPACE_SCOPE } =
+                await import("../memory/pkb/types.js");
+              const pkbRoot = join(getWorkspaceDir(), "pkb");
+              await reconcilePkbIndex(pkbRoot, PKB_WORKSPACE_SCOPE);
+            } catch (err) {
+              log.warn(
+                { err },
+                "PKB index reconciliation failed — continuing startup",
+              );
+            }
+          })();
+        }
 
         // Build the BM25 corpus stats (per-token document frequencies and
         // average document length) used by the v2 sparse channel. Without
@@ -1283,14 +1301,11 @@ export async function runDaemon(): Promise<void> {
       log.warn({ err }, "Proactive artifact backfill failed");
     }
 
-    // Filing yields to the memory v2 consolidation job when the flag is on —
+    // Filing yields to the memory v2 consolidation job when v2 is enabled —
     // both serve the same role (periodic background memory processing) and
     // running both is redundant. The consolidation job runs through the
     // memory jobs worker (see `maybeEnqueueGraphMaintenanceJobs`).
-    const memoryV2Enabled = isAssistantFeatureFlagEnabled(
-      "memory-v2-enabled",
-      config,
-    );
+    const memoryV2Enabled = config.memory.v2.enabled;
     let filing: FilingService | null = null;
     if (!memoryV2Enabled) {
       const filingConfig = config.filing;

package/src/daemon/memory-v2-startup.ts

@@ -6,9 +6,9 @@
 // startup work invoked from `lifecycle.ts`. Lives in its own file so the unit
 // test for the gate does not have to mount the entire lifecycle import graph.
 
-import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
 import type { AssistantConfig } from "../config/schema.js";
 import { getLogger } from "../util/logger.js";
+import { getWorkspaceDir } from "../util/platform.js";
 
 const log = getLogger("memory-v2-startup");
 
@@ -16,21 +16,12 @@ const log = getLogger("memory-v2-startup");
  * Fire-and-forget seed of the v2 skill entries (now indexed alongside concept
  * pages in `memory_v2_concept_pages` under the `skills/<id>` slug prefix), and
  * a one-shot best-effort cleanup of the legacy `memory_v2_skills` Qdrant
- * collection. Gated on both the `memory-v2-enabled` feature flag and the
- * workspace-level `config.memory.v2.enabled` switch so v2 modules stay out of
- * the v1 startup path when v2 is off.
- *
- * Uses a dynamic import so v2 code does not load unless the gate passes.
- * Never awaits — startup must not block on this (see `assistant/CLAUDE.md`
- * daemon startup philosophy).
+ * collection. Uses a dynamic import so v2 code does not load unless the gate
+ * passes. Never awaits — startup must not block on this (see
+ * `assistant/CLAUDE.md` daemon startup philosophy).
  */
 export function maybeSeedMemoryV2Skills(config: AssistantConfig): void {
-  if (
-    !isAssistantFeatureFlagEnabled("memory-v2-enabled", config) ||
-    !config.memory.v2.enabled
-  ) {
-    return;
-  }
+  if (!config.memory.v2.enabled) return;
   void import("../memory/v2/skill-store.js")
     .then(({ seedV2SkillEntries }) => seedV2SkillEntries())
     .catch((err) => log.warn({ err }, "Failed to seed v2 skill entries"));
@@ -43,3 +34,53 @@ export function maybeSeedMemoryV2Skills(config: AssistantConfig): void {
       ),
     );
 }
+
+/**
+ * Reconcile the v2 concept-page Qdrant collection with the expected schema
+ * and enqueue `memory_v2_reembed` when the collection is missing data.
+ * Triggers reembed in two cases:
+ *  - Drift: `ensureConceptPageCollection` returned `{ migrated: true }`
+ *    after destructively recreating the collection (e.g. pre-#29823
+ *    schemas lacking `summary_*` named vectors).
+ *  - Empty-after-create: the collection has zero points but pages exist on
+ *    disk — covers crash-mid-rebuild and external Qdrant wipes.
+ *
+ * Awaited inline by `lifecycle.ts` so the enqueue happens before the memory
+ * worker drains its first batch; the body is wrapped in try/catch so a v2
+ * failure never blocks startup.
+ */
+export async function maybeRebuildMemoryV2Concepts(
+  config: AssistantConfig,
+): Promise<void> {
+  if (!config.memory.v2.enabled) return;
+
+  try {
+    const { ensureConceptPageCollection, countConceptPagePoints } =
+      await import("../memory/v2/qdrant.js");
+    const { hasConceptPages } = await import("../memory/v2/page-store.js");
+    const { enqueueMemoryJob } = await import("../memory/jobs-store.js");
+
+    const { migrated } = await ensureConceptPageCollection();
+
+    let shouldReembed = migrated;
+    if (!shouldReembed) {
+      const points = await countConceptPagePoints();
+      if (points === 0 && (await hasConceptPages(getWorkspaceDir()))) {
+        shouldReembed = true;
+      }
+    }
+
+    if (shouldReembed) {
+      const jobId = enqueueMemoryJob("memory_v2_reembed", {});
+      log.info(
+        { jobId, collectionMigrated: migrated },
+        "Memory v2 collection rebuild required — enqueued reembed job",
+      );
+    }
+  } catch (err) {
+    log.warn(
+      { err },
+      "Memory v2 collection schema check failed — continuing startup; v2 retrieval may be degraded",
+    );
+  }
+}

package/src/daemon/message-types/messages.ts

@@ -147,8 +147,26 @@ export interface ToolResult {
   matchedTrustRuleId?: string;
   /** Whether the daemon is running in a containerized (Docker) environment. */
   isContainerized?: boolean;
-  /** Scope options ladder for the rule editor modal (narrowest to broadest). */
+  /**
+   * Display-only ladder of scope option labels for the rule editor
+   * (narrowest to broadest). The `pattern` here is regex-style and is
+   * NOT a valid trust rule pattern. Clients must use
+   * `riskAllowlistOptions` for the pattern that gets saved.
+   */
   riskScopeOptions?: Array<{ pattern: string; label: string }>;
+  /**
+   * Allowlist options for the rule editor save path (narrowest to
+   * broadest). Each `pattern` is a Minimatch-glob compatible string —
+   * what the gateway actually matches against. Mirrors the
+   * `allowlistOptions` field on `ConfirmationRequest`. May be absent
+   * for tools whose classifier does not produce an allowlist (e.g.
+   * web-risk classifier, MCP tools without classifier coverage).
+   */
+  riskAllowlistOptions?: Array<{
+    label: string;
+    description: string;
+    pattern: string;
+  }>;
   /** Directory scope ladder for the rule editor modal (narrowest to broadest). */
   riskDirectoryScopeOptions?: Array<{ scope: string; label: string }>;
   /** How the approval decision was reached: prompted, auto, blocked, or unknown (legacy). */

package/src/documents/document-store.ts

@@ -5,7 +5,7 @@
  * background jobs (e.g. proactive artifact generation) can persist documents
  * without going through the HTTP layer.
  */
-import { rawRun } from "../memory/raw-query.js";
+import { rawGet, rawRun } from "../memory/raw-query.js";
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("document-store");
@@ -83,3 +83,37 @@ export function saveDocument(params: {
     };
   }
 }
+
+/** Update persisted document content (append or replace). */
+export function updateDocumentContent(
+  surfaceId: string,
+  markdown: string,
+  mode: string,
+): void {
+  try {
+    const existing = rawGet<{ content: string }>(
+      /*sql*/ `SELECT content FROM documents WHERE surface_id = ?`,
+      surfaceId,
+    );
+    if (!existing) {
+      log.info({ surfaceId }, "No persisted document to update");
+      return;
+    }
+    const sep = mode === "append" && existing.content.length > 0 ? "\n\n" : "";
+    const newContent =
+      mode === "append" ? existing.content + sep + markdown : markdown;
+    const wordCount = newContent
+      .split(/\s+/)
+      .filter((w) => w.length > 0).length;
+    rawRun(
+      /*sql*/ `UPDATE documents SET content = ?, word_count = ?, updated_at = ? WHERE surface_id = ?`,
+      newContent,
+      wordCount,
+      Date.now(),
+      surfaceId,
+    );
+    log.info({ surfaceId, mode }, "Updated document content");
+  } catch (error) {
+    log.error({ err: error, surfaceId }, "Document content update error");
+  }
+}

package/src/filing/filing-service.ts

@@ -1,7 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
 import { getConfig } from "../config/loader.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import {
@@ -115,8 +114,8 @@ export class FilingService {
 
   start(): void {
     const fullConfig = getConfig();
-    if (isAssistantFeatureFlagEnabled("memory-v2-enabled", fullConfig)) {
-      log.info("Filing service disabled — memory v2 flag is set");
+    if (fullConfig.memory.v2.enabled) {
+      log.info("Filing service disabled — memory v2 is active");
       this._nextRunAt = null;
       this._nextCompactionAt = null;
       return;

package/src/heartbeat/heartbeat-service.ts

@@ -882,7 +882,7 @@ Do NOT attempt to use tools for these providers — they will fail. Skip any che
     prompt += `\n\n<heartbeat-disposition>
 This heartbeat runs frequently. Do not manufacture a report just because it ran.
 If there is nothing genuinely useful, actionable, or interesting to surface, keep the response brief and end with HEARTBEAT_OK.
-If there is something worth interrupting the guardian for, write a concise guardian-facing note first: what happened, why it matters, and the recommended next step. Then end with HEARTBEAT_ALERT. That note may be used as notification copy.
+If there is something worth interrupting the guardian for, write a concise guardian-facing note first: what happened, why it matters, and the recommended next step. Address the guardian directly as "you"; do not write instructions to yourself or another intermediary. Then end with HEARTBEAT_ALERT. That note may be used as notification copy.
 After completing your review, end your response with one of:
 - HEARTBEAT_OK — if everything looks good, no action needed
 - HEARTBEAT_ALERT — if you found issues that need attention (describe them before this marker)

package/src/ipc/assistant-server.ts

@@ -28,9 +28,13 @@
  * back to a shorter deterministic path so CLI commands can still connect.
  */
 
-import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { existsSync, unlinkSync } from "node:fs";
 import { createServer, type Server, type Socket } from "node:net";
-import { dirname } from "node:path";
+
+import {
+  ensureSocketDir,
+  SocketWatchdog,
+} from "@vellumai/ipc-server-utils";
 
 import { findLocalGuardianPrincipalId } from "../runtime/local-actor-identity.js";
 import { RouteError } from "../runtime/routes/errors.js";
@@ -130,13 +134,29 @@ function isIpcBinaryResponse(value: unknown): value is IpcBinaryResponse {
 // Server
 // ---------------------------------------------------------------------------
 
+/** Optional configuration for {@link AssistantIpcServer}. */
+export interface AssistantIpcServerOptions {
+  /**
+   * How often the socket-file watchdog stats the listening socket path.
+   * Set to `0` to disable. Defaults to {@link SocketWatchdog}'s 5000ms.
+   */
+  watchdogIntervalMs?: number;
+}
+
 export class AssistantIpcServer {
   private server: Server | null = null;
   private clients = new Set<Socket>();
   private methods = new Map<string, RouteDefinition["handler"]>();
   private socketPath: string;
+  private watchdog: SocketWatchdog;
+  /**
+   * Servers whose listener path has been replaced by a re-bind. Kept around
+   * so already-connected sockets continue to work; closed gracefully once
+   * their accept loops drain.
+   */
+  private legacyServers = new Set<Server>();
 
-  constructor() {
+  constructor(options?: AssistantIpcServerOptions) {
     const resolution = resolveIpcSocketPath("assistant");
     this.socketPath = resolution.path;
     log.info(
@@ -154,62 +174,55 @@ export class AssistantIpcServer {
     this.methods.set("db_proxy", (params) =>
       handleDbProxy(params as unknown as DbProxyParams),
     );
+
+    this.watchdog = new SocketWatchdog({
+      socketPath: this.socketPath,
+      intervalMs: options?.watchdogIntervalMs,
+      getServer: () => this.server,
+      createServer: () => this.createListeningServer(),
+      onRebind: (newServer, oldServer) => {
+        this.server = newServer;
+        this.legacyServers.add(oldServer);
+        oldServer.close(() => {
+          this.legacyServers.delete(oldServer);
+        });
+      },
+      log,
+    });
   }
 
   /** Start listening on the Unix domain socket. */
   async start(): Promise<void> {
     // Ensure the parent directory exists before listening.
-    const socketDir = dirname(this.socketPath);
-    if (!existsSync(socketDir)) {
-      mkdirSync(socketDir, { recursive: true, mode: 0o700 });
-    }
+    ensureSocketDir(this.socketPath);
 
     // Probe before unlink so a second daemon can't silently orphan an active
     // listener (Unix lets you unlink a still-bound socket file). See
     // `ensureSocketPathFree` for the behavior matrix.
     await ensureSocketPathFree(this.socketPath);
 
-    this.server = createServer((socket) => {
-      this.clients.add(socket);
-      log.debug("IPC client connected");
-
-      const reader = new IpcFrameReader(
-        (envelope, binary) =>
-          this.handleEnvelope(socket, reader, envelope, binary),
-        (err) => log.warn({ err }, "IPC frame read error"),
-      );
-
-      socket.on("data", (chunk) => {
-        reader.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-      });
-
-      socket.on("close", () => {
-        this.clients.delete(socket);
-        log.debug("IPC client disconnected");
-      });
-
-      socket.on("error", (err) => {
-        log.warn({ err }, "IPC client socket error");
-        this.clients.delete(socket);
-      });
-    });
-
-    this.server.on("error", (err) => {
-      log.error({ err }, "Assistant IPC server error");
-    });
-
+    this.server = this.createListeningServer();
     this.server.listen(this.socketPath, () => {
       log.info({ path: this.socketPath }, "Assistant IPC server listening");
     });
+
+    this.watchdog.start();
   }
 
   /** Stop the server and disconnect all clients. */
   stop(): void {
+    this.watchdog.stop();
+
     for (const client of this.clients) {
       if (!client.destroyed) client.destroy();
     }
     this.clients.clear();
 
+    for (const legacy of this.legacyServers) {
+      legacy.close();
+    }
+    this.legacyServers.clear();
+
     if (this.server) {
       this.server.close();
       this.server = null;
@@ -229,8 +242,52 @@ export class AssistantIpcServer {
     return this.socketPath;
   }
 
+  /**
+   * Re-bind the listening socket if its path entry is missing on disk.
+   *
+   * Public for tests so the watchdog can be exercised deterministically
+   * without waiting for the interval. Returns `true` when a re-bind was
+   * performed, `false` otherwise.
+   */
+  async rebindIfMissing(): Promise<boolean> {
+    return this.watchdog.rebindIfMissing();
+  }
+
   // ── Internal ──────────────────────────────────────────────────────────
 
+  private createListeningServer(): Server {
+    const server = createServer((socket) => {
+      this.clients.add(socket);
+      log.debug("IPC client connected");
+
+      const reader = new IpcFrameReader(
+        (envelope, binary) =>
+          this.handleEnvelope(socket, reader, envelope, binary),
+        (err) => log.warn({ err }, "IPC frame read error"),
+      );
+
+      socket.on("data", (chunk) => {
+        reader.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+
+      socket.on("close", () => {
+        this.clients.delete(socket);
+        log.debug("IPC client disconnected");
+      });
+
+      socket.on("error", (err) => {
+        log.warn({ err }, "IPC client socket error");
+        this.clients.delete(socket);
+      });
+    });
+
+    server.on("error", (err) => {
+      log.error({ err }, "Assistant IPC server error");
+    });
+
+    return server;
+  }
+
   private handleEnvelope(
     socket: Socket,
     reader: IpcFrameReader,