@vellumai/assistant 0.7.2 → 0.8.0

package/src/runtime/routes/debug-bash-routes.ts

@@ -0,0 +1,165 @@
+/**
+ * IPC route for executing shell commands through the assistant process.
+ *
+ * The CLI sends the command over the IPC socket and receives a single
+ * response containing stdout, stderr, and the exit code.
+ *
+ * **Security**: Gated behind VELLUM_DEBUG=1. When debug mode is off (the
+ * default), the handler returns an error immediately so the CLI surfaces a
+ * clear rejection instead of hanging. The assistant must be restarted with
+ * VELLUM_DEBUG=1 for this route to execute commands.
+ */
+
+import { spawn } from "node:child_process";
+
+import { z } from "zod";
+
+import { getIsContainerized } from "../../config/env-registry.js";
+import { buildSanitizedEnv } from "../../tools/terminal/safe-env.js";
+import { getWorkspaceDir } from "../../util/platform.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+function isDebugMode(): boolean {
+  return (
+    process.env.VELLUM_DEBUG === "1" || process.env.VELLUM_DEBUG === "true"
+  );
+}
+
+interface DebugBashResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  timedOut: boolean;
+  error?: string;
+}
+
+function handleDebugBash({ body }: RouteHandlerArgs): Promise<DebugBashResult> {
+  if (getIsContainerized()) {
+    return Promise.resolve({
+      stdout: "",
+      stderr: "",
+      exitCode: null,
+      timedOut: false,
+      error: "debug bash is not available in containerized environments",
+    });
+  }
+
+  if (!isDebugMode()) {
+    return Promise.resolve({
+      stdout: "",
+      stderr: "",
+      exitCode: null,
+      timedOut: false,
+      error:
+        "Bash debug execution is disabled. The running assistant process must have been started with VELLUM_DEBUG=1 (setting it on the CLI command alone is not enough). Restart the assistant with: vellum sleep && VELLUM_DEBUG=1 vellum wake",
+    });
+  }
+
+  const { command, timeoutMs } = body as {
+    command?: string;
+    timeoutMs?: number;
+  };
+
+  if (!command || typeof command !== "string") {
+    return Promise.resolve({
+      stdout: "",
+      stderr: "",
+      exitCode: null,
+      timedOut: false,
+      error: "command is required",
+    });
+  }
+
+  const effectiveTimeout =
+    typeof timeoutMs === "number" && timeoutMs > 0
+      ? timeoutMs
+      : DEFAULT_TIMEOUT_MS;
+
+  return new Promise<DebugBashResult>((resolve) => {
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+    let timedOut = false;
+    let settled = false;
+
+    const finish = (result: DebugBashResult) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+
+    const child = spawn("bash", ["-c", command], {
+      cwd: getWorkspaceDir(),
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: true,
+      env: buildSanitizedEnv(),
+    });
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        process.kill(-child.pid!, "SIGKILL");
+      } catch {
+        // Process group may have already exited.
+      }
+    }, effectiveTimeout);
+
+    child.stdout.on("data", (data: Buffer) => {
+      stdoutChunks.push(data);
+    });
+
+    child.stderr.on("data", (data: Buffer) => {
+      stderrChunks.push(data);
+    });
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      finish({
+        stdout: Buffer.concat(stdoutChunks).toString(),
+        stderr: Buffer.concat(stderrChunks).toString(),
+        exitCode: code,
+        timedOut,
+      });
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      finish({
+        stdout: "",
+        stderr: "",
+        exitCode: null,
+        timedOut: false,
+        error: err.message,
+      });
+    });
+  });
+}
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "debug_bash",
+    endpoint: "debug/bash",
+    method: "POST",
+    requireGuardian: false,
+    summary: "Execute a shell command in the assistant process",
+    description:
+      "Developer debugging tool. Requires the assistant to be running with VELLUM_DEBUG=1.",
+    tags: ["debug"],
+    requestBody: z.object({
+      command: z.string().describe("Shell command to execute via bash -c"),
+      timeoutMs: z
+        .number()
+        .optional()
+        .describe("Execution timeout in milliseconds (default: 30000)"),
+    }),
+    responseBody: z.object({
+      stdout: z.string(),
+      stderr: z.string(),
+      exitCode: z.number().nullable(),
+      timedOut: z.boolean(),
+      error: z.string().optional(),
+    }),
+    handler: handleDebugBash,
+  },
+];

package/src/runtime/routes/disk-pressure-routes.ts

@@ -0,0 +1,121 @@
+import { z } from "zod";
+
+import {
+  acknowledgeDiskPressureLock,
+  DISK_PRESSURE_OVERRIDE_CONFIRMATION,
+  getDiskPressureStatus,
+  overrideDiskPressureLock,
+} from "../../daemon/disk-pressure-guard.js";
+import { RouteError } from "./errors.js";
+import type { RouteDefinition } from "./types.js";
+
+const DiskPressureStatusSchema = z.object({
+  enabled: z.boolean(),
+  state: z.enum(["disabled", "ok", "critical", "unknown"]),
+  locked: z.boolean(),
+  acknowledged: z.boolean(),
+  overrideActive: z.boolean(),
+  effectivelyLocked: z.boolean(),
+  lockId: z.string().nullable(),
+  usagePercent: z.number().nullable(),
+  thresholdPercent: z.number(),
+  path: z.string().nullable(),
+  lastCheckedAt: z.string().nullable(),
+  blockedCapabilities: z.array(
+    z.enum(["agent-turns", "background-work", "remote-ingress"]),
+  ),
+  error: z.string().nullable(),
+});
+
+const DiskPressureActionResponseSchema = z.object({
+  status: DiskPressureStatusSchema,
+});
+
+const OverrideRequestSchema = z.object({
+  confirmation: z.string(),
+});
+
+function statusResponse() {
+  return { status: getDiskPressureStatus() };
+}
+
+function transitionErrorCode(
+  reason: "not_locked" | "already_acknowledged" | "already_overridden",
+): string {
+  if (reason === "not_locked") return "NOT_LOCKED";
+  if (reason === "already_acknowledged") return "ALREADY_ACKNOWLEDGED";
+  return "ALREADY_OVERRIDDEN";
+}
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "getDiskPressureStatus",
+    endpoint: "disk-pressure/status",
+    method: "GET",
+    policyKey: "disk-pressure/status",
+    requirePolicyEnforcement: true,
+    summary: "Get disk pressure status",
+    description:
+      "Return the current disk pressure status snapshot. When safe storage limits are disabled, returns a disabled status.",
+    tags: ["disk-pressure"],
+    responseBody: DiskPressureActionResponseSchema,
+    handler: () => statusResponse(),
+  },
+  {
+    operationId: "acknowledgeDiskPressure",
+    endpoint: "disk-pressure/acknowledge",
+    method: "POST",
+    policyKey: "disk-pressure/acknowledge",
+    requirePolicyEnforcement: true,
+    summary: "Acknowledge disk pressure",
+    description:
+      "Acknowledge the current disk pressure lock and enter cleanup mode without overriding assistant protections.",
+    tags: ["disk-pressure"],
+    responseBody: DiskPressureActionResponseSchema,
+    additionalResponses: {
+      "409": { description: "No active lock or lock already acknowledged." },
+    },
+    handler: () => {
+      const result = acknowledgeDiskPressureLock();
+      if (result.ok) return { status: result.status };
+      if (result.reason === "invalid_confirmation") {
+        throw new RouteError(result.message, "INVALID_CONFIRMATION", 400);
+      }
+      throw new RouteError(
+        result.message,
+        transitionErrorCode(result.reason),
+        409,
+      );
+    },
+  },
+  {
+    operationId: "overrideDiskPressure",
+    endpoint: "disk-pressure/override",
+    method: "POST",
+    policyKey: "disk-pressure/override",
+    requirePolicyEnforcement: true,
+    summary: "Override disk pressure",
+    description: `Override the current disk pressure lock only after confirming "${DISK_PRESSURE_OVERRIDE_CONFIRMATION}".`,
+    tags: ["disk-pressure"],
+    requestBody: OverrideRequestSchema,
+    responseBody: DiskPressureActionResponseSchema,
+    additionalResponses: {
+      "400": { description: "Confirmation phrase is invalid." },
+      "409": { description: "No active lock or lock already overridden." },
+    },
+    handler: ({ body }) => {
+      const parsed = OverrideRequestSchema.safeParse(body);
+      const confirmation = parsed.success ? parsed.data.confirmation : "";
+      const result = overrideDiskPressureLock(confirmation);
+      if (result.ok) return { status: result.status };
+      if (result.reason === "invalid_confirmation") {
+        throw new RouteError(result.message, "INVALID_CONFIRMATION", 400);
+      }
+      throw new RouteError(
+        result.message,
+        transitionErrorCode(result.reason),
+        409,
+      );
+    },
+  },
+];

package/src/runtime/routes/document-pdf-renderer.ts

@@ -146,8 +146,12 @@ export async function renderMarkdownToPDF(
   const pw = await importPlaywright();
   const browser = await pw.chromium.launch({ headless: true });
   try {
-    const page = await browser.newPage();
-    await page.setContent(fullHtml, { waitUntil: "networkidle" });
+    const context = await browser.newContext({
+      javaScriptEnabled: false,
+    });
+    const page = await context.newPage();
+    await page.route("**/*", (route) => route.abort());
+    await page.setContent(fullHtml, { waitUntil: "domcontentloaded" });
     const pdfBuffer = await page.pdf({
       format: "A4",
       margin: {

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

@@ -6,7 +6,8 @@
  */
 import { z } from "zod";
 
-import { rawAll, rawGet, rawRun } from "../../memory/raw-query.js";
+import { saveDocument } from "../../documents/document-store.js";
+import { rawAll, rawGet } from "../../memory/raw-query.js";
 import { getLogger } from "../../util/logger.js";
 import { renderMarkdownToPDF } from "./document-pdf-renderer.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
@@ -27,80 +28,6 @@ interface DocumentRow {
 
 type DocumentListRow = Omit<DocumentRow, "content">;
 
-// ---------------------------------------------------------------------------
-// Junction table helper
-// ---------------------------------------------------------------------------
-
-/** Insert a document–conversation association (idempotent via INSERT OR IGNORE). */
-function addDocumentConversation(
-  surfaceId: string,
-  conversationId: string,
-): void {
-  rawRun(
-    /*sql*/ `INSERT OR IGNORE INTO document_conversations (surface_id, conversation_id, created_at) VALUES (?, ?, ?)`,
-    surfaceId,
-    conversationId,
-    Date.now(),
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Shared business logic (used by both message handlers and HTTP routes)
-// ---------------------------------------------------------------------------
-
-function saveDocument(params: {
-  surfaceId: string;
-  conversationId: string;
-  title: string;
-  content: string;
-  wordCount: number;
-}): { success: true; surfaceId: string } | { success: false; error: string } {
-  try {
-    const now = Date.now();
-    rawRun(
-      `INSERT INTO documents (surface_id, conversation_id, title, content, word_count, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?)
-       ON CONFLICT(surface_id) DO UPDATE SET
-         title = excluded.title,
-         content = excluded.content,
-         word_count = excluded.word_count,
-         updated_at = excluded.updated_at`,
-      params.surfaceId,
-      params.conversationId,
-      params.title,
-      params.content,
-      params.wordCount,
-      now,
-      now,
-    );
-    log.info(
-      { surfaceId: params.surfaceId, title: params.title },
-      "Saved document",
-    );
-
-    // Best-effort: associate the document with the conversation.
-    // Failures (e.g. migration not yet applied, table missing) must not
-    // cause the save response to report failure — the document itself is
-    // already persisted at this point.
-    try {
-      addDocumentConversation(params.surfaceId, params.conversationId);
-    } catch (err) {
-      log.warn(
-        { err, surfaceId: params.surfaceId },
-        "Failed to record document–conversation association",
-      );
-    }
-
-    return { success: true, surfaceId: params.surfaceId };
-  } catch (error) {
-    log.error({ err: error, surfaceId: params.surfaceId }, "Save error");
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : "Unknown error",
-    };
-  }
-}
-
 function loadDocument(surfaceId: string):
   | {
       success: true;

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

@@ -18,14 +18,14 @@
  *   handles registration, touch (heartbeat), and unregistration (dispose).
  */
 
+import { z } from "zod";
+
 import type { HostProxyCapability } from "../../channels/types.js";
 import { parseInterfaceId, supportsHostProxy } from "../../channels/types.js";
+import { emitContactChange } from "../../contacts/contact-events.js";
 import { getOrCreateConversation } from "../../memory/conversation-key-store.js";
 import { getLogger } from "../../util/logger.js";
-import {
-  formatSseFrame,
-  formatSseHeartbeatWithData,
-} from "../assistant-event.js";
+import { formatSseFrame, formatSseHeartbeat } from "../assistant-event.js";
 import type {
   AssistantEventCallback,
   AssistantEventFilter,
@@ -35,13 +35,14 @@ import {
   AssistantEventHub,
   assistantEventHub,
 } from "../assistant-event-hub.js";
+import { resolveActorPrincipalIdForLocalGuardian } from "../local-actor-identity.js";
 import { BadRequestError, ServiceUnavailableError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("events-routes");
 
-/** Keep-alive comment sent to idle clients every 5 s by default. */
-const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
+/** Keep-alive comment sent to idle clients every 7 s by default. */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 7_000;
 
 /**
  * Stream assistant events as Server-Sent Events.
@@ -61,7 +62,7 @@ const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
  *
  * Options (for testing):
  *   hub               -- override the event hub (defaults to process singleton).
- *   heartbeatIntervalMs -- how often to emit keep-alive comments (default 5 s).
+ *   heartbeatIntervalMs -- how often to emit keep-alive comments (default 7 s).
  */
 export function handleSubscribeAssistantEvents(
   args: RouteHandlerArgs,
@@ -81,10 +82,18 @@ export function handleSubscribeAssistantEvents(
   const rawClientId = headers?.["x-vellum-client-id"];
   const rawInterfaceId = headers?.["x-vellum-interface-id"];
   const rawMachineName = headers?.["x-vellum-machine-name"];
+  const rawActorPrincipalId = headers?.["x-vellum-actor-principal-id"];
   const clientId = rawClientId?.trim() || null;
   const interfaceId = clientId
     ? parseInterfaceId(rawInterfaceId?.trim())
     : null;
+  // Verified by RuntimeHttpServer and forwarded by the http-adapter from the
+  // bearer token's AuthContext. May be absent for legacy / service-token
+  // connections that have no principal. See `resolveActorPrincipalId` for the
+  // dev-bypass translation rationale.
+  const actorPrincipalId = resolveActorPrincipalIdForLocalGuardian(
+    rawActorPrincipalId?.trim() || undefined,
+  );
 
   if (clientId && !interfaceId) {
     log.error(
@@ -171,6 +180,7 @@ export function handleSubscribeAssistantEvents(
               supportsHostProxy(interfaceId, cap),
             ),
             machineName: rawMachineName?.trim() || undefined,
+            actorPrincipalId,
           })
         : hub.subscribe({
             ...subscriberBase,
@@ -194,7 +204,7 @@ export function handleSubscribeAssistantEvents(
           return;
         }
 
-        controller.enqueue(encoder.encode(formatSseHeartbeatWithData()));
+        controller.enqueue(encoder.encode(formatSseHeartbeat()));
 
         heartbeatTimer = setInterval(() => {
           try {
@@ -206,7 +216,7 @@ export function handleSubscribeAssistantEvents(
             if (clientId) {
               hub.touchClient(clientId);
             }
-            controller.enqueue(encoder.encode(formatSseHeartbeatWithData()));
+            controller.enqueue(encoder.encode(formatSseHeartbeat()));
           } catch {
             sub.dispose();
             cleanup();
@@ -237,7 +247,29 @@ export function handleSubscribeAssistantEvents(
 // Route definitions
 // ---------------------------------------------------------------------------
 
+const EmitEventBodySchema = z.object({
+  kind: z.enum(["contacts_changed"]),
+});
+
 export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "emit_event",
+    endpoint: "events/emit",
+    method: "POST",
+    summary: "Emit an assistant event",
+    description:
+      "Trigger an in-process assistant event by kind. Used by the gateway after owning a write that the assistant runtime would normally emit.",
+    tags: ["events"],
+    requestBody: EmitEventBodySchema,
+    responseStatus: "204",
+    handler: ({ body }) => {
+      const { kind } = EmitEventBodySchema.parse(body);
+      if (kind === "contacts_changed") {
+        emitContactChange();
+      }
+      return null;
+    },
+  },
   {
     operationId: "subscribe_assistant_events",
     endpoint: "events",

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

@@ -2,14 +2,13 @@
  * Route handlers for filing management.
  *
  * `available` reflects whether the filing service is the active background
- * memory job for this instance. When the `memory-v2-enabled` flag is on,
+ * memory job for this instance. When `config.memory.v2.enabled` is true,
  * filing yields to the consolidation job (see consolidation-routes.ts) and
  * returns `available: false` so the UI can hide the row.
  */
 
 import { z } from "zod";
 
-import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getConfig } from "../../config/loader.js";
 import { FilingService } from "../../filing/filing-service.js";
 import { getLogger } from "../../util/logger.js";
@@ -19,7 +18,7 @@ import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 const log = getLogger("filing-routes");
 
 function isFilingAvailable(): boolean {
-  return !isAssistantFeatureFlagEnabled("memory-v2-enabled", getConfig());
+  return !getConfig().memory.v2.enabled;
 }
 
 // ---------------------------------------------------------------------------

package/src/runtime/routes/host-bash-routes.ts

@@ -7,6 +7,11 @@
 import { z } from "zod";
 
 import { HostBashProxy } from "../../daemon/host-bash-proxy.js";
+import {
+  enforceSameActorOrThrow,
+  SAME_ACTOR_FORBIDDEN_DESCRIPTION,
+} from "../auth/same-actor.js";
+import { resolveActorPrincipalIdForLocalGuardian } from "../local-actor-identity.js";
 import * as pendingInteractions from "../pending-interactions.js";
 import {
   BadRequestError,
@@ -37,7 +42,11 @@ function handleHostBashResult({ body, headers }: RouteHandlerArgs) {
     throw new BadRequestError("requestId is required");
   }
 
-  const submittingClientId = headers?.["x-vellum-client-id"]?.trim() || undefined;
+  const submittingClientId =
+    headers?.["x-vellum-client-id"]?.trim() || undefined;
+  const submittingActorPrincipalId = resolveActorPrincipalIdForLocalGuardian(
+    headers?.["x-vellum-actor-principal-id"]?.trim() || undefined,
+  );
 
   const peeked = pendingInteractions.get(requestId);
   if (!peeked) {
@@ -62,6 +71,18 @@ function handleHostBashResult({ body, headers }: RouteHandlerArgs) {
         `Client "${submittingClientId}" is not the target for this request (expected "${targetClientId}"). The targeted client must submit the result.`,
       );
     }
+
+    // Defense-in-depth on top of the client-id header binding above: the
+    // submitting actor's principal must match the actor principal stored
+    // for the target client at SSE subscription time. This prevents a
+    // cross-user submission even when the attacker can guess or spoof the
+    // target's client ID.
+    enforceSameActorOrThrow({
+      sourceActorPrincipalId: submittingActorPrincipalId,
+      targetActorPrincipalId: peeked.targetActorPrincipalId,
+      targetClientId,
+      op: "host_bash",
+    });
   }
 
   HostBashProxy.instance.resolveResult(requestId, {
@@ -103,8 +124,7 @@ export const ROUTES: RouteDefinition[] = [
           "x-vellum-client-id header is missing for a targeted host bash request.",
       },
       "403": {
-        description:
-          "Submitting client does not match the targeted client for this request.",
+        description: SAME_ACTOR_FORBIDDEN_DESCRIPTION,
       },
       "404": {
         description: "No pending interaction found for the given requestId.",

package/src/runtime/routes/host-cu-routes.ts

@@ -7,8 +7,18 @@
 import { z } from "zod";
 
 import { findConversation } from "../../daemon/conversation-store.js";
+import {
+  enforceSameActorOrThrow,
+  SAME_ACTOR_FORBIDDEN_DESCRIPTION,
+} from "../auth/same-actor.js";
+import { resolveActorPrincipalIdForLocalGuardian } from "../local-actor-identity.js";
 import * as pendingInteractions from "../pending-interactions.js";
-import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from "./errors.js";
+import {
+  BadRequestError,
+  ConflictError,
+  ForbiddenError,
+  NotFoundError,
+} from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 // ---------------------------------------------------------------------------
@@ -65,16 +75,34 @@ function handleHostCuResult({ body, headers }: RouteHandlerArgs) {
 
   // Validate submitting client matches the targeted client (if any).
   if (peeked.targetClientId != null) {
-    const rawClientId = (headers as Record<string, string | undefined>)?.["x-vellum-client-id"];
-    const submittingClientId = rawClientId?.trim() || undefined;
+    const headerMap = (headers as Record<string, string | undefined>) ?? {};
+    const submittingClientId =
+      headerMap["x-vellum-client-id"]?.trim() || undefined;
     if (!submittingClientId) {
-      throw new BadRequestError("x-vellum-client-id header is missing for a targeted host CU request.");
+      throw new BadRequestError(
+        "x-vellum-client-id header is missing for a targeted host CU request.",
+      );
     }
     if (submittingClientId !== peeked.targetClientId) {
       throw new ForbiddenError(
         `Client "${submittingClientId}" is not the target for this request (expected "${peeked.targetClientId}"). The targeted client must submit the result.`,
       );
     }
+
+    // Defense-in-depth: require the submitting actor's principal id to match
+    // the actor principal id captured when the target client opened its SSE
+    // stream. This prevents a different authenticated user with knowledge of
+    // both the requestId and target clientId from submitting a result on
+    // behalf of the targeted client.
+    const submittingActorPrincipalId = resolveActorPrincipalIdForLocalGuardian(
+      headerMap["x-vellum-actor-principal-id"]?.trim() || undefined,
+    );
+    enforceSameActorOrThrow({
+      sourceActorPrincipalId: submittingActorPrincipalId,
+      targetActorPrincipalId: peeked.targetActorPrincipalId,
+      targetClientId: peeked.targetClientId,
+      op: "host_cu",
+    });
   }
 
   const conversation = findConversation(peeked.conversationId);
@@ -141,8 +169,7 @@ export const ROUTES: RouteDefinition[] = [
           "x-vellum-client-id header is missing for a targeted host CU request.",
       },
       "403": {
-        description:
-          "Submitting client does not match the targeted client for this request.",
+        description: SAME_ACTOR_FORBIDDEN_DESCRIPTION,
       },
       "404": {
         description: