@vellumai/assistant 0.11.8 → 0.11.9-staging.2

package/src/notifications/guardian-question-mode.ts

@@ -15,6 +15,8 @@ import { z } from "zod";
 import { externalSourceLinkSchema } from "../messaging/channel-binding-schema.js";
 import { isSlackDmConversation } from "../messaging/providers/slack/message-metadata.js";
 import { nonEmpty } from "./notification-utils.js";
+import type { NotificationSignal } from "./signal.js";
+import type { NotificationChannel, RenderedChannelCopy } from "./types.js";
 
 // ── Schema primitives ──────────────────────────────────────────────────
 
@@ -630,10 +632,6 @@ export function hasGuardianRequestCodeInstruction(
   }
 }
 
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
 function normalizeInstructionText(value: string): string {
   return value
     .replace(/[ \t]+\n/g, "\n")
@@ -660,7 +658,7 @@ export function stripConflictingGuardianRequestInstructions(
   requestCode: string,
   mode: GuardianQuestionInstructionMode,
 ): string {
-  const escapedCode = escapeRegExp(requestCode);
+  const escapedCode = RegExp.escape(requestCode);
   const next =
     mode === "answer"
       ? text.replace(buildApprovalInstructionPattern(escapedCode), "")
@@ -679,7 +677,7 @@ export function stripGuardianRequestCodeInstructions(
   text: string,
   requestCode: string,
 ): string {
-  const escapedCode = escapeRegExp(requestCode);
+  const escapedCode = RegExp.escape(requestCode);
   const next = text
     .replace(buildApprovalInstructionPattern(escapedCode), "")
     .replace(buildAnswerInstructionPattern(escapedCode), "")
@@ -712,6 +710,149 @@ export function parseInteractiveApprovalPayload(
   return nonEmpty(parsed.requestId) ? parsed : null;
 }
 
+// ── Reply mechanics per channel ─────────────────────────────────────────
+
+/**
+ * Whether a channel's rendered guardian-request copy carries request-code
+ * reply mechanics (`Reference code: X. Reply "X <your answer>".` and its
+ * approval-mode twin). Decided by where that channel's copy is read:
+ *
+ * - `vellum`: the notification bell's detail, the OS banner, and the
+ *   delivery audit row. The conversation gets the card
+ *   (`seedContentBlocks`), which carries its own text fallback. None of
+ *   these takes a typed reply; the guardian acts through the card or the
+ *   conversation it points at.
+ * - `platform`: a push banner mirroring the vellum copy.
+ * - `slack`, for payloads that render Approve/Reject buttons
+ *   (`resolveApprovalContext` in broadcaster.ts, gated on the same
+ *   {@link parseInteractiveApprovalPayload}).
+ *
+ * Every other channel is a text chat where "CODE <reply>" is how a guardian
+ * answers, so its copy has to carry the instruction even when the composed
+ * copy left it out. A newly deliverable channel lands here by default,
+ * which keeps its text answerable until it grows a card.
+ */
+export function guardianCopyCarriesReplyMechanics(
+  channel: NotificationChannel,
+  payload: Record<string, unknown>,
+): boolean {
+  switch (channel) {
+    case "vellum":
+    case "platform":
+      return false;
+    case "slack":
+      return parseInteractiveApprovalPayload(payload) == null;
+    default:
+      return true;
+  }
+}
+
+function ensureGuardianRequestCodeInCopy(
+  copy: RenderedChannelCopy,
+  requestCode: string,
+  mode: GuardianQuestionInstructionMode,
+): RenderedChannelCopy {
+  const instruction = buildGuardianRequestCodeInstruction(requestCode, mode);
+
+  const ensureText = (text: string | undefined): string => {
+    const base = typeof text === "string" ? text.trim() : "";
+    const sanitized = stripConflictingGuardianRequestInstructions(
+      base,
+      requestCode,
+      mode,
+    );
+    if (hasGuardianRequestCodeInstruction(sanitized, requestCode, mode)) {
+      return sanitized;
+    }
+    return sanitized.length > 0
+      ? `${sanitized}\n\n${instruction}`
+      : instruction;
+  };
+
+  return {
+    ...copy,
+    body: ensureText(copy.body),
+    deliveryText: copy.deliveryText
+      ? ensureText(copy.deliveryText)
+      : copy.deliveryText,
+    conversationSeedMessage: copy.conversationSeedMessage
+      ? ensureText(copy.conversationSeedMessage)
+      : copy.conversationSeedMessage,
+  };
+}
+
+/**
+ * A field that was nothing but the instruction becomes the request's own
+ * question text, the producer's human-readable ask, so a card surface never
+ * shows the mechanics it exists to avoid. Without one it keeps its original
+ * text rather than becoming empty: downstream treats an empty body as
+ * missing copy.
+ */
+function stripGuardianRequestCodeInCopy(
+  copy: RenderedChannelCopy,
+  requestCode: string,
+  fallbackText: string | undefined,
+): RenderedChannelCopy {
+  const strip = (text: string): string => {
+    const stripped = stripGuardianRequestCodeInstructions(text, requestCode);
+    return stripped.length > 0 ? stripped : (fallbackText ?? text);
+  };
+  // A title is a headline, never the ask, so a code-only title keeps its
+  // text rather than taking the question.
+  const strippedTitle = stripGuardianRequestCodeInstructions(
+    copy.title,
+    requestCode,
+  );
+
+  return {
+    ...copy,
+    title: strippedTitle.length > 0 ? strippedTitle : copy.title,
+    body: strip(copy.body),
+    deliveryText: copy.deliveryText
+      ? strip(copy.deliveryText)
+      : copy.deliveryText,
+    conversationSeedMessage: copy.conversationSeedMessage
+      ? strip(copy.conversationSeedMessage)
+      : copy.conversationSeedMessage,
+  };
+}
+
+/**
+ * Apply the reply-mechanics rule to one channel's copy of a
+ * `guardian.question` signal: enforce the request-code instruction into
+ * copy the guardian answers by typing, strip it (model-authored code
+ * phrasing included) from copy that acts through a card. Any other signal
+ * passes through untouched. Idempotent, so the template composer and the
+ * decision engine can both apply it and the result is the same whichever
+ * path rendered the copy.
+ */
+export function applyGuardianReplyMechanics(
+  copy: RenderedChannelCopy,
+  channel: NotificationChannel,
+  signal: Pick<NotificationSignal, "sourceEventName" | "contextPayload">,
+): RenderedChannelCopy {
+  if (signal.sourceEventName !== "guardian.question") {
+    return copy;
+  }
+  const rawCode = signal.contextPayload.requestCode;
+  if (typeof rawCode !== "string" || rawCode.trim().length === 0) {
+    return copy;
+  }
+  const requestCode = rawCode.trim().toUpperCase();
+  if (!guardianCopyCarriesReplyMechanics(channel, signal.contextPayload)) {
+    const questionText = signal.contextPayload.questionText;
+    return stripGuardianRequestCodeInCopy(
+      copy,
+      requestCode,
+      typeof questionText === "string" ? nonEmpty(questionText) : undefined,
+    );
+  }
+  const { mode } = resolveGuardianQuestionInstructionMode(
+    signal.contextPayload,
+  );
+  return ensureGuardianRequestCodeInCopy(copy, requestCode, mode);
+}
+
 /**
  * Resolve guardian reply instruction mode from a raw context payload.
  *

package/src/notifications/notification-utils.ts

@@ -9,8 +9,9 @@
 import type { Root, RootContent } from "mdast";
 
 import { parseMarkdown } from "../messaging/content/parse.js";
-import { stripAnsiAndControlChars } from "../util/ansi.js";
+import { stripAnsiAndControlChars, stripAnsiSequences } from "../util/ansi.js";
 import { isPlainObject } from "../util/object.js";
+import type { RenderedChannelCopy } from "./types.js";
 
 // ── String helpers ──────────────────────────────────────────────────────────
 
@@ -237,6 +238,40 @@ function sanitize(value: string, maxLength: number): string {
   return truncate(stripAnsiAndControlChars(value, " ").trim(), maxLength);
 }
 
+/**
+ * Collapse horizontal whitespace and blank-line runs while keeping paragraph
+ * breaks. Tabs become spaces. Three or more consecutive newlines collapse to
+ * one blank line so padding does not eat the preview budget.
+ */
+export function collapseHorizontalWhitespace(value: string): string {
+  return value
+    .replace(/[^\S\n]+/g, " ")
+    .replace(/ *\n */g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+/**
+ * Sanitize a notification body that should keep its line breaks.
+ *
+ * ANSI sequences and non-newline control characters are stripped; `\r\n` and
+ * `\r` become `\n`. Horizontal whitespace is collapsed. The result is clamped
+ * to {@link MESSAGE_PREVIEW_MAX_LENGTH}.
+ *
+ * Single-line surfaces (titles, identity fields, channel previews that must
+ * not wrap) should keep using {@link sanitizeMessagePreview}.
+ */
+export function sanitizeMultilineMessagePreview(value: string): string {
+  const normalized = stripAnsiSequences(value)
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]+/g, " ");
+  return truncate(
+    collapseHorizontalWhitespace(normalized),
+    MESSAGE_PREVIEW_MAX_LENGTH,
+  );
+}
+
 /**
  * Sanitize an untrusted identity field for inclusion in notification copy.
  * Strips control characters and clamps to 120 characters.
@@ -271,3 +306,84 @@ export const NOTIFICATION_TITLE_MAX_LENGTH = 60;
 export function sanitizeNotificationTitle(value: string): string {
   return sanitize(value, NOTIFICATION_TITLE_MAX_LENGTH);
 }
+
+/**
+ * Tidy copy after a sentence was cut out of it: trailing spaces before a
+ * line break go, runs of blank lines collapse to one, and the ends trim.
+ */
+export function normalizeStrippedText(value: string): string {
+  return value
+    .replace(/(?<=\S)[ \t]{2,}(?=\S)/g, " ")
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+const DIRECTIVE_VERBS = "approve|reject|verify|trust|block|<your\\s+answer>";
+
+/**
+ * Remove request-code reply mechanics from copy: every sentence that pairs
+ * the code with a reply verb (`Reply "X approve" or "X reject"`, a
+ * paraphrase, a negated form like `Do not reply "X reject"`, and the same
+ * with backticks, smart quotes, or no quotes at all), and every sentence
+ * that names a reference, approval, or request code together with the code
+ * (`Reference code: X.`, `Use reference code X for this request.`).
+ *
+ * Whole sentences go, never a suffix from "reply" onward, so no fragment
+ * like "Alice wants access. Do not" survives. A sentence is text between
+ * line breaks or `.!?` terminators. Sentences that mention other codes or
+ * merely contain the word "reply" are untouched.
+ */
+export function stripRequestCodeDirectives(
+  text: string,
+  requestCode: string,
+): string {
+  const code = RegExp.escape(requestCode);
+  const sentence = (core: string): RegExp =>
+    new RegExp(`[^.!?\\n]*${core}[^.!?\\n]*[.!?]?(?:[ \\t]*\\n)?`, "gi");
+  const next = text
+    .replace(
+      sentence(`(?<![A-Z0-9])${code}\\s+(?:${DIRECTIVE_VERBS})(?![A-Za-z])`),
+      "",
+    )
+    .replace(
+      sentence(
+        `\\b(?:reference|approval|request)\\s+code\\b[^.!?\\n]*?(?<![A-Z0-9])${code}(?![A-Z0-9])`,
+      ),
+      "",
+    );
+  return normalizeStrippedText(next);
+}
+
+/**
+ * Run a reply-mechanics strip over every text field of a channel's copy.
+ * A body, deliveryText, or conversationSeedMessage left empty by the strip
+ * becomes `ask`, the request's own deterministic text, so a card surface
+ * never shows the mechanics it exists to avoid; without one it keeps its
+ * text rather than becoming empty, which downstream reads as missing copy.
+ * A title is a headline, never the ask, so a mechanics-only title keeps
+ * its text.
+ */
+export function stripReplyMechanicsFromCopy(
+  copy: RenderedChannelCopy,
+  strip: (text: string) => string,
+  ask: string | undefined,
+): RenderedChannelCopy {
+  const fallback = ask === undefined ? undefined : nonEmpty(ask);
+  const stripField = (text: string): string => {
+    const stripped = strip(text);
+    return stripped.length > 0 ? stripped : (fallback ?? text);
+  };
+  const strippedTitle = strip(copy.title);
+  return {
+    ...copy,
+    title: strippedTitle.length > 0 ? strippedTitle : copy.title,
+    body: stripField(copy.body),
+    deliveryText: copy.deliveryText
+      ? stripField(copy.deliveryText)
+      : copy.deliveryText,
+    conversationSeedMessage: copy.conversationSeedMessage
+      ? stripField(copy.conversationSeedMessage)
+      : copy.conversationSeedMessage,
+  };
+}

package/src/permissions/confirmation-guardian-request.ts

@@ -8,7 +8,7 @@
  * generic event hub — lets the hub stay a pure pub/sub primitive with no
  * dependency on the conversation registry or guardian bridge.
  *
- * Channel guardian decisions (reactions, buttons, text) all route through the
+ * Channel guardian decisions (buttons, text) all route through the
  * guardian-request pipeline, so without this record none of them can resolve the
  * confirmation.
  *
@@ -135,7 +135,7 @@ export async function createGuardianRequestForConfirmation(
     if (err instanceof IntegrityError) {
       // The confirmation could not be promoted to a guardian request
       // (e.g. its trust context resolved no guardianPrincipalId). Channel
-      // guardian decisions — reactions, buttons, and text — all route through
+      // guardian decisions (buttons and text) all route through
       // the guardian-request pipeline, so without this record none of them can resolve
       // the confirmation. Surface it rather than swallowing: for a guardian's
       // own confirmation a bound principal should always be present.

package/src/permissions/prompter.ts

@@ -173,7 +173,7 @@ export class PermissionPrompter {
       this.sendToClient(confirmationMsg);
 
       // Promote the confirmation to a guardian request so channel
-      // guardian decisions (reactions, buttons, text) can resolve it.
+      // guardian decisions (buttons, text) can resolve it.
       // The prompter runs inside the emitting turn, so the request binds
       // to that turn's trust snapshot.
       if (conversationId) {

package/src/persistence/conversation-crud.ts

@@ -32,6 +32,7 @@ import { conversationMetadataSyncTag } from "../daemon/message-types/sync.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
 import { clearAllConversationIds } from "../home/feed-writer.js";
 import type { ConversationDeletedInputContext } from "../hooks/types.js";
+import { readProviderMetadata } from "../messaging/read-provider-metadata.js";
 import { HOOKS } from "../plugin-api/constants.js";
 import { forkConversationMemory } from "../plugins/defaults/memory/fork-conversation-memory.js";
 import { indexMessageNow } from "../plugins/defaults/memory/indexer.js";
@@ -309,7 +310,7 @@ export const messageMetadataSchema = z
     /**
      * Optional client-side metadata bag attached to user messages at persist
      * time. `os` carries the client-reported OS surface ("web" | "ios" |
-     * "macos" | "windows" | "android") from the request body's `clientOs`
+     * "macos" | "windows" | "linux" | "android") from the request body's `clientOs`
      * field, stamped by `persistQueuedMessageBody`. The transport
      * `userMessageInterface` is
      * "web" for the web, mobile, and desktop apps alike, so this is the only
@@ -422,6 +423,12 @@ export const messageMetadataSchema = z
      *  as a literal here (like `memoryInjectedBlock`) so the storage schema does
      *  not import the memory feature. */
     memoryV3InjectedBlock: z.string().optional(),
+    /** Memory-v3 per-turn `<memory_spotlight>` block (wrapped). Rehydrated
+     *  by `loadFromDb` so historical turns keep the spotlight they were sent
+     *  with. The key matches the memory plugin's
+     *  `MEMORY_V3_SPOTLIGHT_BLOCK_METADATA_KEY`, kept as a literal here so
+     *  the storage schema does not import the memory feature. */
+    memoryV3SpotlightBlock: z.string().optional(),
     turnContextBlock: z.string().optional(),
     pkbSystemReminderBlock: z.string().optional(),
     workspaceBlock: z.string().optional(),
@@ -491,8 +498,9 @@ export function isProviderErrorMetadata(
 }
 
 /**
- * True when an assistant row is a standalone display turn: a system card or
- * a provider-error notice, or a deliberate-silence marker. Standalone rows never merge with adjacent
+ * True when an assistant row is a standalone display turn: a system card, a
+ * provider-error notice, a deliberate-silence marker, a reaction, or a row
+ * deleted on its channel. Standalone rows never merge with adjacent
  * assistant rows, and turn grouping closes on them, so display merging and
  * the turn resolver agree on boundaries. Takes the raw persisted `metadata`
  * JSON string; malformed JSON and non-assistant roles are never standalone.
@@ -510,13 +518,28 @@ export function isStandaloneAssistantMessage(
       isSystemCardMetadata(parsed) ||
       isProviderErrorMetadata(parsed) ||
       isNoResponseMetadata(parsed) ||
-      isReactionMessageMetadata(parsed)
+      isReactionMessageMetadata(parsed) ||
+      isChannelDeletedMetadata(metadata)
     );
   } catch {
     return false;
   }
 }
 
+/**
+ * True when the row was deleted on its channel after it was stored. The
+ * marker lives in the provider envelope rather than in `messageKind`, so a
+ * merged run would take the anchor's envelope and either drop the deletion
+ * or claim it over text that is still visible. The substring guard keeps the
+ * envelope parse off rows that cannot carry it.
+ */
+function isChannelDeletedMetadata(metadata: string): boolean {
+  return (
+    metadata.includes("deletedAt") &&
+    readProviderMetadata(metadata)?.deletedAt !== undefined
+  );
+}
+
 /**
  * Parse a persisted message's metadata JSON against {@link messageMetadataSchema}
  * — the single source of truth for its shape — returning the validated fields,
@@ -753,11 +776,17 @@ const parseMessage = createRowMapper<typeof messages.$inferSelect, MessageRow>({
 });
 
 /**
- * Monotonic timestamp source for message ordering. Two messages saved within
- * the same millisecond (e.g., tool_results user message + assistant message in
- * message_complete) would get the same Date.now(), making their reload order
- * non-deterministic. This counter ensures every call returns a strictly
- * increasing value so insertion order is always preserved.
+ * Monotonic timestamp source for message ordering and conversation creation.
+ * Two messages saved within the same millisecond (e.g., tool_results user
+ * message + assistant message in message_complete) would get the same
+ * Date.now(), making their reload order non-deterministic. This counter
+ * ensures every call returns a strictly increasing value so insertion order is
+ * always preserved.
+ *
+ * Conversation rows draw from it for a second reason: `created_at` is what
+ * tells one incarnation of an id from another, so two creations in one
+ * millisecond must not be able to collide. Sharing the counter with messages
+ * costs nothing, both wanting the same "never twice the same value" guarantee.
  */
 let lastTimestamp = 0;
 function monotonicNow(): number {
@@ -780,6 +809,24 @@ interface InsertedMessage {
   deduplicated: boolean;
 }
 
+/**
+ * Thrown by an insert whose caller's `insertPrecondition` reads false.
+ *
+ * No row was written, so a caller holding resources for the message it asked
+ * for (an uploaded attachment, a pending client receipt) is free to give them
+ * up on this error. Carries no SQLite code, which is what keeps
+ * {@link withSqliteRetry} from mistaking it for contention and retrying an
+ * abort that will only abort again.
+ */
+export class MessageInsertPreconditionError extends Error {
+  constructor(conversationId: string) {
+    super(
+      `Message insert precondition failed for conversation ${conversationId}`,
+    );
+    this.name = "MessageInsertPreconditionError";
+  }
+}
+
 interface InsertMessageCoreParams {
   conversationId: string;
   role: MessageRole;
@@ -793,6 +840,9 @@ interface InsertMessageCoreParams {
    *  `requestId` for user turns) can pass it here so the persisted
    *  row ID matches the runtime request ID. */
   id?: string;
+  /** Answered synchronously at the top of every insert attempt. See
+   *  {@link AddMessageOptions.insertPrecondition}. */
+  insertPrecondition?: () => boolean;
 }
 
 /**
@@ -879,6 +929,7 @@ async function insertMessageCore(
     metadata,
     clientMessageId,
     id,
+    insertPrecondition,
   } = params;
   warnOnModelInvisibleContent(content, conversationId);
   const db = getDb();
@@ -905,8 +956,17 @@ async function insertMessageCore(
   // The timestamp is recomputed each attempt so a late retry doesn't persist a
   // stale `updatedAt`.
   return withSqliteRetry(
-    (): InsertedMessage =>
-      timeSyncSection(
+    (): InsertedMessage => {
+      // Asked at the top of EVERY attempt, and synchronously, because that is
+      // the scope the answer holds for. Contention retries this function after
+      // an awaited backoff, so an answer given once for the call would be
+      // reporting on the world as it stood before a sleep the caller cannot
+      // see. From here to the statement below there is nothing async, so the
+      // answer and the row this attempt writes share one tick.
+      if (insertPrecondition && !insertPrecondition()) {
+        throw new MessageInsertPreconditionError(conversationId);
+      }
+      return timeSyncSection(
         "messages:insert",
         (): InsertedMessage => {
           const now = monotonicNow();
@@ -1016,7 +1076,8 @@ async function insertMessageCore(
           contentBytes:
             typeof content === "string" ? content.length : undefined,
         }),
-      ),
+      );
+    },
     { op: "insertMessageCore", context: { conversationId } },
   );
 }
@@ -1073,7 +1134,12 @@ export function createConversation(
       },
 ) {
   const db = getDb();
-  const now = Date.now();
+  // Monotonic, because `created_at` is a conversation's incarnation identity:
+  // callers holding work for an id compare against the stamp they were
+  // accepted for, so a row deleted and written back under that id has to carry
+  // a later one even when both land in the same millisecond. Per process is
+  // the scope that matters, the holders being in-memory and gone on a restart.
+  const now = monotonicNow();
   const initialSeq = getCurrentSeq();
   const opts =
     typeof titleOrOpts === "string"
@@ -2361,6 +2427,17 @@ export interface AddMessageOptions {
    *  internally. Pass the same value as `requestId` for user turns so
    *  the persisted row ID matches the runtime correlation ID. */
   id?: string;
+  /**
+   * Answered synchronously at the top of every insert attempt, immediately
+   * before that attempt's statement. False aborts with a
+   * {@link MessageInsertPreconditionError} and writes nothing.
+   *
+   * For a caller whose right to write can lapse while the insert is in
+   * flight. Per attempt rather than per call because contention retries the
+   * insert after an awaited backoff, and the world can move under a caller
+   * during that sleep.
+   */
+  insertPrecondition?: () => boolean;
 }
 
 /**
@@ -2374,7 +2451,8 @@ export async function addMessage(
   content: string,
   options?: AddMessageOptions,
 ) {
-  const { metadata, skipIndexing, clientMessageId, id } = options ?? {};
+  const { metadata, skipIndexing, clientMessageId, id, insertPrecondition } =
+    options ?? {};
   const inserted = await insertMessageCore({
     conversationId,
     role,
@@ -2382,6 +2460,7 @@ export async function addMessage(
     metadata,
     clientMessageId,
     id,
+    ...(insertPrecondition ? { insertPrecondition } : {}),
   });
 
   if (inserted.deduplicated) {