@vellumai/assistant 0.7.2 → 0.8.0

package/src/ipc/assistant-server.ts

@@ -28,13 +28,21 @@
  * 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";
 import { ROUTES } from "../runtime/routes/index.js";
-import type { RouteDefinition } from "../runtime/routes/types.js";
+import type {
+  RouteDefinition,
+  RouteHandlerArgs,
+} from "../runtime/routes/types.js";
 import { getLogger } from "../util/logger.js";
 import {
   type IpcEnvelope,
@@ -126,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(
@@ -150,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;
@@ -225,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,
@@ -256,7 +317,8 @@ export class AssistantIpcServer {
     void binary;
 
     try {
-      const result = handler(req.params ?? {});
+      const handlerArgs = injectLocalActorHeader(req.params);
+      const result = handler(handlerArgs);
 
       if (result instanceof Promise) {
         result
@@ -454,3 +516,52 @@ export class AssistantIpcServer {
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
+
+/**
+ * Inject a synthetic `x-vellum-actor-principal-id` header from the local
+ * guardian principal when the caller hasn't already provided one.
+ *
+ * Local IPC is intra-process and owned by the same user as the daemon, so
+ * routes that consume `headers["x-vellum-actor-principal-id"]` (e.g. the
+ * same-user filter on `GET /v1/clients`) need an actor identity to function
+ * over IPC. The HTTP adapter does this from the verified `AuthContext`
+ * (`http-adapter.ts`); this helper mirrors that convention for IPC.
+ *
+ * Existing headers from the caller (e.g. the gateway's IPC runtime proxy,
+ * which forwards real `x-vellum-*` headers from the authenticated HTTP
+ * request) are preserved — we only fill in the gap for direct CLI/local
+ * IPC callers.
+ */
+function injectLocalActorHeader(
+  params: Record<string, unknown> | undefined,
+): RouteHandlerArgs {
+  const args = (params ?? {}) as RouteHandlerArgs;
+  const existingHeaders = args.headers;
+  if (existingHeaders?.["x-vellum-actor-principal-id"]) {
+    return args;
+  }
+
+  // Defensive: the guardian lookup queries the contacts table, which may
+  // not yet exist on a very early boot path or in test fixtures that don't
+  // initialize the DB. A failure here must not block IPC dispatch — routes
+  // that require the header will fail-closed on their own.
+  let localActor: string | undefined;
+  try {
+    localActor = findLocalGuardianPrincipalId();
+  } catch (err) {
+    log.debug(
+      { err },
+      "failed to resolve local actor principal for IPC header injection",
+    );
+    return args;
+  }
+  if (!localActor) return args;
+
+  return {
+    ...args,
+    headers: {
+      ...existingHeaders,
+      "x-vellum-actor-principal-id": localActor,
+    },
+  };
+}

package/src/ipc/gateway-client.ts

@@ -38,9 +38,10 @@ const log = getLogger("gateway-ipc-client");
 export async function ipcCall(
   method: string,
   params?: Record<string, unknown>,
+  timeoutMs?: number,
 ): Promise<unknown> {
   const socketPath = getGatewaySocketPath();
-  return packageIpcCall(socketPath, method, params, log);
+  return packageIpcCall(socketPath, method, params, log, timeoutMs);
 }
 
 // ---------------------------------------------------------------------------
@@ -90,9 +91,15 @@ export function resetPersistentClient(): void {
 /**
  * Fetch all merged feature flags from the gateway via IPC.
  * Returns an empty record on any failure.
+ *
+ * @param timeoutMs - Optional timeout override forwarded to the IPC
+ *   transport. Pass a small value (e.g. 200) for CLI startup paths where
+ *   a slow/absent gateway should fail fast.
  */
-export async function ipcGetFeatureFlags(): Promise<Record<string, boolean>> {
-  const result = await ipcCall("get_feature_flags");
+export async function ipcGetFeatureFlags(
+  timeoutMs?: number,
+): Promise<Record<string, boolean>> {
+  const result = await ipcCall("get_feature_flags", undefined, timeoutMs);
   if (result && typeof result === "object" && !Array.isArray(result)) {
     const filtered: Record<string, boolean> = {};
     for (const [k, v] of Object.entries(result as Record<string, unknown>)) {
@@ -103,6 +110,33 @@ export async function ipcGetFeatureFlags(): Promise<Record<string, boolean>> {
   return {};
 }
 
+// ---------------------------------------------------------------------------
+// Velay tunnel status
+// ---------------------------------------------------------------------------
+
+export interface VelayTunnelStatus {
+  connected: boolean;
+  publicUrl: string | null;
+}
+
+/**
+ * Fetch the current Velay tunnel status from the gateway via IPC.
+ * Returns `null` when the gateway is unreachable or returns an unexpected
+ * response — callers should treat `null` as "gateway not running".
+ */
+export async function ipcGetVelayStatus(): Promise<VelayTunnelStatus | null> {
+  const result = await ipcCall("get_velay_status");
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    return null;
+  }
+  const obj = result as Record<string, unknown>;
+  if (typeof obj.connected !== "boolean") return null;
+  return {
+    connected: obj.connected,
+    publicUrl: typeof obj.publicUrl === "string" ? obj.publicUrl : null,
+  };
+}
+
 /**
  * Classify risk for a tool invocation via the gateway's persistent IPC
  * connection.

package/src/ipc/skill-server.ts

@@ -37,9 +37,13 @@
  * back to a shorter deterministic path via the shared socket-path resolver.
  */
 
-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 {
   type SkillRouteHandle,
@@ -233,6 +237,15 @@ class SkillIpcConnectionState implements SkillIpcConnection {
 // Server
 // ---------------------------------------------------------------------------
 
+/** Optional configuration for {@link SkillIpcServer}. */
+export interface SkillIpcServerOptions {
+  /**
+   * 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 SkillIpcServer {
   private server: Server | null = null;
   private clients = new Set<Socket>();
@@ -252,8 +265,15 @@ export class SkillIpcServer {
   private connections = new WeakMap<Socket, SkillIpcConnectionState>();
   private nextConnectionId = 1;
   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?: SkillIpcServerOptions) {
     const resolution = resolveSkillIpcSocketPath();
     this.socketPath = resolution.path;
     log.info(
@@ -266,6 +286,21 @@ export class SkillIpcServer {
     for (const route of skillIpcStreamingRoutes) {
       this.streamingMethods.set(route.method, route.handler);
     }
+
+    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,
+    });
   }
 
   /** Register an additional method handler after construction. */
@@ -349,17 +384,71 @@ export class SkillIpcServer {
   /** 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.server = this.createListeningServer();
+    this.server.listen(this.socketPath, () => {
+      log.info({ path: this.socketPath }, "Skill IPC server listening");
+    });
+
+    this.watchdog.start();
+  }
+
+  /** Stop the server and disconnect all clients. */
+  stop(): void {
+    this.watchdog.stop();
+
+    for (const client of this.clients) {
+      this.teardownSubscriptions(client);
+      this.teardownConnection(client);
+      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;
+    }
+
+    if (existsSync(this.socketPath)) {
+      try {
+        unlinkSync(this.socketPath);
+      } catch {
+        // Ignore
+      }
+    }
+  }
+
+  /** Get the socket path (for diagnostics). */
+  getSocketPath(): string {
+    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);
       const connection = new SkillIpcConnectionState(
         `skill-ipc-${this.nextConnectionId++}`,
@@ -406,45 +495,13 @@ export class SkillIpcServer {
       });
     });
 
-    this.server.on("error", (err) => {
+    server.on("error", (err) => {
       log.error({ err }, "Skill IPC server error");
     });
 
-    this.server.listen(this.socketPath, () => {
-      log.info({ path: this.socketPath }, "Skill IPC server listening");
-    });
-  }
-
-  /** Stop the server and disconnect all clients. */
-  stop(): void {
-    for (const client of this.clients) {
-      this.teardownSubscriptions(client);
-      this.teardownConnection(client);
-      if (!client.destroyed) client.destroy();
-    }
-    this.clients.clear();
-
-    if (this.server) {
-      this.server.close();
-      this.server = null;
-    }
-
-    if (existsSync(this.socketPath)) {
-      try {
-        unlinkSync(this.socketPath);
-      } catch {
-        // Ignore
-      }
-    }
-  }
-
-  /** Get the socket path (for diagnostics). */
-  getSocketPath(): string {
-    return this.socketPath;
+    return server;
   }
 
-  // ── Internal ──────────────────────────────────────────────────────────
-
   private handleMessage(socket: Socket, line: string): void {
     let frame: IpcRequest & { result?: unknown; error?: string };
     try {

package/src/live-voice/live-voice-archive.ts

@@ -17,7 +17,7 @@ const LIVE_VOICE_AUDIO_SOURCE = "live-voice";
 
 export type LiveVoiceAudioArchiveRole = "user" | "assistant";
 
-export type LiveVoiceAudioSource =
+type LiveVoiceAudioSource =
   | {
       type: "base64";
       dataBase64: string;
@@ -28,7 +28,7 @@ export type LiveVoiceAudioSource =
       sizeBytes?: number;
     };
 
-export interface ArchiveLiveVoiceAudioInput {
+interface ArchiveLiveVoiceAudioInput {
   messageId: string;
   sessionId: string;
   turnId: string;
@@ -55,7 +55,7 @@ export interface LiveVoiceAudioArtifactMetadata {
   archivedAt: number;
 }
 
-export type LiveVoiceAudioArchiveWarningCode =
+type LiveVoiceAudioArchiveWarningCode =
   | "archive_failed"
   | "attachment_not_found"
   | "invalid_audio_source"
@@ -591,7 +591,7 @@ type LinkLiveVoiceRolelessAudioInput = Omit<
   messageId?: string | null;
 };
 
-export interface LinkLiveVoiceAudioArtifactInput {
+interface LinkLiveVoiceAudioArtifactInput {
   messageId?: string | null;
   artifact: LiveVoiceAudioArtifactMetadata;
   position?: number;

package/src/live-voice/protocol.ts

@@ -6,8 +6,7 @@ const LIVE_VOICE_CLIENT_FRAME_TYPES = [
   "end",
 ] as const;
 
-export type LiveVoiceClientFrameType =
-  (typeof LIVE_VOICE_CLIENT_FRAME_TYPES)[number];
+type LiveVoiceClientFrameType = (typeof LIVE_VOICE_CLIENT_FRAME_TYPES)[number];
 
 const _LIVE_VOICE_SERVER_FRAME_TYPES = [
   "ready",
@@ -23,8 +22,7 @@ const _LIVE_VOICE_SERVER_FRAME_TYPES = [
   "error",
 ] as const;
 
-export type LiveVoiceServerFrameType =
-  (typeof _LIVE_VOICE_SERVER_FRAME_TYPES)[number];
+type LiveVoiceServerFrameType = (typeof _LIVE_VOICE_SERVER_FRAME_TYPES)[number];
 
 export const LiveVoiceProtocolErrorCode = {
   InvalidJson: "invalid_json",
@@ -45,7 +43,7 @@ export interface LiveVoiceProtocolError {
   readonly frameType?: string;
 }
 
-export type LiveVoiceParseResult<T> =
+type LiveVoiceParseResult<T> =
   | { ok: true; frame: T }
   | { ok: false; error: LiveVoiceProtocolError };
 
@@ -85,12 +83,12 @@ export type LiveVoiceClientFrame =
   | LiveVoiceClientInterruptFrame
   | LiveVoiceClientEndFrame;
 
-export interface LiveVoiceBinaryAudioFrame {
+interface LiveVoiceBinaryAudioFrame {
   readonly type: "binary_audio";
   readonly data: Uint8Array;
 }
 
-export interface LiveVoiceServerFrameBase {
+interface LiveVoiceServerFrameBase {
   readonly type: LiveVoiceServerFrameType;
   readonly seq: number;
 }

package/src/media/image-service.ts

@@ -76,10 +76,4 @@ export function providerForModel(
   return fallback;
 }
 
-export type {
-  GeneratedImage,
-  ImageGenCredentials,
-  ImageGenerationRequest,
-  ImageGenerationResult,
-  ImageGenProvider,
-} from "./types.js";
+export type { ImageGenCredentials } from "./types.js";

package/src/memory/__tests__/fixtures/memory-v2-activation-fixtures.ts

@@ -1,7 +1,6 @@
 import type {
   MemoryV2ConceptRowRecord,
   MemoryV2ConfigSnapshot,
-  MemoryV2SkillRowRecord,
 } from "../../memory-v2-activation-log-store.js";
 
 export const sampleConcepts: MemoryV2ConceptRowRecord[] = [
@@ -13,10 +12,28 @@ export const sampleConcepts: MemoryV2ConceptRowRecord[] = [
     simUser: 0.6,
     simAssistant: 0.4,
     simNow: 0.3,
+    simUserRerankBoost: 0,
+    simAssistantRerankBoost: 0,
+    inRerankPool: false,
     spreadContribution: 0.2,
     source: "both",
     status: "injected",
   },
+  {
+    slug: "skills/skill-1",
+    finalActivation: 0.8,
+    ownActivation: 0.8,
+    priorActivation: 0,
+    simUser: 0.5,
+    simAssistant: 0.4,
+    simNow: 0.3,
+    simUserRerankBoost: 0,
+    simAssistantRerankBoost: 0,
+    inRerankPool: false,
+    spreadContribution: 0,
+    source: "ann_top50",
+    status: "injected",
+  },
   {
     slug: "concept-b",
     finalActivation: 0.4,
@@ -25,23 +42,15 @@ export const sampleConcepts: MemoryV2ConceptRowRecord[] = [
     simUser: 0.2,
     simAssistant: 0.1,
     simNow: 0.05,
+    simUserRerankBoost: 0,
+    simAssistantRerankBoost: 0,
+    inRerankPool: false,
     spreadContribution: 0.0,
     source: "ann_top50",
     status: "not_injected",
   },
 ];
 
-export const sampleSkills: MemoryV2SkillRowRecord[] = [
-  {
-    id: "skill-1",
-    activation: 0.8,
-    simUser: 0.5,
-    simAssistant: 0.4,
-    simNow: 0.3,
-    status: "injected",
-  },
-];
-
 export const sampleConfig: MemoryV2ConfigSnapshot = {
   d: 0.85,
   c_user: 1.0,
@@ -50,6 +59,5 @@ export const sampleConfig: MemoryV2ConfigSnapshot = {
   k: 5,
   hops: 2,
   top_k: 10,
-  top_k_skills: 3,
   epsilon: 0.001,
 };