@vellumai/assistant 0.11.7 → 0.11.8-staging.1

package/src/runtime/guardian-form-registry.ts

@@ -0,0 +1,256 @@
+/**
+ * The parking rail behind every guardian form.
+ *
+ * A form-backed command does not write. It parks here, its form goes to every
+ * connected client, and the write happens elsewhere (today the gateway, which
+ * owns contact writes) and reports back. With no human at a form, nothing is
+ * written and the call times out. That property is what makes these commands
+ * guardian-gated, and it lives in this file rather than in any one form.
+ *
+ * What a form owner supplies: how to broadcast it, how to take it down, and
+ * what its result looks like. Everything below is the same for all of them.
+ *
+ * Lifecycle:
+ *   open   -> the call parks, the form goes out, a deadline starts
+ *   claim  -> one submission wins; the answer deadline is swapped for a
+ *             bounded settle window while the write runs
+ *   resolve-> the write reports back, the parked call returns, the card is
+ *             retired everywhere it is showing
+ *
+ * See `docs/guardian-forms.md` for how to add one.
+ */
+
+import { v4 as uuid } from "uuid";
+
+import {
+  GUARDIAN_FORM_DEFAULT_TIMEOUT_MS,
+  GUARDIAN_FORM_SETTLE_MS,
+} from "../util/guardian-form-timeouts.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("guardian-form-registry");
+
+/** Every form's result carries at least this; owners widen it. */
+export interface GuardianFormResult {
+  ok: boolean;
+  error?: string;
+}
+
+export type GuardianFormClosedReason = "answered" | "cancelled" | "timed_out";
+
+/**
+ * How a form reaches clients and how it leaves them.
+ *
+ * Both are the owner's, because the event names are wire contract. The
+ * registry decides *when* they fire.
+ */
+export interface GuardianFormBroadcast {
+  open: (requestId: string) => void;
+  closed: (requestId: string, reason: GuardianFormClosedReason) => void;
+}
+
+interface PendingGuardianForm {
+  kind: string;
+  resolve: (result: GuardianFormResult) => void;
+  timer: ReturnType<typeof setTimeout>;
+  closed: GuardianFormBroadcast["closed"];
+  /**
+   * Owner-defined state the write may need to read back out of band, for a
+   * client with no field to echo it in. Opaque here.
+   */
+  meta: Record<string, unknown>;
+  logContext: Record<string, unknown>;
+  /**
+   * Set once a submission has been accepted. The form went to every connected
+   * client, so more than one can answer it; the first claim wins and the rest
+   * write nothing.
+   */
+  claimed: boolean;
+}
+
+const pendingForms = new Map<string, PendingGuardianForm>();
+
+export interface OpenGuardianFormOptions {
+  /** Which form this is, for logs and for scoping the open-form check. */
+  kind: string;
+  broadcast: GuardianFormBroadcast;
+  /** How long to hold it open. Defaults to the shared 5 minutes. */
+  timeoutMs?: number;
+  meta?: Record<string, unknown>;
+  /** Form-specific fields folded into this form's log lines. */
+  logContext?: Record<string, unknown>;
+  /** What the parked call is told when nobody answers. */
+  timeoutError?: string;
+}
+
+/**
+ * Park a call until the guardian answers its form.
+ *
+ * The returned promise settles exactly once: on an answer, on a dismissal, or
+ * on the deadline. It never rejects, because the caller's failure is a result
+ * it has to report, not an exception to unwind through.
+ */
+export function openGuardianForm<TResult extends GuardianFormResult>(
+  options: OpenGuardianFormOptions,
+): Promise<TResult> {
+  const {
+    kind,
+    broadcast,
+    timeoutMs,
+    meta = {},
+    logContext = {},
+    timeoutError = "Prompt timed out",
+  } = options;
+  const requestId = uuid();
+
+  return new Promise<TResult>((resolve) => {
+    const timer = setTimeout(() => {
+      const pending = pendingForms.get(requestId);
+      if (!pending) {
+        return;
+      }
+      log.warn({ requestId, kind, ...logContext }, "Guardian form timed out");
+      expireForm(requestId, pending, timeoutError);
+    }, timeoutMs ?? GUARDIAN_FORM_DEFAULT_TIMEOUT_MS);
+
+    pendingForms.set(requestId, {
+      kind,
+      // The registry knows only the base shape; the owner's extra fields ride
+      // through resolveGuardianForm untouched, so the cast is confined here.
+      resolve: resolve as (result: GuardianFormResult) => void,
+      timer,
+      closed: broadcast.closed,
+      meta,
+      logContext,
+      claimed: false,
+    });
+
+    broadcast.open(requestId);
+    log.info({ requestId, kind, ...logContext }, "Guardian form broadcast");
+  });
+}
+
+/**
+ * End a form nobody answered in time, and tell the clients showing it.
+ *
+ * Without the broadcast the card stays up offering an answer that would now be
+ * refused: a form that has closed accepts no submission.
+ */
+function expireForm(
+  requestId: string,
+  pending: PendingGuardianForm,
+  error: string,
+): void {
+  pendingForms.delete(requestId);
+  pending.resolve({ ok: false, error });
+  pending.closed(requestId, "timed_out");
+}
+
+/**
+ * Claim a pending form so exactly one submission can write.
+ *
+ * The daemon holds the only record of which forms are still open, so it is the
+ * one place that can decide a race between two clients answering the same
+ * broadcast, and the only one that can tell whether an id is even the right
+ * form. Pass `expectedKind` whenever the caller knows which form it is
+ * writing for. First caller wins; the rest are told why they lost, so the writer
+ * can tell "somebody already answered this" (leave their answer alone) apart
+ * from "no such form" (expired or already resolved, so nothing should be
+ * written at all).
+ */
+export function claimGuardianForm(
+  requestId: string,
+  expectedKind?: string,
+): {
+  claimed: boolean;
+  reason?: "already_claimed" | "unknown" | "wrong_kind";
+  settleMs?: number;
+} {
+  const pending = pendingForms.get(requestId);
+  if (!pending) {
+    return { claimed: false, reason: "unknown" };
+  }
+  if (expectedKind !== undefined && pending.kind !== expectedKind) {
+    // An id alone does not say which form it belongs to. Without this, a
+    // submission to form B's endpoint could claim an open form A: B's write
+    // would run, and A's parked caller would be handed B's result for a form
+    // it never showed.
+    log.warn(
+      { requestId, expectedKind, actualKind: pending.kind },
+      "Guardian form claim rejected: the id belongs to a different form",
+    );
+    return { claimed: false, reason: "wrong_kind" };
+  }
+  if (pending.claimed) {
+    return { claimed: false, reason: "already_claimed" };
+  }
+  pending.claimed = true;
+  // Answered, so its open-for-answers deadline gives way to a bounded settle
+  // window while the write reports back.
+  clearTimeout(pending.timer);
+  pending.timer = setTimeout(() => {
+    log.warn(
+      { requestId, kind: pending.kind, ...pending.logContext },
+      "Guardian form claimed but never settled; the write never reported back",
+    );
+    expireForm(requestId, pending, "The submitted form never completed");
+  }, GUARDIAN_FORM_SETTLE_MS);
+  // The claimer needs the window too: it is how long its write has to report
+  // back before the caller gives up, and it should not have to know the number
+  // independently.
+  return { claimed: true, settleMs: GUARDIAN_FORM_SETTLE_MS };
+}
+
+/**
+ * Hand a form's answer to the call parked on it and retire the card.
+ *
+ * An error covers a dismissal and a failed write alike: the form is over
+ * either way, and the caller is the one told why.
+ */
+export function resolveGuardianForm<TResult extends GuardianFormResult>(
+  requestId: string,
+  result: TResult,
+): { resolved: boolean } {
+  const pending = pendingForms.get(requestId);
+  if (!pending) {
+    log.warn({ requestId }, "resolve: no pending guardian form found");
+    return { resolved: false };
+  }
+
+  clearTimeout(pending.timer);
+  pendingForms.delete(requestId);
+  pending.resolve(result);
+  pending.closed(requestId, result.ok ? "answered" : "cancelled");
+
+  log.info(
+    { requestId, kind: pending.kind, ...pending.logContext },
+    "Guardian form resolved",
+  );
+  return { resolved: true };
+}
+
+/**
+ * Whether any form of these kinds is open and still unanswered.
+ *
+ * Takes the kinds to check rather than sweeping the whole registry. Clients
+ * hold one card per kind, so a second broadcast of a kind already on screen
+ * replaces the first and leaves its command waiting on a form nobody can
+ * answer. A registry-wide check would go further than that and let any pending
+ * form block every other one, which is a rule each form should opt into rather
+ * than inherit.
+ */
+export function hasUnclaimedGuardianForm(kinds: readonly string[]): boolean {
+  for (const pending of pendingForms.values()) {
+    if (!pending.claimed && kinds.includes(pending.kind)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Owner-defined state parked with a form, for a writer that must read it back. */
+export function getGuardianFormMeta(
+  requestId: string,
+): Record<string, unknown> | undefined {
+  return pendingForms.get(requestId)?.meta;
+}

package/src/runtime/guardian-reply-router.ts

@@ -23,6 +23,7 @@
  * to allow for incremental migration and independent testability.
  */
 
+import type { InboundReactionPayload } from "@vellumai/gateway-client";
 import { isGuardianRequestExpired } from "@vellumai/gateway-client";
 
 import {
@@ -61,7 +62,7 @@ import type {
   ApprovalConversationGenerator,
 } from "./http-types.js";
 import * as pendingInteractions from "./pending-interactions.js";
-import { parseReactionCallbackData } from "./routes/channel-route-shared.js";
+import { reactionDecisionForEmoji } from "./routes/channel-route-shared.js";
 
 const log = getLogger("guardian-reply-router");
 
@@ -106,7 +107,12 @@ export interface GuardianReplyContext {
   /** Callback data from button presses (e.g. `apr:<requestId>:<action>`). */
   callbackData?: string;
   /**
-   * For emoji-reaction decisions (`callbackData` of `reaction:<emoji>`): the
+   * Structured reaction payload when the inbound event is a reaction; the
+   * reaction branch keys on it and reads nothing off callbackData.
+   */
+  reaction?: InboundReactionPayload;
+  /**
+   * For emoji-reaction decisions: the
    * channel-native id (e.g. Slack `ts`) of the message the reaction was
    * attached to. Used to recover the target request from its delivery record.
    */
@@ -368,23 +374,36 @@ export async function routeGuardianReply(
   // even when several cards are pending in the same chat, so — unlike the
   // text/NL paths — no clarification prompt is ever needed. `reaction_removed`
   // never expresses intent and is filtered out before reaching the router.
-  if (
-    callbackData?.startsWith("reaction:") &&
-    !callbackData.startsWith("reaction_removed:")
-  ) {
-    const reaction = parseReactionCallbackData(callbackData);
+  if (ctx.reaction?.op === "added") {
+    const decision = reactionDecisionForEmoji(ctx.reaction.emoji);
     const guardianChatId = channelDeliveryContext?.guardianChatId;
-    if (!reaction || !reactedMessageTs || !guardianChatId) {
+    if (!decision || !reactedMessageTs || !guardianChatId) {
       // Unknown emoji, or missing addressing context — not an actionable
       // approval reaction. Leave it for the caller to persist as a transcript
       // signal (it must not trigger an agent turn).
       return notConsumed();
     }
-    const request = await getPendingRequestByDestinationMessageOrNull(
-      channel,
-      guardianChatId,
-      reactedMessageTs,
-    );
+    // A delivery row keys its card by the destination the adapter delivered
+    // to, and channels address that destination in one of two modalities: a
+    // chat (the conversation the reaction arrives from) or a person (the
+    // guardian's own user id, which person-addressed adapters store so a
+    // stale room id can never become a delivery target). The reactor on an
+    // approval card is the person it was delivered to, so their id is the
+    // second probe; identity validation in applyGuardianDecision still
+    // guards the decision itself.
+    const request =
+      (await getPendingRequestByDestinationMessageOrNull(
+        channel,
+        guardianChatId,
+        reactedMessageTs,
+      )) ??
+      (actor.actorExternalUserId
+        ? await getPendingRequestByDestinationMessageOrNull(
+            channel,
+            actor.actorExternalUserId,
+            reactedMessageTs,
+          )
+        : null);
     if (!request) {
       // The reacted message is not a known pending approval card (a stray
       // reaction, or one whose request was already resolved). Never approve
@@ -393,7 +412,7 @@ export async function routeGuardianReply(
     }
     return applyDecision(
       request.id,
-      reaction.action,
+      decision.action,
       actor,
       undefined,
       channelDeliveryContext,

package/src/runtime/invite-instruction-generator.ts

@@ -66,9 +66,16 @@ export async function generateInviteInstruction(params: {
   const handle = params.channelHandle
     ? ` at ${params.channelHandle}`
     : ` on ${channelLabel}`;
+  // Discord DMs only open between accounts that share a server, and a
+  // member can still have server-member DMs turned off, so the instruction
+  // names both or the invitee dead-ends before the code.
+  const discordCaveat =
+    params.channelType === "discord"
+      ? " They need to be in a server with me, with DMs from server members enabled, before they can DM me."
+      : "";
   const fallback = params.shareUrl
-    ? `Send ${contact} this link: ${params.shareUrl} — or tell them to message me${handle} with the code below.`
-    : `Tell ${contact} to message me${handle} with the code below.`;
+    ? `Send ${contact} this link: ${params.shareUrl}, or tell them to message me${handle} with the code below.${discordCaveat}`
+    : `Tell ${contact} to message me${handle} with the code below.${discordCaveat}`;
 
   const resolved = await resolveConfiguredProvider(
     "inviteInstructionGenerator",
@@ -101,6 +108,11 @@ export async function generateInviteInstruction(params: {
         "No share link is available for this channel. Do NOT mention sharing a link or URL.",
       );
     }
+    if (params.channelType === "discord") {
+      parts.push(
+        "Platform constraint: the contact must share a Discord server with the bot, and have DMs from server members enabled in their privacy settings, before they can send it a direct message. Mention this.",
+      );
+    }
     parts.push(
       "",
       "Requirements:",

package/src/runtime/migrations/vbundle-metadata-merge.ts

@@ -1,13 +1,10 @@
 /**
  * Merge helper for `data/credentials/metadata.json` on bundle import.
  *
- * The credential metadata file lists the credentials known to the assistant
- * (service, field, policy, timestamps) and is used by the gateway's
- * `readServiceCredentials` to decide whether a service is "configured".
- * The VELLUM spec requires all four `vellum:*` fields (`platform_base_url`,
- * `assistant_api_key`, `platform_assistant_id`, `webhook_secret`) to be
- * present in metadata before the gateway will even look up their values in
- * CES.
+ * The leftover workspace credential metadata file may remain on disk after
+ * CES import. CES owns identity and policy records. Bundle import still
+ * merges `vellum:*` catalog rows so platform identity survives a
+ * local-to-platform teleport.
  *
  * On a local→platform teleport, the bundle carries the SOURCE's metadata
  * (no `vellum:*` entries, since the source is local), and a naive overwrite

package/src/runtime/no-response.ts

@@ -1,75 +1,14 @@
 /**
- * The assistant emits a `<no_response/>` sentinel to signal that a turn should
- * produce no user-visible reply. Channel delivery must hide the sentinel
- * itself without hiding real content it happens to coexist with. Slack
- * surfaces that begin work on the first deliverable text (the thinking-status
- * indicator and native reply streaming) additionally must not act on a
- * partially-arrived sentinel: a slow stream can surface just `<` or `<no_resp`
- * before the rest lands, and starting on that leaks a stray message that
- * later resolves to empty.
- */
-
-/** Matches a message whose entire content is the sentinel. */
-const NO_RESPONSE_ONLY_RE = /^\s*<no_response\s*\/?>\s*$/i;
-
-/** Matches every sentinel occurrence for stripping it out of mixed content. */
-export const NO_RESPONSE_INLINE_RE = /<no_response\s*\/?>/gi;
-
-/**
- * Detection variant without the `g` flag: a `g`-flagged regex is stateful
- * under `.test()` (it resumes from `lastIndex`), so reusing
- * {@link NO_RESPONSE_INLINE_RE} for detection would alternate between
- * matches and misses across calls.
- */
-const NO_RESPONSE_MARKER_RE = new RegExp(NO_RESPONSE_INLINE_RE.source, "i");
-
-/** Whether `text` contains the sentinel anywhere. */
-export function containsNoResponseMarker(text: string): boolean {
-  return NO_RESPONSE_MARKER_RE.test(text);
-}
-
-/** Removes every sentinel occurrence, trimming the leftover whitespace. */
-export function stripNoResponseMarkers(text: string): string {
-  return text.replace(NO_RESPONSE_INLINE_RE, "").trim();
-}
-
-const NO_RESPONSE_SENTINEL_FORMS = [
-  "<no_response/>",
-  "<no_response />",
-  "<no_response>",
-] as const;
-
-/**
- * Whether `text` could still grow into the sentinel — i.e. it is a leading
- * substring of one of its forms. Holding on these keeps a slowly-streamed
- * `<no_response/>` from surfacing as visible partial content.
- */
-function isPotentialNoResponsePrefix(text: string): boolean {
-  const lower = text.trim().toLowerCase();
-  if (lower.length === 0) {
-    return false;
-  }
-  return NO_RESPONSE_SENTINEL_FORMS.some((sentinel) =>
-    sentinel.startsWith(lower),
-  );
-}
-
-/**
- * Whether `text` carries user-visible content worth acting on now. Returns
- * `false` for empty text, the standalone sentinel, and any prefix that could
- * still complete into one; returns `true` once real content remains after
- * stripping inline sentinels.
- */
-export function hasDeliverableAssistantText(text: string): boolean {
-  const trimmed = text.trim();
-  if (trimmed.length === 0) {
-    return false;
-  }
-  if (NO_RESPONSE_ONLY_RE.test(trimmed)) {
-    return false;
-  }
-  if (isPotentialNoResponsePrefix(trimmed)) {
-    return false;
-  }
-  return stripNoResponseMarkers(trimmed).length > 0;
-}
+ * Daemon door for the shared `<no_response/>` sentinel convention. The
+ * definitions live in `@vellumai/service-contracts/no-response` so the
+ * daemon, gateway, and clients parse identically; this module exists so
+ * daemon-internal imports keep one stable path.
+ */
+export {
+  containsNoResponseMarker,
+  hasDeliverableAssistantText,
+  isNoResponseOnlyText,
+  isPotentialNoResponsePrefix,
+  NO_RESPONSE_INLINE_RE,
+  stripNoResponseMarkers,
+} from "@vellumai/service-contracts/no-response";