@vellumai/assistant 0.7.3 → 0.8.0

package/src/notifications/copy-composer.ts

@@ -32,6 +32,51 @@ export function nonEmpty(value: string | undefined): string | undefined {
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
+export function looksLikeIntermediaryInstruction(text: string): boolean {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  const intermediaryAction =
+    "(?:tell|telling|ask|asking|remind|reminding|nudge|nudging|prompt|prompting|notify|notifying|encourage|encouraging|prime|priming|brief|briefing|coach|coaching)";
+  const target = "(?:the\\s+)?(?:guardian|recipient|user)";
+  return (
+    /\b(?:assistant|agent|system|model|watcher)\s+(?:should|needs?\s+to|must|can|could)\b/i.test(
+      normalized,
+    ) ||
+    new RegExp(
+      `\\b(?:consider|try|please)\\s+${intermediaryAction}\\s+${target}\\b`,
+      "i",
+    ).test(normalized) ||
+    new RegExp(
+      `\\b${intermediaryAction}\\s+${target}\\s+(?:to|that|about|with)\\b`,
+      "i",
+    ).test(normalized) ||
+    new RegExp(
+      `\\b${target}\\s+(?:should|needs?\\s+to|must|might\\s+want\\s+to)\\b`,
+      "i",
+    ).test(normalized) ||
+    new RegExp(`\\b(?:for|to)\\s+${target}\\s+to\\b`, "i").test(normalized)
+  );
+}
+
+function buildHeartbeatAlertCopy(
+  payload: Record<string, unknown>,
+): RenderedChannelCopy {
+  const summary = str(
+    payload.summary,
+    str(payload.body, "Your assistant found something worth your attention."),
+  ).trim();
+  const safePopupBody = looksLikeIntermediaryInstruction(summary)
+    ? "I found something worth your attention in a heartbeat check. Open the conversation for details."
+    : summary;
+
+  return {
+    title: str(payload.title, "Heartbeat Alert"),
+    body: safePopupBody,
+    deliveryText: safePopupBody,
+    conversationTitle: str(payload.conversationTitle, "Heartbeat"),
+    conversationSeedMessage: summary,
+  };
+}
+
 // ── Access-request copy contract ─────────────────────────────────────────────
 //
 // Deterministic helpers for building guardian-facing access-request copy.
@@ -505,18 +550,7 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
     body: str(payload.body, "A watcher event requires your attention"),
   }),
 
-  "heartbeat.alert": (payload) => {
-    const body = str(
-      payload.summary,
-      str(payload.body, "Your assistant found something worth your attention."),
-    );
-    return {
-      title: str(payload.title, "Heartbeat Alert"),
-      body,
-      conversationTitle: str(payload.conversationTitle, "Heartbeat"),
-      conversationSeedMessage: body,
-    };
-  },
+  "heartbeat.alert": buildHeartbeatAlertCopy,
 
   "tool_confirmation.required_action": (payload) => ({
     title: "Tool Confirmation",

package/src/notifications/decision-engine.ts

@@ -35,6 +35,7 @@ import {
   composeFallbackCopy,
   hasAccessRequestInstructions,
   hasInviteFlowDirective,
+  looksLikeIntermediaryInstruction,
 } from "./copy-composer.js";
 import { createDecision } from "./decisions-store.js";
 import {
@@ -127,11 +128,13 @@ function buildSystemPrompt(
     ``,
     `Copy guidelines (three distinct outputs):`,
     `- \`title\` and \`body\` are for native notification popups (e.g. vellum desktop/mobile) — keep them short and glanceable (title ≤ 8 words, body ≤ 2 sentences).`,
+    `  - Write popup copy as final copy for the guardian or recipient. Do not write instructions for the assistant or another intermediary.`,
     `- \`deliveryText\` is the channel-native message for chat channels (e.g. telegram). It must read naturally as a standalone message.`,
     `  - Do not prepend mechanical labels like "Conversation:".`,
     `  - Do not mention channel or transport names (e.g. Telegram, Slack, email) unless the event context explicitly requires it.`,
     `  - Do not repeat title/body verbatim unless that repetition is truly necessary.`,
     `  - Avoid meta-send phrasing (e.g. "I'd like to send a notification", "May I go ahead with that?"). Write the recipient-facing message directly.`,
+    `  - Avoid intermediary-instruction phrasing like "consider telling the guardian", "ask the recipient to", or "the assistant should remind them". Rewrite it as final copy the recipient can act on directly.`,
     `  - For telegram: 1-2 concise sentences.`,
     `- \`conversationSeedMessage\` is the opening message in the internal notification conversation — it can be richer and more contextual.`,
     `  - For vellum (desktop): 2-4 short sentences with useful context and clear next step if action is required.`,
@@ -664,6 +667,47 @@ function enforceAccessRequestInstructions(
   };
 }
 
+function enforceHeartbeatAlertCopy(
+  decision: NotificationDecision,
+  signal: NotificationSignal,
+): NotificationDecision {
+  if (signal.sourceEventName !== "heartbeat.alert") return decision;
+  if (!decision.shouldNotify || decision.selectedChannels.length === 0)
+    return decision;
+
+  const fallbackCopy = composeFallbackCopy(signal, decision.selectedChannels);
+  const nextCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>> = {
+    ...decision.renderedCopy,
+  };
+
+  for (const channel of decision.selectedChannels) {
+    const currentCopy = nextCopy[channel];
+    if (
+      currentCopy &&
+      !heartbeatCopyLooksLikeIntermediaryInstruction(currentCopy)
+    ) {
+      continue;
+    }
+    const safeCopy = fallbackCopy[channel];
+    if (!safeCopy) continue;
+    nextCopy[channel] = safeCopy;
+  }
+
+  return {
+    ...decision,
+    renderedCopy: nextCopy,
+  };
+}
+
+function heartbeatCopyLooksLikeIntermediaryInstruction(
+  copy: RenderedChannelCopy,
+): boolean {
+  return [copy.title, copy.body, copy.deliveryText].some(
+    (value) =>
+      typeof value === "string" && looksLikeIntermediaryInstruction(value),
+  );
+}
+
 function ensureAccessRequestInstructionsInCopy(
   copy: RenderedChannelCopy,
   requestCode: string,
@@ -754,6 +798,7 @@ export async function evaluateSignal(
     let decision = buildFallbackDecision(signal, availableChannels);
     decision = enforceGuardianRequestCode(decision, signal);
     decision = enforceAccessRequestInstructions(decision, signal);
+    decision = enforceHeartbeatAlertCopy(decision, signal);
     decision = enforceGuardianCallConversationAffinity(decision, signal);
     decision = enforceConversationAffinity(
       decision,
@@ -783,6 +828,7 @@ export async function evaluateSignal(
 
   decision = enforceGuardianRequestCode(decision, signal);
   decision = enforceAccessRequestInstructions(decision, signal);
+  decision = enforceHeartbeatAlertCopy(decision, signal);
   decision = enforceGuardianCallConversationAffinity(decision, signal);
   decision = enforceConversationAffinity(
     decision,

package/src/permissions/gateway-threshold-reader.ts

@@ -44,6 +44,106 @@ const conversationThresholdCache = new Map<
 >();
 const CONVERSATION_CACHE_TTL_MS = 5_000;
 
+// ── Failure-coalescing log helper ────────────────────────────────────────────
+// When the gateway IPC socket is broken (e.g. the path was unlinked from
+// disk), every threshold lookup fails with ENOENT on the hot path. Without
+// coalescing the per-call WARN drowns the actual signal ("Strict-when-
+// Relaxed because the gateway lost its socket") in its own log spam.
+//
+// Each `op` (e.g. "conversation_threshold", "global_thresholds") emits at
+// most one WARN per {@link DEFAULT_FAILURE_WARN_INTERVAL_MS} window. The
+// first failure in a streak WARNs immediately so failures aren't lost. When
+// the IPC starts working again, an INFO records the streak duration and
+// how many calls were swallowed — that's the cue dashboards should alert
+// on.
+
+interface FailureState {
+  consecutiveFailures: number;
+  firstFailureAt: number;
+  lastWarnAt: number;
+}
+
+const DEFAULT_FAILURE_WARN_INTERVAL_MS = 30_000;
+let failureWarnIntervalMs = DEFAULT_FAILURE_WARN_INTERVAL_MS;
+const failureStateByOp = new Map<string, FailureState>();
+
+function noteFailure(
+  op: string,
+  fields: Record<string, unknown>,
+  message: string,
+): void {
+  const now = Date.now();
+  const state = failureStateByOp.get(op);
+  if (!state) {
+    failureStateByOp.set(op, {
+      consecutiveFailures: 1,
+      firstFailureAt: now,
+      lastWarnAt: now,
+    });
+    log.warn(
+      {
+        ...fields,
+        op,
+        consecutiveFailures: 1,
+        event: "ipc_threshold_failure",
+      },
+      message,
+    );
+    return;
+  }
+  state.consecutiveFailures += 1;
+  if (now - state.lastWarnAt >= failureWarnIntervalMs) {
+    log.warn(
+      {
+        ...fields,
+        op,
+        consecutiveFailures: state.consecutiveFailures,
+        streakDurationMs: now - state.firstFailureAt,
+        event: "ipc_threshold_failure",
+      },
+      message,
+    );
+    state.lastWarnAt = now;
+  }
+}
+
+function noteSuccess(op: string): void {
+  const state = failureStateByOp.get(op);
+  if (!state) return;
+  log.info(
+    {
+      op,
+      swallowedFailures: state.consecutiveFailures,
+      streakDurationMs: Date.now() - state.firstFailureAt,
+      event: "ipc_threshold_recovered",
+    },
+    "Gateway IPC threshold call recovered after failure streak",
+  );
+  failureStateByOp.delete(op);
+}
+
+/** Test-only: clear the failure-coalescing state. */
+export function _resetFailureCoalesceForTesting(): void {
+  failureStateByOp.clear();
+  failureWarnIntervalMs = DEFAULT_FAILURE_WARN_INTERVAL_MS;
+}
+
+/**
+ * Test-only: read a snapshot of the failure-coalescing state for a given
+ * op. Returns `undefined` when no streak is in progress.
+ */
+export function _getFailureStateForTesting(
+  op: string,
+): Readonly<FailureState> | undefined {
+  const state = failureStateByOp.get(op);
+  return state ? { ...state } : undefined;
+}
+
+/** Test-only: override the WARN cadence. Pass {@link DEFAULT_FAILURE_WARN_INTERVAL_MS} to reset. */
+export function _setFailureWarnIntervalForTesting(intervalMs: number): void {
+  failureWarnIntervalMs = intervalMs;
+}
+
 /**
  * Clear the global threshold cache. Exported for testing.
  */
@@ -112,18 +212,24 @@ export async function getAutoApproveThreshold(
       })) as ConversationThreshold | null | undefined;
 
       if (result === undefined) {
-        log.warn(
+        noteFailure(
+          "conversation_threshold",
           { conversationId },
           "IPC call failed for conversation threshold override, falling through to global",
         );
         // Fall through to global threshold fetch below.
-      } else if (result && isValidThreshold(result.threshold)) {
-        conversationThresholdCache.set(conversationId, {
-          threshold: result.threshold,
-          timestamp: Date.now(),
-        });
-        return result.threshold;
       } else {
+        // Any defined response (including a null "no override") is a
+        // successful round-trip — clear any in-progress failure streak so
+        // dashboards see the recovery.
+        noteSuccess("conversation_threshold");
+        if (result && isValidThreshold(result.threshold)) {
+          conversationThresholdCache.set(conversationId, {
+            threshold: result.threshold,
+            timestamp: Date.now(),
+          });
+          return result.threshold;
+        }
         // result === null (or an unexpected shape) — cache the negative result
         // and fall through to global defaults.
         conversationThresholdCache.set(conversationId, {
@@ -151,7 +257,8 @@ export async function getAutoApproveThreshold(
   } catch (err) {
     // Gateway unreachable — default to "none" (Strict) so no tools are
     // silently auto-approved when the gateway is down.
-    log.warn(
+    noteFailure(
+      "global_thresholds",
       { error: String(err) },
       "Failed to fetch global thresholds, defaulting to none",
     );
@@ -176,6 +283,7 @@ async function fetchGlobalThresholds(): Promise<GlobalThresholds> {
     throw new Error("Gateway IPC returned no result for global thresholds");
   }
 
+  noteSuccess("global_thresholds");
   cachedGlobalThresholds = result;
   cachedGlobalTimestamp = Date.now();
   return result;

package/src/permissions/prompter.ts

@@ -11,19 +11,14 @@ import type { AllowlistOption, ScopeOption, UserDecision } from "./types.js";
 
 const log = getLogger("permission-prompter");
 
-interface PendingPrompt {
-  resolve: (value: {
-    decision: UserDecision;
-    selectedPattern?: string;
-    selectedScope?: string;
-    decisionContext?: string;
-    wasTimeout?: boolean;
-    wasSystemCancel?: boolean;
-  }) => void;
-  reject: (reason: Error) => void;
-  timer: ReturnType<typeof setTimeout>;
-  toolUseId?: string;
-}
+type ConfirmResult = {
+  decision: UserDecision;
+  selectedPattern?: string;
+  selectedScope?: string;
+  decisionContext?: string;
+  wasTimeout?: boolean;
+  wasSystemCancel?: boolean;
+};
 
 export type ConfirmationStateCallback = (
   requestId: string,
@@ -33,7 +28,13 @@ export type ConfirmationStateCallback = (
 ) => void;
 
 export class PermissionPrompter {
-  private pending = new Map<string, PendingPrompt>();
+  /**
+   * Tracks which requestIds belong to this prompter instance so that
+   * denyAllPending / dispose can scope their cleanup to this conversation.
+   * The full per-request state (callbacks, timer, toolUseId) lives in
+   * pendingInteractions, matching the host proxy pattern.
+   */
+  private ownedIds = new Set<string>();
   private sendToClient: (msg: ServerMessage) => void;
   private onStateChanged?: ConfirmationStateCallback;
 
@@ -69,74 +70,68 @@ export class PermissionPrompter {
     riskReason?: string,
     isContainerized?: boolean,
     directoryScopeOptions?: readonly { scope: string; label: string }[],
-  ): Promise<{
-    decision: UserDecision;
-    selectedPattern?: string;
-    selectedScope?: string;
-    decisionContext?: string;
-    wasTimeout?: boolean;
-    wasSystemCancel?: boolean;
-    wasAbort?: boolean;
-  }> {
+  ): Promise<ConfirmResult & { wasAbort?: boolean }> {
     if (signal?.aborted) return { decision: "deny", wasAbort: true };
 
     const requestId = uuid();
 
-    // Self-register in pendingInteractions so /v1/confirm can route the
-    // response to this conversation without going through broadcastMessage.
-    if (conversationId) {
-      pendingInteractions.register(requestId, {
-        conversationId,
-        kind: "confirmation",
-        confirmationDetails: {
-          toolName,
-          input: redactSensitiveFields(input),
-          riskLevel,
-          executionTarget,
-          allowlistOptions: allowlistOptions.map((o) => ({
-            label: o.label,
-            description: o.description,
-            pattern: o.pattern,
-          })),
-          scopeOptions: scopeOptions.map((o) => ({
-            label: o.label,
-            scope: o.scope,
-          })),
-          persistentDecisionsAllowed: persistentDecisionsAllowed ?? true,
-        },
-      });
-    }
-
     return new Promise((resolve, reject) => {
       const timeoutMs = getConfig().timeouts.permissionTimeoutSec * 1000;
+
       const timer = setTimeout(() => {
-        this.pending.delete(requestId);
-        pendingInteractions.resolve(requestId);
+        const interaction = pendingInteractions.resolve(requestId);
+        this.ownedIds.delete(requestId);
         log.warn(
           { requestId, toolName },
           "Permission prompt timed out, defaulting to deny",
         );
         this.onStateChanged?.(requestId, "timed_out", "timeout", toolUseId);
-        resolve({
-          decision: "deny",
-          wasTimeout: true,
-          decisionContext: `The permission prompt for the "${toolName}" tool timed out. The user did not explicitly deny this request — they may have been away or busy. You may retry this tool call if it is still needed for the current task.`,
-        });
+        (interaction?.rpcResolve as ((v: ConfirmResult) => void) | undefined)?.(
+          {
+            decision: "deny",
+            wasTimeout: true,
+            decisionContext: `The permission prompt for the "${toolName}" tool timed out. The user did not explicitly deny this request — they may have been away or busy. You may retry this tool call if it is still needed for the current task.`,
+          },
+        );
       }, timeoutMs);
 
-      this.pending.set(requestId, {
-        resolve,
-        reject,
-        timer,
-        toolUseId,
-      });
+      // Register all lifecycle state in pendingInteractions — same pattern as
+      // host proxies. The prompter tracks ownership via ownedIds.
+      // Always register unconditionally so rpcResolve/rpcReject/timer
+      // are reachable by resolveConfirmation, denyAllPending, and the timeout
+      // handler even when conversationId is absent. Routes return 404 for
+      // interactions with an empty conversationId, which is correct behaviour.
+      pendingInteractions.register(requestId, {
+        conversationId: conversationId ?? "",
+        kind: "confirmation",
+          confirmationDetails: {
+            toolName,
+            input: redactSensitiveFields(input),
+            riskLevel,
+            executionTarget,
+            allowlistOptions: allowlistOptions.map((o) => ({
+              label: o.label,
+              description: o.description,
+              pattern: o.pattern,
+            })),
+            scopeOptions: scopeOptions.map((o) => ({
+              label: o.label,
+              scope: o.scope,
+            })),
+            persistentDecisionsAllowed: persistentDecisionsAllowed ?? true,
+          },
+          rpcResolve: resolve as (value: unknown) => void,
+          rpcReject: reject,
+          timer,
+          toolUseId,
+        });
+      this.ownedIds.add(requestId);
 
       if (signal) {
         const onAbort = () => {
-          if (this.pending.has(requestId)) {
-            clearTimeout(timer);
-            this.pending.delete(requestId);
+          if (this.ownedIds.has(requestId)) {
             pendingInteractions.resolve(requestId);
+            this.ownedIds.delete(requestId);
             resolve({ decision: "deny", wasAbort: true });
           }
         };
@@ -175,17 +170,17 @@ export class PermissionPrompter {
   }
 
   hasPendingRequest(requestId: string): boolean {
-    return this.pending.has(requestId);
+    return this.ownedIds.has(requestId);
   }
 
   /** Returns all currently pending request IDs. */
   getPendingRequestIds(): string[] {
-    return [...this.pending.keys()];
+    return [...this.ownedIds];
   }
 
   /** Returns the toolUseId associated with a pending request, if any. */
   getToolUseId(requestId: string): string | undefined {
-    return this.pending.get(requestId)?.toolUseId;
+    return pendingInteractions.get(requestId)?.toolUseId;
   }
 
   resolveConfirmation(
@@ -195,22 +190,17 @@ export class PermissionPrompter {
     selectedScope?: string,
     decisionContext?: string,
   ): void {
-    const pending = this.pending.get(requestId);
-    if (!pending) {
+    if (!this.ownedIds.has(requestId)) {
       log.warn({ requestId }, "No pending prompt for confirmation response");
       return;
     }
-    clearTimeout(pending.timer);
-    this.pending.delete(requestId);
-    // Idempotent — approval-routes already calls pendingInteractions.resolve()
-    // before routing here, but we call it defensively for non-route paths.
-    pendingInteractions.resolve(requestId);
-    pending.resolve({
-      decision,
-      selectedPattern,
-      selectedScope,
-      decisionContext,
-    });
+    // The prompter owns deregistration; all callers use get() to peek before
+    // routing to resolveConfirmation, which fires the rpcResolve callback.
+    const interaction = pendingInteractions.resolve(requestId);
+    this.ownedIds.delete(requestId);
+    (interaction?.rpcResolve as ((v: ConfirmResult) => void) | undefined)?.(
+      { decision, selectedPattern, selectedScope, decisionContext },
+    );
   }
 
   /**
@@ -219,31 +209,31 @@ export class PermissionPrompter {
    * see the denial and can re-request if still needed.
    */
   denyAllPending(): void {
-    for (const [requestId, pending] of this.pending) {
-      clearTimeout(pending.timer);
-      this.pending.delete(requestId);
-      pendingInteractions.resolve(requestId);
-      pending.resolve({
-        decision: "deny",
-        wasSystemCancel: true,
-        decisionContext:
-          "The user sent a new message instead of responding to this permission prompt. Stop what you are doing and respond to the user's new message. Do NOT retry this tool or request permission again until the user asks you to.",
-      });
+    for (const requestId of [...this.ownedIds]) {
+      const interaction = pendingInteractions.resolve(requestId);
+      this.ownedIds.delete(requestId);
+      (interaction?.rpcResolve as ((v: ConfirmResult) => void) | undefined)?.(
+        {
+          decision: "deny",
+          wasSystemCancel: true,
+          decisionContext:
+            "The user sent a new message instead of responding to this permission prompt. Stop what you are doing and respond to the user's new message. Do NOT retry this tool or request permission again until the user asks you to.",
+        },
+      );
     }
   }
 
   get hasPending(): boolean {
-    return this.pending.size > 0;
+    return this.ownedIds.size > 0;
   }
 
   dispose(): void {
-    for (const [requestId, pending] of this.pending) {
-      clearTimeout(pending.timer);
-      pendingInteractions.resolve(requestId);
-      pending.reject(
+    for (const requestId of [...this.ownedIds]) {
+      const interaction = pendingInteractions.resolve(requestId);
+      this.ownedIds.delete(requestId);
+      interaction?.rpcReject?.(
         new AssistantError("Prompter disposed", ErrorCode.INTERNAL_ERROR),
       );
     }
-    this.pending.clear();
   }
 }