@vellumai/assistant 0.11.7 → 0.11.8-staging.1

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

@@ -0,0 +1,242 @@
+/**
+ * Unit tests for the guardian-form registry.
+ *
+ * The registry is the rail every form-backed command parks on, so the
+ * concurrency rules are tested here directly rather than only through the
+ * contact forms that happen to use them today. What matters: a form is
+ * answered once, a claim stops the answer deadline without ending the form,
+ * and a form that nobody answers ends by telling the clients showing it.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+
+import {
+  claimGuardianForm,
+  type GuardianFormClosedReason,
+  hasUnclaimedGuardianForm,
+  openGuardianForm,
+  resolveGuardianForm,
+} from "../guardian-form-registry.js";
+
+interface TestResult {
+  ok: boolean;
+  error?: string;
+  wrote?: string;
+}
+
+/** Open a form and hand back its requestId plus the parked promise. */
+function openForm(options: { kind?: string; timeoutMs?: number } = {}) {
+  const closed = mock((_id: string, _reason: GuardianFormClosedReason) => {});
+  let requestId = "";
+  const settled = openGuardianForm<TestResult>({
+    kind: options.kind ?? "test.form",
+    timeoutMs: options.timeoutMs ?? 30_000,
+    meta: { verify: true },
+    broadcast: {
+      open: (id) => {
+        requestId = id;
+      },
+      closed,
+    },
+  });
+  return { requestId, settled, closed };
+}
+
+const tick = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe("openGuardianForm", () => {
+  test("broadcasts the form and parks until something resolves it", async () => {
+    const { requestId, settled } = openForm();
+    expect(requestId).toMatch(/^[0-9a-f-]{36}$/);
+
+    let done = false;
+    void settled.then(() => {
+      done = true;
+    });
+    await tick(10);
+    expect(done).toBe(false);
+
+    resolveGuardianForm(requestId, { ok: true, wrote: "contact-1" });
+    expect(await settled).toEqual({ ok: true, wrote: "contact-1" });
+  });
+
+  test("hands the writer's own fields back to the parked call", async () => {
+    const { requestId, settled } = openForm();
+    resolveGuardianForm(requestId, { ok: false, error: "Cancelled by user" });
+    expect(await settled).toEqual({ ok: false, error: "Cancelled by user" });
+  });
+
+  test("an unanswered form ends and tells the clients showing it", async () => {
+    const { requestId, settled, closed } = openForm({ timeoutMs: 30 });
+
+    expect(await settled).toEqual({ ok: false, error: "Prompt timed out" });
+    expect(closed).toHaveBeenCalledWith(requestId, "timed_out");
+  });
+});
+
+describe("claimGuardianForm", () => {
+  test("only the first claim wins", async () => {
+    const { requestId, settled } = openForm();
+
+    const first = claimGuardianForm(requestId);
+    const second = claimGuardianForm(requestId);
+
+    expect(first.claimed).toBe(true);
+    expect(first.settleMs).toBeGreaterThan(0);
+    expect(second).toEqual({ claimed: false, reason: "already_claimed" });
+
+    resolveGuardianForm(requestId, { ok: true });
+    await settled;
+  });
+
+  test("a form nobody is holding claims as unknown", () => {
+    expect(claimGuardianForm("no-such-form")).toEqual({
+      claimed: false,
+      reason: "unknown",
+    });
+  });
+
+  test("claiming disarms the answer deadline", async () => {
+    // The form is open for 30ms, and the claim lands inside that window. If the
+    // claim did not swap the deadline for the settle window, the parked call
+    // would report a timeout while the write it started was still running.
+    const { requestId, settled, closed } = openForm({ timeoutMs: 30 });
+    expect(claimGuardianForm(requestId).claimed).toBe(true);
+
+    let done = false;
+    void settled.then(() => {
+      done = true;
+    });
+    await tick(80);
+
+    expect(done).toBe(false);
+    expect(closed).not.toHaveBeenCalled();
+
+    resolveGuardianForm(requestId, { ok: true, wrote: "late" });
+    expect(await settled).toEqual({ ok: true, wrote: "late" });
+  });
+
+  test("a resolved form cannot be claimed again", async () => {
+    const { requestId, settled } = openForm();
+    resolveGuardianForm(requestId, { ok: true });
+    await settled;
+
+    expect(claimGuardianForm(requestId)).toEqual({
+      claimed: false,
+      reason: "unknown",
+    });
+  });
+});
+
+describe("resolveGuardianForm", () => {
+  test("retires the card as answered or cancelled", async () => {
+    const answered = openForm();
+    resolveGuardianForm(answered.requestId, { ok: true });
+    await answered.settled;
+    expect(answered.closed).toHaveBeenCalledWith(
+      answered.requestId,
+      "answered",
+    );
+
+    const cancelled = openForm();
+    resolveGuardianForm(cancelled.requestId, { ok: false, error: "no" });
+    await cancelled.settled;
+    expect(cancelled.closed).toHaveBeenCalledWith(
+      cancelled.requestId,
+      "cancelled",
+    );
+  });
+
+  test("reports that nothing was waiting for an unknown form", () => {
+    expect(resolveGuardianForm("no-such-form", { ok: true })).toEqual({
+      resolved: false,
+    });
+  });
+});
+
+describe("hasUnclaimedGuardianForm", () => {
+  test("sees only the kinds it is asked about", async () => {
+    const { requestId, settled } = openForm({ kind: "kind.a" });
+
+    expect(hasUnclaimedGuardianForm(["kind.a"])).toBe(true);
+    // The point of taking kinds: an open form of one kind must not block a
+    // form of another, which a registry-wide sweep would do.
+    expect(hasUnclaimedGuardianForm(["kind.b"])).toBe(false);
+    expect(hasUnclaimedGuardianForm(["kind.b", "kind.a"])).toBe(true);
+
+    resolveGuardianForm(requestId, { ok: true });
+    await settled;
+    expect(hasUnclaimedGuardianForm(["kind.a"])).toBe(false);
+  });
+
+  test("a claimed form no longer counts as open", async () => {
+    const { requestId, settled } = openForm({ kind: "kind.c" });
+    expect(hasUnclaimedGuardianForm(["kind.c"])).toBe(true);
+
+    claimGuardianForm(requestId);
+    // Claimed means answered: its card is gone, so the next command should not
+    // be refused on account of it.
+    expect(hasUnclaimedGuardianForm(["kind.c"])).toBe(false);
+
+    resolveGuardianForm(requestId, { ok: true });
+    await settled;
+  });
+});
+
+describe("resolveFormFromCallback", () => {
+  test("passes a writer's own fields through untouched", async () => {
+    // The rail is only reusable if a new form's result reaches its caller. A
+    // callback that enumerated contact fields would drop everything else.
+    const { requestId, settled } = openForm();
+
+    const { resolveFormFromCallback } =
+      await import("../routes/guardian-form-routes.js");
+    resolveFormFromCallback({
+      body: { requestId, id: "row-7", rows: 3, skipped: false },
+    } as never);
+
+    expect(await settled).toEqual({
+      ok: true,
+      id: "row-7",
+      rows: 3,
+      skipped: false,
+    } as never);
+  });
+
+  test("an error makes the outcome a failure", async () => {
+    const { requestId, settled } = openForm();
+    const { resolveFormFromCallback } =
+      await import("../routes/guardian-form-routes.js");
+    resolveFormFromCallback({
+      body: { requestId, error: "nope", id: "ignored" },
+    } as never);
+
+    expect(await settled).toEqual({ ok: false, error: "nope" });
+  });
+});
+
+describe("claiming names the form", () => {
+  test("a claim for a different kind is refused", async () => {
+    // An id alone does not say which form it belongs to. Without this check a
+    // submission to form B could claim an open form A, run B's write, and hand
+    // A's caller a result for a form it never showed.
+    const { requestId, settled } = openForm({ kind: "kind.real" });
+
+    expect(claimGuardianForm(requestId, "kind.other")).toEqual({
+      claimed: false,
+      reason: "wrong_kind",
+    });
+    // Refused, not consumed: the right caller can still claim it.
+    expect(claimGuardianForm(requestId, "kind.real").claimed).toBe(true);
+
+    resolveGuardianForm(requestId, { ok: true });
+    await settled;
+  });
+
+  test("a caller that names no kind still claims, as before", async () => {
+    const { requestId, settled } = openForm({ kind: "kind.real" });
+    expect(claimGuardianForm(requestId).claimed).toBe(true);
+    resolveGuardianForm(requestId, { ok: true });
+    await settled;
+  });
+});

package/src/runtime/access-request-helper.ts

@@ -11,6 +11,8 @@
  * principal so access requests cannot bind to stale/cross-assistant contacts.
  */
 
+import { isGuardianRequestExpired } from "@vellumai/gateway-client";
+
 import {
   createGuardianRequest,
   listGuardianRequestsOrEmpty,
@@ -228,13 +230,19 @@ export async function notifyGuardianOfAccessRequest(
   // notified: true with the existing request ID so callers know the guardian
   // was already notified. A degraded (empty) read falls through to creation,
   // whose fail-closed throw prevents a prompt without a persisted request.
-  const existingPending = await listGuardianRequestsOrEmpty({
-    status: "pending",
-    requesterExternalUserId: actorExternalId,
-    sourceChannel,
-    kind: "access_request",
-    sourceConversationId: conversationId,
-  });
+  // Past-deadline rows never dedupe: a pending row can sit past its
+  // expiresAt until the sweep expires it, it is already undecidable, and
+  // letting it absorb a fresh attempt would silently drop the new guardian
+  // notification.
+  const existingPending = (
+    await listGuardianRequestsOrEmpty({
+      status: "pending",
+      requesterExternalUserId: actorExternalId,
+      sourceChannel,
+      kind: "access_request",
+      sourceConversationId: conversationId,
+    })
+  ).filter((r) => !isGuardianRequestExpired(r));
   if (existingPending.length > 0) {
     log.debug(
       { sourceChannel, actorExternalId, existingId: existingPending[0].id },

package/src/runtime/agent-wake.ts

@@ -145,9 +145,9 @@ function sanitizeEventAttr(value: string): string {
 /**
  * Untrusted third-party output to fence inside a persisted wake trigger via
  * {@link wrapUntrustedContent}. `maxChars` overrides the per-source character
- * budget — used for preformatted shell output that `formatShellOutput` already
- * bounded (to `MAX_OUTPUT_LENGTH`) and appended an `<output_truncated file=…/>`
- * recovery marker to, so the wrapper does not re-truncate that marker off.
+ * budget. Used for preformatted shell output that is already bounded to
+ * `MAX_OUTPUT_LENGTH` with an `<output_truncated />` marker, so the wrapper
+ * does not slice that marker off.
  */
 interface WakeUntrustedOutput {
   content: string;
@@ -1018,7 +1018,19 @@ export async function wakeAgentForOpportunity(
               },
             ];
     const wakeHintMessageCount = wakeMessages.length;
-    const runInput: Message[] = [...baseline, ...wakeMessages];
+    // Camera-frame retention, the wake's equivalent of the orchestrator's
+    // pre-run pass. The wake sends this array itself and keeps the in-loop
+    // budget gate disabled, so neither the loop's post-compaction transform nor
+    // `runAgentLoopImpl`'s pre-run pass ever sees it; a wake on a long camera
+    // session would otherwise carry every frame the conversation holds,
+    // including any the gate above just retained. The pass replaces blocks
+    // inside messages without adding, dropping, or reordering one, so
+    // `baselineLength` and `wakeHintMessageCount` still index the same
+    // positions.
+    const runInput: Message[] = conversation.trimAgedSightFrames([
+      ...baseline,
+      ...wakeMessages,
+    ]);
 
     // Event handling runs in two modes. While `mode === "buffering"`,
     // events accumulate in `buffered` so that a wake which ultimately

package/src/runtime/channel-approval-types.ts

@@ -160,12 +160,15 @@ export interface ChannelApprovalPrompt {
 // Decision result (daemon-internal)
 // ---------------------------------------------------------------------------
 
-/** How the user communicated their decision. */
+/**
+ * How the user communicated their decision: the modality, never the channel.
+ * A channel-prefixed value here would misattribute the next channel that
+ * joins (every channel's buttons ride the same `apr:` callback), and no
+ * consumer reads a channel off this field.
+ */
 export type ApprovalDecisionSource =
-  | "telegram_button"
-  | "whatsapp_button"
-  | "slack_button"
-  | "slack_reaction"
+  | "button"
+  | "reaction"
   | "vellum_surface"
   | "plain_text";
 

package/src/runtime/channel-invite-transport.ts

@@ -13,6 +13,7 @@
  */
 
 import type { ChannelId } from "../channels/types.js";
+import { discordInviteAdapter } from "./channel-invite-transports/discord.js";
 import { emailInviteAdapter } from "./channel-invite-transports/email.js";
 import { slackInviteAdapter } from "./channel-invite-transports/slack.js";
 import { telegramInviteAdapter } from "./channel-invite-transports/telegram.js";
@@ -96,6 +97,7 @@ export async function resolveAdapterHandle(
 /** Create a registry instance with built-in adapters registered. */
 export function createInviteAdapterRegistry(): InviteAdapterRegistry {
   const registry = new InviteAdapterRegistry();
+  registry.register(discordInviteAdapter);
   registry.register(emailInviteAdapter);
   registry.register(slackInviteAdapter);
   registry.register(telegramInviteAdapter);

package/src/runtime/channel-invite-transports/discord.ts

@@ -0,0 +1,27 @@
+/**
+ * Discord channel invite adapter.
+ *
+ * Resolves the assistant's Discord bot username for use in invite
+ * instructions. Discord invites use the universal 6-digit code path for
+ * redemption, so this adapter only implements `resolveChannelHandle`,
+ * no `buildShareLink` or `extractInboundToken` needed. The platform
+ * constraint that shapes the instruction copy lives with the copy
+ * (`invite-instruction-generator.ts`): a person can only DM the bot once
+ * they share a server with it.
+ */
+
+import type { ChannelId } from "../../channels/types.js";
+import { getConfig } from "../../config/loader.js";
+import type { ChannelInviteAdapter } from "../channel-invite-types.js";
+
+export const discordInviteAdapter: ChannelInviteAdapter = {
+  channel: "discord" as ChannelId,
+
+  resolveChannelHandle(): string | undefined {
+    const { botUsername } = getConfig().discord;
+    if (!botUsername) {
+      return undefined;
+    }
+    return `@${botUsername}`;
+  },
+};

package/src/runtime/channel-readiness-service.ts

@@ -26,10 +26,10 @@ export const REMOTE_TTL_MS = 5 * 60 * 1000;
  * Bot scopes the Slack manifest requests that the app cannot work without.
  *
  * Slack's install flow can return a token carrying a fraction of the manifest's
- * scopes while `auth.test` still succeeds — a live install produced 2 of 18, and
- * the first real API call failed with `missing_scope`. `auth.test` passing is
- * therefore not evidence the install is usable; the granted set has to be read
- * off the `x-oauth-scopes` response header and compared.
+ * scopes while `auth.test` still succeeds, leaving the first real API call to
+ * fail with `missing_scope`. `auth.test` passing is therefore not evidence the
+ * install is usable; the granted set has to be read off the `x-oauth-scopes`
+ * response header and compared.
  *
  * Mirrors the non-optional half of `oauth_config.scopes.bot` in
  * `skills/slack-app-setup/scripts/build-manifest.ts` (and its copy in

package/src/runtime/channel-reply-delivery.ts

@@ -3,6 +3,7 @@ import type { MessageAudience } from "@vellumai/gateway-client";
 import { stripVellumLinks } from "../daemon/assistant-attachments.js";
 import type { RenderedHistoryContent } from "../daemon/handlers/shared.js";
 import { renderHistoryContent } from "../daemon/handlers/shared.js";
+import { readProviderMessageMetadata } from "../messaging/provider-message-metadata.js";
 import { editChannelMessage } from "../messaging/providers/index.js";
 import { readSlackMetadata } from "../messaging/providers/slack/message-metadata.js";
 import { getAttachmentMetadataForMessage } from "../persistence/attachments-store.js";
@@ -383,16 +384,16 @@ async function deliverPersistedAssistantMessageViaCallback(
     return false;
   }
 
-  // Compose an `onMessageTs` that reconciles `slackMeta.channelTs` on the
-  // persisted assistant row once Slack returns the authoritative ts. The
-  // assistant row was written BEFORE the gateway POST in
-  // `handleMessageComplete`, so the partial `slackMeta` it carries is
-  // missing `channelTs` and would otherwise be rejected by
-  // `readSlackMetadata`, dropping the row out of chronological/thread-tag
-  // rendering. We only act on the FIRST ts (top-level segment); any
-  // subsequent split segments become independent Slack messages with
-  // their own ts and are not represented as separate DB rows.
-  const reconcileOnMessageTs = makeChannelTsReconciler(msg.id);
+  // Compose an `onMessageTs` that reconciles the persisted assistant row's
+  // provider message ids as the transport reports the authoritative ones.
+  // The assistant row is written BEFORE the gateway POST, so its pre-send
+  // envelope names no id of its own: a Slack row's partial `slackMeta` lacks
+  // `channelTs` and reads as null through `readSlackMetadata`, and a
+  // neutral-envelope row lacks the `messageId` a later reaction
+  // naming it resolves by. A reply split into several segments reports one
+  // id per posted provider message, all reconciled onto this one row; see
+  // `makeSentMessageIdReconciler` for the per-envelope rules.
+  const reconcileOnMessageTs = makeSentMessageIdReconciler(msg.id);
   const callerOnMessageTs = options?.onMessageTs;
   const composedOnMessageTs = (ts: string): void => {
     reconcileOnMessageTs(ts);
@@ -491,39 +492,40 @@ export async function deliverReplyViaCallback(
 }
 
 /**
- * Build a one-shot `onMessageTs` handler that reconciles the persisted
- * assistant message's `slackMeta.channelTs` from Slack's authoritative `ts`.
+ * Build an `onMessageTs` handler that reconciles the persisted assistant
+ * row's provider message ids from the transport's authoritative ones:
+ * `slackMeta.channelTs` for a Slack row, `providerMeta.messageId` plus
+ * `additionalMessageIds` for a row carrying the neutral envelope (Discord
+ * today, any transport whose delivery result reports the sent id). The
+ * back-filled ids are what let a later reaction naming the
+ * assistant's own post resolve back to this row.
  *
  * Behavior:
- * - Acts only on the first invocation per delivery (subsequent segments
- *   correspond to independent Slack messages with their own ts and are not
- *   represented as separate DB rows).
- * - No-op when the row was not persisted with a `slackMeta` envelope (the
- *   channel was not Slack at write-time, e.g. vellum/telegram outbound).
- * - No-op when the row's existing `slackMeta` already parses cleanly via
- *   `readSlackMetadata` (channelTs already present, e.g. from a prior
- *   reconciliation).
+ * - A Slack row acts on the first invocation only: `channelTs` is the one
+ *   id its envelope names, and later split segments are independent Slack
+ *   messages it cannot carry.
+ * - A neutral-envelope row records every reported id: the first as
+ *   `messageId`, the rest under `additionalMessageIds`, all naming this
+ *   same row. An id already recorded (a redelivery) is skipped.
+ * - No-op when the row was persisted with neither envelope (e.g. vellum
+ *   outbound).
  * - Failures are logged and swallowed so a transient DB error cannot break
  *   the outbound delivery itself.
  */
-function makeChannelTsReconciler(messageId: string): (ts: string) => void {
-  let applied = false;
+function makeSentMessageIdReconciler(messageId: string): (ts: string) => void {
+  let slackApplied = false;
   return (ts: string): void => {
-    if (applied) {
-      return;
-    }
-    applied = true;
     if (!ts) {
       return;
     }
     try {
       // Re-read the row's current metadata so a concurrent edit-propagation
       // write (e.g. `editedAt`) is not clobbered. `updateMessageMetadata`
-      // shallow-merges into the top-level envelope, and the slackMeta
+      // shallow-merges into the top-level envelope, and the per-channel
       // sub-object is merged manually below so we can preserve fields on
       // the partial pre-send envelope (`mergeSlackMetadata` would call
       // `readSlackMetadata` which rejects the partial form for lacking
-      // channelTs — exactly the state we are reconciling).
+      // channelTs, exactly the state we are reconciling).
       const row = getMessageById(messageId);
       if (row === null || row.metadata === null) {
         return;
@@ -537,8 +539,13 @@ function makeChannelTsReconciler(messageId: string): (ts: string) => void {
       const slackMetaRaw =
         typeof envelope.slackMeta === "string" ? envelope.slackMeta : null;
       if (slackMetaRaw === null) {
+        reconcileProviderMessageId(messageId, envelope, ts);
         return;
       }
+      if (slackApplied) {
+        return;
+      }
+      slackApplied = true;
       // If the existing slackMeta already parses cleanly via the strict
       // reader, channelTs is already present (a prior reconciliation ran,
       // or backfill stamped the field) — nothing to do.
@@ -579,3 +586,40 @@ function makeChannelTsReconciler(messageId: string): (ts: string) => void {
     }
   };
 }
+
+/**
+ * The neutral-envelope arm of the reconciliation: record the transport's
+ * sent-message id on the row's `providerMeta`. The first reported id
+ * becomes `messageId`; further ids (a reply split at tool boundaries posts
+ * several provider messages) accumulate under `additionalMessageIds`. An id
+ * the envelope already names is a redelivery and is skipped, and a row
+ * carrying no valid neutral envelope is left untouched.
+ */
+function reconcileProviderMessageId(
+  messageId: string,
+  envelope: Record<string, unknown>,
+  ts: string,
+): void {
+  const providerMeta = readProviderMessageMetadata(envelope.providerMeta);
+  if (providerMeta === null) {
+    return;
+  }
+  if (providerMeta.messageId === undefined) {
+    updateMessageMetadata(messageId, {
+      providerMeta: JSON.stringify({ ...providerMeta, messageId: ts }),
+    });
+    return;
+  }
+  if (
+    providerMeta.messageId === ts ||
+    providerMeta.additionalMessageIds?.includes(ts)
+  ) {
+    return;
+  }
+  updateMessageMetadata(messageId, {
+    providerMeta: JSON.stringify({
+      ...providerMeta,
+      additionalMessageIds: [...(providerMeta.additionalMessageIds ?? []), ts],
+    }),
+  });
+}

package/src/runtime/guardian-action-service.ts

@@ -101,6 +101,10 @@ export async function processGuardianDecision(
   // 2. Verify conversationId scoping before applying the decision. The
   //    decision is allowed when the conversationId matches the request's
   //    source conversation OR a recorded delivery destination conversation.
+  //    Deliberately not narrowed by delivery channel: a delivery row's
+  //    destinationConversationId is always an internal conversation id, and
+  //    a channel card's paired conversation renders the same actionable
+  //    in-app card, so its taps are as legitimate as the vellum card's.
   //    Reads degrade fail-closed: an unreachable gateway scopes to not_found
   //    (and the decide below fails loudly anyway).
   if (conversationId) {
@@ -108,11 +112,7 @@ export async function processGuardianDecision(
     if (
       request &&
       request.sourceConversationId &&
-      !(await isGuardianRequestInScopeOrFalse(
-        requestId,
-        conversationId,
-        channel,
-      ))
+      !(await isGuardianRequestInScopeOrFalse(requestId, conversationId))
     ) {
       return { ok: true, applied: false, reason: "not_found" };
     }
@@ -128,6 +128,10 @@ export async function processGuardianDecision(
       channel,
       guardianPrincipalId: actorContext.guardianPrincipalId,
     },
+    // The acting conversation: card withdrawal suppresses only this
+    // conversation's completion broadcast (the acting client already shows
+    // its optimistic completion); sibling in-app projections still get theirs.
+    ...(conversationId ? { originConversationId: conversationId } : {}),
     userText: undefined,
   });