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

package/src/runtime/slack-reply-session.ts

@@ -0,0 +1,382 @@
+import type { SlackStreamTask } from "@vellumai/gateway-client";
+
+import {
+  extractThreadTsFromCallbackUrl,
+  isSlackDeliveryCallbackUrl,
+} from "../channels/slack-thread-store.js";
+import type { ChannelId } from "../channels/types.js";
+import {
+  incompleteVellumLinkSuffixLength,
+  stripVellumLinks,
+} from "../daemon/assistant-attachments.js";
+import type { ServerMessage } from "../daemon/message-protocol.js";
+import { SLACK_STREAM_MARKDOWN_LIMIT } from "../messaging/providers/slack/api.js";
+import { renderSlackBlocks } from "../messaging/providers/slack/render.js";
+import { getLogger } from "../util/logger.js";
+import { needsBoundarySpace } from "../util/text-spacing.js";
+import { deliverChannelReply } from "./gateway-client.js";
+import {
+  hasDeliverableAssistantText,
+  NO_RESPONSE_INLINE_RE,
+} from "./slack-no-response.js";
+import type { TaskProgressData } from "./slack-task-progress.js";
+import {
+  getTaskProgressDataFromSurfaceData,
+  mergeTaskProgressData,
+  toSlackStreamTasks,
+} from "./slack-task-progress.js";
+
+const log = getLogger("slack-reply-session");
+
+/**
+ * Minimum gap between coalesced `appendStream` calls. `chat.appendStream` is a
+ * Tier 4 method (100+ req/min); debouncing deltas keeps well under that while
+ * still feeling live.
+ *
+ * @see https://docs.slack.dev/reference/methods/chat.appendStream/
+ */
+const STREAM_COALESCE_MS = 400;
+
+/**
+ * How durable finalize should reconcile against the streaming session.
+ *
+ * - `streamed`: the reply was delivered live into a single streamed message;
+ *   finalize skips re-posting text, reconciles `slackMeta.channelTs` to the
+ *   stream `ts`, and posts only attachments.
+ * - `fallback`: no stream was opened (ineligible turn, no deliverable text, or
+ *   a failed `startStream`); finalize posts the full reply normally.
+ */
+export type SlackStreamReconciliation =
+  | { mode: "streamed"; messageTs: string; deliveredSegmentCount: number }
+  | { mode: "fallback" };
+
+export type SlackReplySession = {
+  observeEvent: (msg: ServerMessage) => void;
+  /**
+   * Settle in-flight stream operations, finalize the stream, and report how
+   * durable delivery should reconcile. Call once after processing completes.
+   */
+  finish: () => Promise<SlackStreamReconciliation>;
+};
+
+/**
+ * Whether a turn is eligible for native Slack reply streaming. Every eligible
+ * turn resolves to a threaded reply, since `chat.startStream` requires a
+ * `thread_ts`. Assistant-container DMs carry that thread implicitly; channel
+ * turns (including app-mention threads) thread under the inbound message.
+ *
+ * DMs infer the reader, so they stream without recipient identity. Channels
+ * must name the reader: `chat.startStream` requires both `recipient_user_id`
+ * and `recipient_team_id`, so a channel turn missing either falls back to
+ * durable delivery.
+ *
+ * @see https://docs.slack.dev/reference/methods/chat.startStream/
+ */
+export function shouldStreamSlackReply(params: {
+  sourceChannel: ChannelId;
+  chatType?: string;
+  replyCallbackUrl?: string;
+  recipientUserId?: string;
+  recipientTeamId?: string;
+}): boolean {
+  if (params.sourceChannel !== "slack") return false;
+  if (!isSlackDeliveryCallbackUrl(params.replyCallbackUrl)) return false;
+  if (extractThreadTsFromCallbackUrl(params.replyCallbackUrl) === null) {
+    return false;
+  }
+  if (params.chatType === "im") return true;
+  return Boolean(params.recipientUserId && params.recipientTeamId);
+}
+
+type StreamState = "idle" | "streaming" | "fallback";
+
+/**
+ * Owns the live-content lifecycle of one Slack DM reply: it consumes the
+ * assistant token stream once, opens a streamed message on first deliverable
+ * text, coalesces deltas into `appendStream` calls, advances a native plan
+ * block from `task_progress` surfaces, and finalizes with `stopStream`.
+ *
+ * Any stream-call failure degrades gracefully: the session abandons streaming
+ * (state `fallback`) and reports back so durable finalize posts the full reply
+ * via the normal path. Returns `undefined` for turns that are not eligible to
+ * stream.
+ */
+export function createSlackReplySession(params: {
+  sourceChannel: ChannelId;
+  chatType?: string;
+  replyCallbackUrl?: string;
+  chatId: string;
+  assistantId?: string;
+  /** Slack user ID of the reader; required to stream into a channel. */
+  recipientUserId?: string;
+  /** Slack team ID of the reader; required to stream into a channel. */
+  recipientTeamId?: string;
+  /** Gap between coalesced `appendStream` calls. Defaults to {@link STREAM_COALESCE_MS}. */
+  coalesceMs?: number;
+}): SlackReplySession | undefined {
+  if (!shouldStreamSlackReply(params) || !params.replyCallbackUrl) {
+    return undefined;
+  }
+  const { chatId, assistantId, recipientUserId, recipientTeamId } = params;
+  const coalesceMs = params.coalesceMs ?? STREAM_COALESCE_MS;
+  const replyCallbackUrl = params.replyCallbackUrl;
+  const threadTs = extractThreadTsFromCallbackUrl(replyCallbackUrl);
+  if (threadTs === null) return undefined;
+
+  let state: StreamState = "idle";
+  let started = false;
+  let finished = false;
+  let streamTs: string | undefined;
+
+  let rawText = "";
+  let confirmedLength = 0;
+
+  let segmentBuffer = "";
+  let deliveredSegmentCount = 0;
+  // Set when a tool-call or message boundary closes a text segment: the next
+  // segment's first delta is a fresh model response, so it is spaced off the
+  // prior segment when the model omitted the separating whitespace (matching
+  // `renderHistoryContent`'s `joinWithSpacing` on the durable delivery path).
+  let pendingSegmentBoundary = false;
+
+  const taskProgressBySurfaceId = new Map<string, TaskProgressData>();
+  let activeProgress: TaskProgressData | undefined;
+
+  let coalesceTimer: ReturnType<typeof setTimeout> | undefined;
+  let opChain: Promise<void> = Promise.resolve();
+
+  const cleanedText = (): string =>
+    stripVellumLinks(rawText).replace(NO_RESPONSE_INLINE_RE, "");
+
+  // Text safe to append to Slack's append-only stream: while more deltas may
+  // arrive, a trailing `[label](vellum://…)` link that is still being assembled
+  // is withheld so its internal path is never emitted before the link closes
+  // (and `stripVellumLinks` can remove it). Once `finished`, no delta can
+  // extend the text, so the full cleaned reply is safe to emit.
+  const streamableText = (): string => {
+    if (finished) return cleanedText();
+    const hold = incompleteVellumLinkSuffixLength(rawText);
+    const stable = hold > 0 ? rawText.slice(0, rawText.length - hold) : rawText;
+    return stripVellumLinks(stable).replace(NO_RESPONSE_INLINE_RE, "");
+  };
+
+  const planTasks = (): SlackStreamTask[] | undefined =>
+    activeProgress ? toSlackStreamTasks(activeProgress) : undefined;
+
+  const imageBlocks = (
+    text: string,
+  ):
+    | NonNullable<Parameters<typeof deliverChannelReply>[1]["blocks"]>
+    | undefined => {
+    const blocks = renderSlackBlocks(text)?.filter(
+      (block) => block.type === "image",
+    );
+    return blocks && blocks.length > 0 ? blocks : undefined;
+  };
+
+  const enqueue = (op: () => Promise<void>): void => {
+    opChain = opChain.catch(() => undefined).then(op);
+  };
+
+  const enqueueStart = (): void => {
+    enqueue(async () => {
+      const clean = streamableText();
+      if (clean.trim().length === 0) return;
+      const firstChunk = clean.slice(0, SLACK_STREAM_MARKDOWN_LIMIT);
+      const planActive = activeProgress !== undefined;
+      const tasks = planTasks();
+      try {
+        const result = await deliverChannelReply(replyCallbackUrl, {
+          chatId,
+          assistantId,
+          slackStream: {
+            action: "start",
+            threadTs,
+            markdownText: firstChunk,
+            ...(planActive ? { taskDisplayMode: "plan" as const } : {}),
+            ...(tasks ? { tasks } : {}),
+            ...(recipientUserId ? { recipientUserId } : {}),
+            ...(recipientTeamId ? { recipientTeamId } : {}),
+          },
+        });
+        if (result.ok && result.ts) {
+          streamTs = result.ts;
+          confirmedLength = firstChunk.length;
+          state = "streaming";
+        } else {
+          state = "fallback";
+        }
+      } catch (err) {
+        log.warn({ err, chatId }, "Slack startStream failed; falling back");
+        state = "fallback";
+      }
+    });
+    enqueueAppend();
+  };
+
+  const enqueueAppend = (): void => {
+    enqueue(async () => {
+      if (state !== "streaming" || !streamTs) return;
+      const clean = streamableText();
+      const tasks = planTasks();
+      // `chat.appendStream` requires `markdown_text` and caps it per call, so a
+      // delta wider than the limit drains across successive append calls. Each
+      // append carries the current task state, advancing the plan alongside
+      // text. Progress that advances without new text is not appended on its
+      // own (an append with no text is rejected); it lands on the next text
+      // append or on `stopStream`.
+      while (confirmedLength < clean.length) {
+        const chunk = clean.slice(
+          confirmedLength,
+          confirmedLength + SLACK_STREAM_MARKDOWN_LIMIT,
+        );
+        try {
+          await deliverChannelReply(replyCallbackUrl, {
+            chatId,
+            assistantId,
+            slackStream: {
+              action: "append",
+              streamTs,
+              markdownText: chunk,
+              ...(tasks ? { tasks } : {}),
+            },
+          });
+          confirmedLength += chunk.length;
+        } catch (err) {
+          log.warn(
+            { err, chatId },
+            "Slack appendStream failed; deferring delta",
+          );
+          return;
+        }
+      }
+    });
+  };
+
+  const flush = (): void => {
+    if (coalesceTimer) {
+      clearTimeout(coalesceTimer);
+      coalesceTimer = undefined;
+    }
+    if (finished || state === "fallback") return;
+    if (!started) {
+      if (!hasDeliverableAssistantText(streamableText())) return;
+      started = true;
+      enqueueStart();
+      return;
+    }
+    enqueueAppend();
+  };
+
+  const scheduleFlush = (): void => {
+    if (coalesceTimer || finished) return;
+    coalesceTimer = setTimeout(() => {
+      coalesceTimer = undefined;
+      flush();
+    }, coalesceMs);
+    (coalesceTimer as { unref?: () => void }).unref?.();
+  };
+
+  const countSegmentBoundary = (): void => {
+    const segment = segmentBuffer;
+    segmentBuffer = "";
+    if (segment.replace(NO_RESPONSE_INLINE_RE, "").trim().length > 0) {
+      deliveredSegmentCount += 1;
+    }
+  };
+
+  const observeTaskProgress = (msg: ServerMessage): void => {
+    if (msg.type === "ui_surface_show") {
+      const progress = getTaskProgressDataFromSurfaceData(msg.data);
+      if (!progress) return;
+      taskProgressBySurfaceId.set(msg.surfaceId, progress);
+    } else if (msg.type === "ui_surface_update") {
+      const existing = taskProgressBySurfaceId.get(msg.surfaceId);
+      const progress = mergeTaskProgressData(existing, msg.data);
+      if (!progress) return;
+      taskProgressBySurfaceId.set(msg.surfaceId, progress);
+    } else {
+      return;
+    }
+    activeProgress = taskProgressBySurfaceId.get(msg.surfaceId);
+    scheduleFlush();
+  };
+
+  return {
+    observeEvent(msg) {
+      if (finished) return;
+
+      if (msg.type === "ui_surface_show" || msg.type === "ui_surface_update") {
+        observeTaskProgress(msg);
+        return;
+      }
+      if (msg.type === "assistant_text_delta") {
+        if (pendingSegmentBoundary && msg.text.length > 0) {
+          if (needsBoundarySpace(rawText, msg.text)) {
+            rawText += " ";
+          }
+          pendingSegmentBoundary = false;
+        }
+        rawText += msg.text;
+        segmentBuffer += msg.text;
+        scheduleFlush();
+        return;
+      }
+      if (msg.type === "tool_use_start" || msg.type === "message_complete") {
+        countSegmentBoundary();
+        pendingSegmentBoundary = true;
+      }
+    },
+
+    async finish() {
+      finished = true;
+      if (coalesceTimer) {
+        clearTimeout(coalesceTimer);
+        coalesceTimer = undefined;
+      }
+
+      // A reply that completed before the first coalesced flush still streams
+      // as a single start→stop so the transcript holds one streamed message.
+      if (!started && hasDeliverableAssistantText(rawText)) {
+        started = true;
+        enqueueStart();
+      }
+
+      enqueueAppend();
+      enqueue(async () => {
+        if (state !== "streaming" || !streamTs) return;
+        const clean = cleanedText();
+        const remaining = clean.slice(confirmedLength);
+        const blocks = imageBlocks(clean);
+        const tasks = planTasks();
+        try {
+          await deliverChannelReply(replyCallbackUrl, {
+            chatId,
+            assistantId,
+            slackStream: {
+              action: "stop",
+              streamTs,
+              ...(remaining.length > 0 ? { markdownText: remaining } : {}),
+              ...(blocks ? { blocks } : {}),
+              ...(tasks ? { tasks } : {}),
+            },
+          });
+          confirmedLength = clean.length;
+        } catch (err) {
+          log.warn(
+            { err, chatId },
+            "Slack stopStream failed; falling back to durable delivery",
+          );
+          state = "fallback";
+        }
+      });
+
+      await opChain;
+
+      if (state === "streaming" && streamTs) {
+        return { mode: "streamed", messageTs: streamTs, deliveredSegmentCount };
+      }
+      return { mode: "fallback" };
+    },
+  };
+}

package/src/runtime/slack-task-progress.ts

@@ -0,0 +1,95 @@
+import type { SlackStreamTask } from "@vellumai/gateway-client";
+
+/**
+ * A single step of a `task_progress` UI surface: an ordered, status-bearing
+ * unit of work the assistant reports while a turn runs.
+ */
+export type TaskProgressStep = {
+  label: string;
+  status: "pending" | "in_progress" | "completed" | "failed";
+};
+
+export type TaskProgressData = {
+  steps: TaskProgressStep[];
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Read a `task_progress` surface payload into typed steps, if it is one. */
+export function getTaskProgressDataFromSurfaceData(
+  data: unknown,
+): TaskProgressData | undefined {
+  if (!isRecord(data)) return undefined;
+  if (data.template !== "task_progress") return undefined;
+  return parseTaskProgressData(data.templateData);
+}
+
+function parseTaskProgressData(value: unknown): TaskProgressData | undefined {
+  if (!isRecord(value) || !Array.isArray(value.steps)) return undefined;
+
+  const steps = value.steps.flatMap((step): TaskProgressStep[] => {
+    if (!isRecord(step)) return [];
+    if (typeof step.label !== "string") return [];
+    if (
+      step.status !== "pending" &&
+      step.status !== "in_progress" &&
+      step.status !== "completed" &&
+      step.status !== "failed"
+    ) {
+      return [];
+    }
+    return [{ label: step.label, status: step.status }];
+  });
+
+  return steps.length > 0 ? { steps } : undefined;
+}
+
+/**
+ * Apply a `ui_surface_update` payload onto the steps already known for a
+ * surface. A full `task_progress` payload replaces the steps; a partial
+ * `templateData` update is merged over the existing steps.
+ */
+export function mergeTaskProgressData(
+  existing: TaskProgressData | undefined,
+  data: unknown,
+): TaskProgressData | undefined {
+  if (!isRecord(data)) return existing;
+  const update = getTaskProgressDataFromSurfaceData(data);
+  if (update) return update;
+  if (!existing || !("templateData" in data)) return existing;
+
+  return parseTaskProgressData({
+    steps: existing.steps,
+    ...(isRecord(data.templateData) ? data.templateData : {}),
+  });
+}
+
+const TASK_PROGRESS_STATUS_TO_SLACK: Record<
+  TaskProgressStep["status"],
+  SlackStreamTask["status"]
+> = {
+  pending: "pending",
+  in_progress: "in_progress",
+  completed: "complete",
+  failed: "error",
+};
+
+/**
+ * Map ordered `task_progress` steps onto Slack streaming task cards. Step
+ * position supplies the stable card `id` (a step keeps its index across
+ * updates), the label becomes the card title, and the surface status maps onto
+ * Slack's task-card status vocabulary.
+ *
+ * @see https://docs.slack.dev/ai/developing-agents
+ */
+export function toSlackStreamTasks(
+  progress: TaskProgressData,
+): SlackStreamTask[] {
+  return progress.steps.map((step, index) => ({
+    id: `task-${index}`,
+    title: step.label,
+    status: TASK_PROGRESS_STATUS_TO_SLACK[step.status],
+  }));
+}

package/src/runtime/sync/resource-sync-events.ts

@@ -9,6 +9,17 @@ import { getAvatarImagePath } from "../../util/platform.js";
 import { broadcastMessage } from "../assistant-event-hub.js";
 import { publishSyncInvalidation } from "./sync-publisher.js";
 
+/**
+ * Derive the initiating client's id from request headers so a sync publish can
+ * carry it as `originClientId`, letting that client self-echo-suppress its own
+ * invalidation. Trimmed; blank/absent headers yield `undefined`.
+ */
+export function getOriginClientId(
+  headers: Record<string, string> | undefined,
+): string | undefined {
+  return headers?.["x-vellum-client-id"]?.trim() || undefined;
+}
+
 export function publishAvatarChanged(originClientId?: string): void {
   broadcastMessage({
     type: "avatar_updated",
@@ -50,6 +61,10 @@ export function publishAppsChanged(originClientId?: string): void {
   void publishSyncInvalidation([SYNC_TAGS.appsList], originClientId);
 }
 
+export function publishPluginsChanged(originClientId?: string): void {
+  void publishSyncInvalidation([SYNC_TAGS.pluginsList], originClientId);
+}
+
 /**
  * Reasons that change the *shape* of the conversation list — a row is
  * added, removed, or its position changes. These require web clients to
@@ -160,6 +175,16 @@ export function publishConversationTitleChanged(
   );
 }
 
+export function publishConversationEnabledPluginsChanged(
+  conversationId: string,
+  originClientId?: string,
+): void {
+  void publishSyncInvalidation(
+    [SYNC_TAGS.conversationsList, conversationMetadataSyncTag(conversationId)],
+    originClientId,
+  );
+}
+
 export function publishConversationInferenceProfileChanged(
   params: {
     conversationId: string;

package/src/runtime/tool-grant-request-helper.ts

@@ -23,6 +23,7 @@ import {
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
 import { getLogger } from "../util/logger.js";
 import { getGuardianBinding } from "./channel-verification-service.js";
+import { resolveDecidableGuardianPrincipalId } from "./local-actor-identity.js";
 import { GUARDIAN_APPROVAL_TTL_MS } from "./routes/channel-route-shared.js";
 
 const log = getLogger("tool-grant-request-helper");
@@ -87,6 +88,21 @@ export async function createOrReuseToolGrantRequest(
     return { failed: true, reason: "no_guardian_binding" };
   }
 
+  // A binding with no principal is unresolved, not empty: adopt the vellum
+  // anchor principal so the resulting request is decidable by the guardian.
+  // When neither resolves, fail closed — a principal-less tool_grant_request
+  // can never be authorized by anyone.
+  const guardianPrincipalId = await resolveDecidableGuardianPrincipalId(
+    binding.guardianPrincipalId,
+  );
+  if (!guardianPrincipalId) {
+    log.warn(
+      { sourceChannel, assistantId },
+      "Guardian principal unresolved for tool grant request escalation",
+    );
+    return { failed: true, reason: "no_guardian_binding" };
+  }
+
   // Deduplicate: skip creation if there is already a pending canonical request
   // for the same requester + conversation + tool + input digest + guardian.
   // Guardian identity is included so that after a guardian rebind, old requests
@@ -132,7 +148,7 @@ export async function createOrReuseToolGrantRequest(
     requesterExternalUserId,
     requesterChatId: requesterChatId ?? undefined,
     guardianExternalUserId: binding.guardianExternalUserId,
-    guardianPrincipalId: binding.guardianPrincipalId,
+    guardianPrincipalId,
     toolName,
     inputDigest,
     questionText,

package/src/runtime/trust-class.test.ts

@@ -0,0 +1,141 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { resolveCapabilities } from "./capabilities.js";
+import {
+  derivePersonaTrustFlags,
+  isContactTrustClass,
+  type PersonaTrustFlags,
+  trustClassSchema,
+} from "./trust-class.js";
+
+describe("isContactTrustClass", () => {
+  test("matches exactly the trusted/unverified contact pair", () => {
+    expect(isContactTrustClass("trusted_contact")).toBe(true);
+    expect(isContactTrustClass("unverified_contact")).toBe(true);
+    expect(isContactTrustClass("guardian")).toBe(false);
+    expect(isContactTrustClass("unknown")).toBe(false);
+  });
+
+  test("rejects undefined and legacy/foreign metadata strings", () => {
+    expect(isContactTrustClass(undefined)).toBe(false);
+    // Values that appear in persisted turn metadata from older builds.
+    expect(isContactTrustClass("non_guardian")).toBe(false);
+    expect(isContactTrustClass("non-guardian")).toBe(false);
+    expect(isContactTrustClass("")).toBe(false);
+  });
+
+  test("agrees with derivePersonaTrustFlags for every trust class", () => {
+    // The predicate and the persona flags encode the same grouping; pin them
+    // together so neither can drift without failing here.
+    for (const trustClass of trustClassSchema.options) {
+      expect(isContactTrustClass(trustClass)).toBe(
+        derivePersonaTrustFlags(trustClass).isTrustedContact,
+      );
+    }
+  });
+});
+
+describe("derivePersonaTrustFlags", () => {
+  test("guardian derives the guardian flag only", () => {
+    expect(derivePersonaTrustFlags("guardian")).toEqual({
+      trustClass: "guardian",
+      isGuardian: true,
+      isTrustedContact: false,
+      isStranger: false,
+    });
+  });
+
+  test("trusted_contact and unverified_contact derive identical contact flags", () => {
+    // The admission-only equivalence documented on trustClassSchema: the two
+    // classes must never drift apart at the persona layer.
+    const expected: PersonaTrustFlags = {
+      trustClass: "trusted_contact",
+      isGuardian: false,
+      isTrustedContact: true,
+      isStranger: false,
+    };
+    expect(derivePersonaTrustFlags("trusted_contact")).toEqual(expected);
+    expect(derivePersonaTrustFlags("unverified_contact")).toEqual({
+      ...expected,
+      trustClass: "unverified_contact",
+    });
+  });
+
+  test("unknown derives the stranger flag only", () => {
+    expect(derivePersonaTrustFlags("unknown")).toEqual({
+      trustClass: "unknown",
+      isGuardian: false,
+      isTrustedContact: false,
+      isStranger: true,
+    });
+  });
+
+  test("an unresolved actor (undefined) fails closed to stranger", () => {
+    // Disclosure gating must default to the guardrail, never to a guardian
+    // exemption, when no actor was resolved for the turn.
+    expect(derivePersonaTrustFlags(undefined)).toEqual({
+      trustClass: "unknown",
+      isGuardian: false,
+      isTrustedContact: false,
+      isStranger: true,
+    });
+  });
+
+  test("exactly one flag is true for every trust class", () => {
+    // Iterates the Zod enum so a newly added class is covered automatically
+    // (the helper itself won't compile until the new class gets a case).
+    for (const trustClass of trustClassSchema.options) {
+      const flags = derivePersonaTrustFlags(trustClass);
+      const trueCount = [
+        flags.isGuardian,
+        flags.isTrustedContact,
+        flags.isStranger,
+      ].filter(Boolean).length;
+      expect(trueCount).toBe(1);
+      expect(flags.trustClass).toBe(trustClass);
+    }
+  });
+
+  describe("independence from the deployment auth posture", () => {
+    const prior = process.env.DISABLE_HTTP_AUTH;
+
+    afterEach(() => {
+      if (prior === undefined) {
+        delete process.env.DISABLE_HTTP_AUTH;
+      } else {
+        process.env.DISABLE_HTTP_AUTH = prior;
+      }
+    });
+
+    test("an unresolved actor stays stranger under DISABLE_HTTP_AUTH", () => {
+      // Deliberate divergence from resolveTrustClass, which fail-safes an
+      // unresolved turn to guardian under the local auth-bypass for
+      // control-plane gates. The disclosure guardrail must instead fail closed
+      // — this test exists so the helper is never "unified" onto that bypass.
+      process.env.DISABLE_HTTP_AUTH = "true";
+      expect(derivePersonaTrustFlags(undefined).isStranger).toBe(true);
+      expect(derivePersonaTrustFlags("trusted_contact").isGuardian).toBe(false);
+    });
+  });
+
+  test("persona partition matches the capability matrix's prompt guidance", () => {
+    // The persona flags and resolveCapabilities().promptTrustGuidance encode
+    // the same three-way partition (guardian / known contact / stranger) in two
+    // homes. Pin them together so persona framing and turn-context guidance
+    // can't drift apart when either table changes.
+    const guidanceByFlag: Record<string, string> = {
+      isGuardian: "none",
+      isTrustedContact: "social-engineering-defense",
+      isStranger: "stranger-warning",
+    };
+    for (const trustClass of trustClassSchema.options) {
+      const flags = derivePersonaTrustFlags(trustClass);
+      const guidance = resolveCapabilities(trustClass).promptTrustGuidance;
+      for (const [flag, expected] of Object.entries(guidanceByFlag)) {
+        if (flags[flag as keyof PersonaTrustFlags]) {
+          expect(guidance).toBe(expected as typeof guidance);
+        }
+      }
+    }
+  });
+});