@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/monitoring/sample-ring-buffer.ts

@@ -0,0 +1,108 @@
+/**
+ * A bounded, append-only JSONL ring buffer persisted to disk.
+ *
+ * The resource monitor writes one sample per tick here so that when the
+ * container is OOM-SIGKILL'd — which resets every in-process buffer and cgroup
+ * peak — the last samples leading up to the freeze are still on the workspace
+ * volume for post-mortem inspection.
+ *
+ * Bounding is done by rotation rather than rewrite: the active file is appended
+ * to until it reaches `capacity` lines, then renamed to `<name>.1` and a fresh
+ * active file is started. At most two files exist (`<name>` + `<name>.1`), so
+ * disk stays bounded at ~2× capacity while the most recent writes always land
+ * in the active file (append is atomic per line and needs no read-modify-write,
+ * so a SIGKILL mid-run can lose at most the in-flight line).
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+} from "node:fs";
+import { dirname } from "node:path";
+
+export class SampleRingBuffer<T> {
+  private readonly activePath: string;
+  private readonly rotatedPath: string;
+  private readonly capacity: number;
+  private lineCount: number;
+
+  constructor(path: string, capacity: number) {
+    this.activePath = path;
+    this.rotatedPath = `${path}.1`;
+    this.capacity = Math.max(1, capacity);
+    mkdirSync(dirname(path), { recursive: true });
+    // Resume line accounting from a prior run so an existing active file
+    // rotates at the right point instead of growing unbounded.
+    this.lineCount = countLines(this.activePath);
+  }
+
+  append(record: T): void {
+    appendFileSync(this.activePath, `${JSON.stringify(record)}\n`);
+    this.lineCount += 1;
+    if (this.lineCount >= this.capacity) {
+      renameSync(this.activePath, this.rotatedPath);
+      this.lineCount = 0;
+    }
+  }
+
+  /**
+   * Return the most recent `limit` records (default: all retained), oldest
+   * first. Reads the rotated file then the active file so ordering is
+   * chronological across the rotation boundary. Malformed trailing lines (e.g.
+   * a half-written line from a SIGKILL) are skipped.
+   */
+  readRecent(limit?: number): T[] {
+    const records = [
+      ...parseJsonl<T>(this.rotatedPath),
+      ...parseJsonl<T>(this.activePath),
+    ];
+    if (limit != null && records.length > limit) {
+      return records.slice(records.length - limit);
+    }
+    return records;
+  }
+
+  /** The most recent record, or null when the buffer is empty. */
+  readLast(): T | null {
+    const recent = this.readRecent(1);
+    return recent.length > 0 ? recent[recent.length - 1] : null;
+  }
+}
+
+function countLines(path: string): number {
+  if (!existsSync(path)) return 0;
+  try {
+    const raw = readFileSync(path, "utf-8");
+    if (raw.length === 0) return 0;
+    let count = 0;
+    for (let i = 0; i < raw.length; i++) {
+      if (raw[i] === "\n") count += 1;
+    }
+    return count;
+  } catch {
+    return 0;
+  }
+}
+
+function parseJsonl<T>(path: string): T[] {
+  if (!existsSync(path)) return [];
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return [];
+  }
+  const out: T[] = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line) as T);
+    } catch {
+      // Skip a malformed (e.g. partially-written) line.
+    }
+  }
+  return out;
+}

package/src/monitoring/worker.ts

@@ -0,0 +1,94 @@
+/**
+ * Standalone entry point for the resource monitor as its own OS process.
+ *
+ * Spawned by `assistant monitoring start` (and at daemon startup when
+ * `monitoring.enabled` is set). Loads config, starts the sampling loop,
+ * writes a PID file, and stays alive until SIGTERM/SIGINT.
+ *
+ * Running as a separate process — off the assistant's main event loop — is the
+ * whole point: the sampler keeps recording during a main-thread freeze, and its
+ * on-disk ring buffer survives the OOM SIGKILL that resets all in-VM state.
+ */
+
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+
+import { getConfig } from "../config/loader.js";
+import { getLogger } from "../util/logger.js";
+import {
+  getMonitoringDataDir,
+  getMonitoringPidPath,
+} from "../util/platform.js";
+import {
+  type ResourceSamplerHandle,
+  startResourceSampler,
+} from "./resource-sampler.js";
+
+const log = getLogger("monitoring-worker");
+
+function cleanupPidFile(): void {
+  const pidPath = getMonitoringPidPath();
+  try {
+    if (existsSync(pidPath)) unlinkSync(pidPath);
+  } catch {
+    // best-effort
+  }
+}
+
+async function main(): Promise<void> {
+  const config = getConfig();
+  const pidPath = getMonitoringPidPath();
+
+  // Ensure the data dir exists before the PID write — the sampler's ring buffer
+  // would otherwise be the first to create it, but the PID file lands here too.
+  mkdirSync(getMonitoringDataDir(), { recursive: true });
+
+  // Write PID file so `status` and `stop` can find us.
+  writeFileSync(pidPath, String(process.pid), { flag: "w" });
+  log.info(
+    {
+      pid: process.pid,
+      pidPath,
+      sampleIntervalMs: config.monitoring.sampleIntervalMs,
+    },
+    "Resource monitor process started",
+  );
+
+  const sampler: ResourceSamplerHandle = startResourceSampler(
+    config.monitoring,
+  );
+
+  const shutdown = (signal: string) => {
+    log.info({ signal }, "Resource monitor process shutting down");
+    sampler.stop();
+    cleanupPidFile();
+    process.exit(0);
+  };
+
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+
+  process.on("uncaughtException", (err) => {
+    log.error({ err }, "Uncaught exception in resource monitor process");
+    sampler.stop();
+    cleanupPidFile();
+    process.exit(1);
+  });
+
+  process.on("unhandledRejection", (reason) => {
+    log.error({ reason }, "Unhandled rejection in resource monitor process");
+    sampler.stop();
+    cleanupPidFile();
+    process.exit(1);
+  });
+
+  process.on("exit", () => {
+    sampler.stop();
+    cleanupPidFile();
+  });
+}
+
+void main().catch((err) => {
+  log.error({ err }, "Resource monitor process failed to start");
+  cleanupPidFile();
+  process.exit(1);
+});

package/src/notifications/README.md

@@ -57,7 +57,7 @@ Hard invariants that the LLM cannot override:
 
 **Post-generation enforcement** (`decision-engine.ts`):
 
-- **Guardian question request-code enforcement** — `enforceGuardianRequestCode()` ensures request-code instructions (approve/reject or free-text answer) appear in all `guardian.question` notification copy, even when the LLM omits them.
+- **Guardian question request-code enforcement** — `enforceGuardianRequestCode()` ensures request-code instructions (approve/reject or free-text answer) appear in all `guardian.question` notification copy, even when the LLM omits them. Exception: for approval-mode questions the Slack adapter renders an interactive card with Approve/Reject buttons, so Slack copy is instead **stripped** of request-code instructions and bare code mentions (`stripGuardianRequestCodeInstructions()`).
 - **Access-request instruction enforcement** — `enforceAccessRequestInstructions()` validates that `ingress.access_request` copy contains: (1) the request-code approve/reject directive, (2) the exact "open invite flow" phrase. If any required element is missing, the full deterministic contract text is appended. This prevents model-generated copy from dropping security-critical action directives.
 
 **Pre-send gate checks** (`deterministic-checks.ts`) — these all depend on the decision, so they run here, after it:

package/src/notifications/access-request-copy.ts

@@ -7,6 +7,12 @@
 
 import { z } from "zod";
 
+import {
+  buildIntroductionActions,
+  coerceSignalBoolean,
+  type IntroductionActionOption,
+  isHandshakeOffered,
+} from "../runtime/introduction-policy.js";
 import {
   nonEmpty,
   sanitizeIdentityField,
@@ -20,8 +26,12 @@ const optStr = z
   .unknown()
   .transform((v) => (typeof v === "string" ? v : undefined));
 
-/** Accepts boolean or any other type — coerces non-true to undefined. */
-const optBool = z.unknown().transform((v) => (v === true ? true : undefined));
+/**
+ * Tri-state identity-signal boolean (see `coerceSignalBoolean`): explicit
+ * `false` is preserved as a positive platform resolution, everything
+ * non-boolean is unknown.
+ */
+const optBool = z.unknown().transform(coerceSignalBoolean);
 
 export const AccessRequestPayloadSchema = z.object({
   requestId: optStr,
@@ -36,6 +46,7 @@ export const AccessRequestPayloadSchema = z.object({
   guardianResolutionSource: optStr,
   previousMemberStatus: optStr,
   messagePreview: optStr,
+  isBot: optBool,
   isStranger: optBool,
   isRestricted: optBool,
   messageTs: optStr,
@@ -64,6 +75,11 @@ export function buildAccessRequestWarnings(
   if (p.previousMemberStatus === "revoked") {
     warnings.push("This user was previously revoked.");
   }
+  if (p.isBot) {
+    warnings.push(
+      "Bot / integration account — code verification isn't possible.",
+    );
+  }
   if (p.isStranger) {
     warnings.push("External Slack user (not in this workspace).");
   }
@@ -73,6 +89,35 @@ export function buildAccessRequestWarnings(
   return warnings;
 }
 
+// ── Introduction actions ─────────────────────────────────────────────────────
+
+/**
+ * Signal-driven introduction-card action list for a parsed access-request
+ * payload. Shared by every card renderer (Slack Card block, Telegram inline
+ * keyboard, Vellum Surface card) so the offered actions never drift between
+ * surfaces.
+ */
+export function buildIntroductionActionsForPayload(
+  p: ParsedAccessRequestPayload,
+): IntroductionActionOption[] {
+  return buildIntroductionActions(p.sourceChannel, {
+    isBot: p.isBot,
+    isStranger: p.isStranger,
+    isRestricted: p.isRestricted,
+  });
+}
+
+/** Whether the verification handshake is offered for this requester. */
+export function isHandshakeOfferedForPayload(
+  p: ParsedAccessRequestPayload,
+): boolean {
+  return isHandshakeOffered(p.sourceChannel, {
+    isBot: p.isBot,
+    isStranger: p.isStranger,
+    isRestricted: p.isRestricted,
+  });
+}
+
 // ── Slack conversation helpers ───────────────────────────────────────────────
 
 /** Slack DM conversation IDs start with `D` followed by alphanumeric chars. */
@@ -159,10 +204,14 @@ function buildMessagePreviewFromParsed(
   p: ParsedAccessRequestPayload,
 ): string | undefined {
   const raw = p.messagePreview;
-  if (!raw) return undefined;
+  if (!raw) {
+    return undefined;
+  }
 
   const sanitized = sanitizeMessagePreview(raw);
-  if (sanitized.length === 0) return undefined;
+  if (sanitized.length === 0) {
+    return undefined;
+  }
 
   return `> Their message: "${sanitized}"`;
 }
@@ -189,16 +238,28 @@ export function normalizeForDirectiveMatching(text: string): string {
     .trim();
 }
 
+/** Build a negated-lookbehind directive regex for `reply ... "CODE <verb>"`. */
+function buildCodeDirectiveRegex(escapedCode: string, verb: string): RegExp {
+  return new RegExp(
+    `(?<!not\\s)(?<!n't\\s)(?<!never\\s)reply\\b[^.!?\\n]*?"${escapedCode}\\s+${verb}"`,
+    "i",
+  );
+}
+
 /**
- * Check whether a text contains the required access-request instruction elements:
- * 1. Approve directive: Reply "CODE approve"
- * 2. Reject directive: Reply "CODE reject"
- * 3. Invite directive: Reply "open invite flow"
+ * Check whether a text contains the required access-request instruction
+ * elements for the introduction card:
+ * 1. Trust directive: Reply "CODE trust"
+ * 2. Verify directive: Reply "CODE verify" — only when the handshake is
+ *    offered for this requester (never for bots / workspace-vouched members)
+ * 3. Leave-unverified directive: Reply "CODE reject"
+ * 4. Block directive: Reply "CODE block"
+ * 5. Invite directive: Reply "open invite flow"
  *
  * Each directive is matched independently using negative lookbehind to reject
  * matches preceded by negation words ("not", "n't", "never"). This prevents
  * contradictory copy like `Do not reply "CODE reject"` from satisfying the
- * check even when a positive approve directive exists nearby.
+ * check even when a positive directive exists nearby.
  *
  * The text is normalized before matching to handle smart apostrophes and
  * multiple whitespace characters that would otherwise bypass negation detection.
@@ -206,26 +267,28 @@ export function normalizeForDirectiveMatching(text: string): string {
 export function hasAccessRequestInstructions(
   text: string | undefined,
   requestCode: string,
+  options?: { handshakeOffered?: boolean },
 ): boolean {
-  if (typeof text !== "string") return false;
+  if (typeof text !== "string") {
+    return false;
+  }
+  const handshakeOffered = options?.handshakeOffered ?? true;
   const normalized = normalizeForDirectiveMatching(text);
   const escapedCode = requestCode.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   // Each directive must follow "reply" without a preceding negation word.
   // Negative lookbehinds reject "do not reply", "don't reply", "never reply".
-  const approveRe = new RegExp(
-    `(?<!not\\s)(?<!n't\\s)(?<!never\\s)reply\\b[^.!?\\n]*?"${escapedCode}\\s+approve"`,
-    "i",
-  );
-  const rejectRe = new RegExp(
-    `(?<!not\\s)(?<!n't\\s)(?<!never\\s)reply\\b[^.!?\\n]*?"${escapedCode}\\s+reject"`,
-    "i",
-  );
+  const trustRe = buildCodeDirectiveRegex(escapedCode, "trust");
+  const verifyRe = buildCodeDirectiveRegex(escapedCode, "verify");
+  const rejectRe = buildCodeDirectiveRegex(escapedCode, "reject");
+  const blockRe = buildCodeDirectiveRegex(escapedCode, "block");
   const inviteRe =
     /(?<!not\s)(?<!n't\s)(?<!never\s)reply\b[^.!?\n]*?"open invite flow"/i;
 
   return (
-    approveRe.test(normalized) &&
+    trustRe.test(normalized) &&
+    (!handshakeOffered || verifyRe.test(normalized)) &&
     rejectRe.test(normalized) &&
+    blockRe.test(normalized) &&
     inviteRe.test(normalized)
   );
 }
@@ -237,7 +300,9 @@ export function hasAccessRequestInstructions(
  * directive should still be present.
  */
 export function hasInviteFlowDirective(text: string | undefined): boolean {
-  if (typeof text !== "string") return false;
+  if (typeof text !== "string") {
+    return false;
+  }
   const normalized = normalizeForDirectiveMatching(text);
   const inviteRe =
     /(?<!not\s)(?<!n't\s)(?<!never\s)reply\b[^.!?\n]*?"open invite flow"/i;
@@ -293,9 +358,15 @@ export function buildAccessRequestContractText(
 
   if (requestCode) {
     const code = requestCode.toUpperCase();
-    lines.push(
-      `Reply "${code} approve" to grant access or "${code} reject" to deny.`,
-    );
+    if (isHandshakeOfferedForPayload(p)) {
+      lines.push(
+        `Reply "${code} verify" to send them a verification code, "${code} trust" to trust them without one, "${code} reject" to leave them unverified, or "${code} block" to block them.`,
+      );
+    } else {
+      lines.push(
+        `Reply "${code} trust" to trust them, "${code} reject" to leave them unverified, or "${code} block" to block them.`,
+      );
+    }
   }
   lines.push(buildAccessRequestInviteDirective());
 

package/src/notifications/adapters/slack.ts

@@ -3,10 +3,10 @@
  * using native Card blocks for approval notifications.
  *
  * Approval notifications (access requests, tool approvals) render as a
- * single Slack Card block with Approve/Reject action buttons, plus
- * optional companion context blocks for details that exceed the card's
- * character limits. Non-approval notifications use standard Block Kit
- * text sections.
+ * single Slack Card block with Approve/Reject action buttons. Text that
+ * exceeds the card body's 200-character cap continues in a companion
+ * section block below the card. Non-approval notifications use standard
+ * Block Kit text sections.
  *
  * Card block reference:
  * https://docs.slack.dev/reference/block-kit/blocks/card-block
@@ -40,14 +40,41 @@ const log = getLogger("notif-adapter-slack");
 // Slack Card block builders for approval notifications
 // ---------------------------------------------------------------------------
 
-/** Build action buttons for a Slack Card block from approval metadata. */
+/** Translate a surface-agnostic emphasis into Slack's button style token. */
+function slackStyleForEmphasis(
+  emphasis: "primary" | "secondary" | "destructive",
+): { style: "primary" | "danger" } | Record<string, never> {
+  switch (emphasis) {
+    case "primary":
+      return { style: "primary" };
+    case "destructive":
+      return { style: "danger" };
+    case "secondary":
+      return {};
+  }
+}
+
+/**
+ * Build action buttons for a Slack Card block from approval metadata.
+ *
+ * Actions carrying an `emphasis` (introduction cards) render it directly, so
+ * emphasis policy stays in introduction-policy.ts. Actions without one (tool
+ * approvals) fall back to positional styling: first action `primary`,
+ * `reject` `danger`.
+ */
 function buildCardActions(approval: ApprovalUIMetadata): Button[] {
-  return approval.actions.map((action) => ({
+  return approval.actions.map((action, index) => ({
     type: "button",
     text: { type: "plain_text", text: action.label, emoji: true },
     action_id: `apr:${approval.requestId}:${action.id}`,
     value: `apr:${approval.requestId}:${action.id}`,
-    ...(action.id === "reject" ? { style: "danger" } : { style: "primary" }),
+    ...(action.emphasis
+      ? slackStyleForEmphasis(action.emphasis)
+      : action.id === "reject"
+        ? { style: "danger" }
+        : index === 0
+          ? { style: "primary" }
+          : {}),
   }));
 }
 
@@ -63,7 +90,9 @@ function buildAccessRequestSubtitle(view: AccessRequestCardView): string {
     parts.push(`(@${view.username})`);
   }
 
-  if (view.sourceChannel) parts.push(`via ${view.sourceChannel}`);
+  if (view.sourceChannel) {
+    parts.push(`via ${view.sourceChannel}`);
+  }
 
   return truncate(parts.join(" "), 150);
 }
@@ -111,7 +140,9 @@ function buildRequesterIdBlock(
   view: AccessRequestCardView,
 ): ContextBlock | undefined {
   const safeExternalId = view.externalId;
-  if (!safeExternalId) return undefined;
+  if (!safeExternalId) {
+    return undefined;
+  }
 
   if (safeExternalId === view.displayName || safeExternalId === view.username) {
     return undefined;
@@ -171,10 +202,14 @@ function buildAccessRequestCardBlocks(
   }
 
   const sourceContext = buildSourceContextBlock(view);
-  if (sourceContext) blocks.push(sourceContext);
+  if (sourceContext) {
+    blocks.push(sourceContext);
+  }
 
   const idBlock = buildRequesterIdBlock(view);
-  if (idBlock) blocks.push(idBlock);
+  if (idBlock) {
+    blocks.push(idBlock);
+  }
 
   blocks.push({
     type: "context",
@@ -204,11 +239,40 @@ function buildAccessRequestCardBlocks(
 // Tool approval card
 // ---------------------------------------------------------------------------
 
+/** Slack caps a card block's `body` text at 200 characters. */
+const CARD_BODY_MAX_LENGTH = 200;
+
+/** Marker signalling the card body continues in the section below. */
+const CARD_BODY_CONTINUATION_MARKER = " ↓";
+
+/**
+ * Split message text so the head fits Slack's card body cap (marker
+ * included) and the tail continues in a companion section below the card.
+ * Splits on the last whitespace inside the budget when there is one, so
+ * neither piece cuts mid-word. Text within the cap needs no split.
+ */
+function splitAtCardBodyLimit(text: string): { head: string; tail?: string } {
+  if (text.length <= CARD_BODY_MAX_LENGTH) {
+    return { head: text };
+  }
+
+  const budget = CARD_BODY_MAX_LENGTH - CARD_BODY_CONTINUATION_MARKER.length;
+  const window = text.slice(0, budget + 1);
+  const lastWhitespace = window.search(/\s\S*$/);
+  const cut = lastWhitespace > 0 ? lastWhitespace : budget;
+
+  return {
+    head: text.slice(0, cut).trimEnd() + CARD_BODY_CONTINUATION_MARKER,
+    tail: text.slice(cut).trimStart(),
+  };
+}
+
 /**
  * Build Slack blocks for a tool approval notification using a native Card block.
  *
  * Layout:
  *   Card — title + subtitle (tool + requester) + body (notification text) + actions
+ *   Section — continuation of body text exceeding the card's 200-char cap
  */
 function buildToolApprovalCardBlocks(
   payload: ChannelDeliveryPayload,
@@ -227,28 +291,27 @@ function buildToolApprovalCardBlocks(
     subtitle = truncate(toolName, 150);
   }
 
-  const needsOverflow = messageText.length > 200;
+  const { head, tail } = splitAtCardBodyLimit(messageText);
   const card: CardBlock = {
     type: "card",
     title: {
       type: "mrkdwn",
       text: details ? "Tool Approval" : "Approval Request",
     },
-    body: {
-      type: "mrkdwn",
-      text: needsOverflow ? truncate(messageText, 197) + " ↓" : messageText,
-    },
+    body: { type: "mrkdwn", text: head },
     actions: buildCardActions(approval),
   };
-  if (subtitle) card.subtitle = { type: "mrkdwn", text: subtitle };
+  if (subtitle) {
+    card.subtitle = { type: "mrkdwn", text: subtitle };
+  }
   blocks.push(card);
 
-  // When the message exceeds the card body limit, show the full text in a
-  // companion section so the approver can see the complete command/context.
-  if (needsOverflow) {
+  // The companion section carries only the remainder — repeating the full
+  // text would render the same message twice (once in the card, once below).
+  if (tail) {
     blocks.push({
       type: "section",
-      text: { type: "mrkdwn", text: truncate(messageText, 3000) },
+      text: { type: "mrkdwn", text: truncate(`… ${tail}`, 3000) },
     });
   }
 
@@ -305,9 +368,14 @@ export class SlackAdapter implements ChannelAdapter {
     const messageText = resolveMessageText(payload);
 
     try {
+      // `approval` rides along with the prebuilt card blocks so the send
+      // layer treats a rejected Block Kit payload as an approval prompt:
+      // its block-free retry re-attaches `plainTextFallback` reply
+      // instructions instead of posting text with no way to respond.
       const result = payload.approvalContext
         ? await sendSlackReply(chatId, messageText, {
             blocks: buildApprovalNotificationBlocks(payload, messageText),
+            approval: payload.approvalContext,
           })
         : await sendSlackReply(chatId, messageText, { useBlocks: true });