@vellumai/assistant 0.10.2 → 0.10.3-dev.202606252046.9075fd5

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

@@ -12,7 +12,7 @@
  */
 
 import type { ChannelId } from "../channels/types.js";
-import { findGuardianForChannel } from "../contacts/contact-store.js";
+import { getGuardianDelivery } from "../contacts/guardian-delivery-reader.js";
 import type { ChannelStatus } from "../contacts/types.js";
 import {
   createCanonicalGuardianRequest,
@@ -25,6 +25,7 @@ import {
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
 import type { GuardianResolutionSource } from "../notifications/signal.js";
 import { getLogger } from "../util/logger.js";
+import { resolveAnchoredGuardian } from "./anchored-guardian.js";
 import { GUARDIAN_APPROVAL_TTL_MS } from "./routes/channel-route-shared.js";
 
 const log = getLogger("access-request-helper");
@@ -70,12 +71,12 @@ export type AccessRequestResult =
  * trust anchor and only accepts source-channel contacts that match it. This
  * prevents stale or cross-assistant contacts from being bound to the request.
  *
- * This is intentionally synchronous with respect to the canonical store writes
- * and fire-and-forget for the notification signal emission.
+ * The canonical store writes complete before this resolves; the notification
+ * signal emission is fire-and-forget.
  */
-export function notifyGuardianOfAccessRequest(
+export async function notifyGuardianOfAccessRequest(
   params: AccessRequestParams,
-): AccessRequestResult {
+): Promise<AccessRequestResult> {
   const {
     canonicalAssistantId,
     sourceChannel,
@@ -94,40 +95,18 @@ export function notifyGuardianOfAccessRequest(
     return { notified: false, reason: "no_sender_id" };
   }
 
-  // Resolve guardian identity with assistant-anchored strategy:
-  // 1. Ensure the assistant has a vellum guardian principal (trust anchor)
-  // 2. Use source-channel guardian only when principal matches anchor
-  // 3. Fallback to vellum guardian identity for this assistant principal
-  let guardianExternalUserId: string | null = null;
-  let guardianPrincipalId: string | null = null;
-  let guardianBindingChannel: string | null = null;
-  let guardianResolutionSource: GuardianResolutionSource = "none";
-
-  const vellumGuardian = findGuardianForChannel("vellum");
-  const assistantGuardianPrincipalId = vellumGuardian?.contact.principalId;
-
-  // Try source-channel guardian, but only if it maps to the assistant's
-  // anchored principal. This blocks cross-assistant/stale contact selection.
-  const sourceGuardian = findGuardianForChannel(sourceChannel);
-  if (
-    assistantGuardianPrincipalId &&
-    sourceGuardian &&
-    sourceGuardian.contact.principalId === assistantGuardianPrincipalId
-  ) {
-    guardianExternalUserId = sourceGuardian.channel.address;
-    guardianPrincipalId = sourceGuardian.contact.principalId;
-    guardianBindingChannel = sourceGuardian.channel.type;
-    guardianResolutionSource = "source-channel-contact";
-  }
-
-  // Access requests always require a principal. If source-channel resolution
-  // did not match the assistant anchor, use the anchored vellum identity.
-  if (!guardianPrincipalId && vellumGuardian) {
-    guardianExternalUserId = vellumGuardian.channel.address;
-    guardianPrincipalId = assistantGuardianPrincipalId ?? null;
-    guardianBindingChannel = guardianBindingChannel ?? "vellum";
-    guardianResolutionSource = "vellum-anchor";
-  }
+  // Resolve guardian identity with the assistant-anchored strategy (gateway
+  // source-channel match validated against the vellum anchor, else the vellum
+  // anchor).
+  const anchored = resolveAnchoredGuardian({
+    guardians: await getGuardianDelivery(),
+    sourceChannel,
+  });
+  const guardianExternalUserId = anchored?.address ?? null;
+  const guardianPrincipalId = anchored?.principalId ?? null;
+  const guardianBindingChannel = anchored?.channelType ?? null;
+  const guardianResolutionSource: GuardianResolutionSource =
+    anchored?.source ?? "none";
 
   log.debug(
     {

package/src/runtime/actor-trust-resolver.ts

@@ -17,15 +17,23 @@
  */
 
 import type { ChannelId } from "../channels/types.js";
+import { findContactByAddress } from "../contacts/contact-store.js";
 import {
-  findContactByAddress,
-  findGuardianForChannel,
-} from "../contacts/contact-store.js";
+  guardianForChannel,
+  peekCachedGuardianDelivery,
+} from "../contacts/guardian-delivery-reader.js";
 import { channelStatusToMemberStatus } from "../contacts/member-status.js";
-import type { ContactChannel, ContactWithChannels } from "../contacts/types.js";
+import type {
+  ChannelPolicy,
+  ChannelStatus,
+  ContactChannel,
+  ContactRole,
+  ContactWithChannels,
+} from "../contacts/types.js";
 import type { TrustContext } from "../daemon/trust-context.js";
 import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
 import { getLogger } from "../util/logger.js";
+import { getCachedMemberAcl } from "./member-verdict-cache.js";
 
 const log = getLogger("actor-trust-resolver");
 
@@ -78,10 +86,18 @@ export interface ActorTrustContext {
   } | null;
   /** Canonical principal ID from the guardian binding. */
   guardianPrincipalId?: string;
-  /** Resolved contact + channel for this sender, if any. */
+  /**
+   * Resolved contact + channel for this sender, if any. The ACL view
+   * (status/policy/role) is carried here rather than on the contact/channel
+   * objects, sourced from the gateway verdict — the verdict path reads it
+   * inline, the sync fallback from the in-memory member-verdict cache.
+   */
   memberRecord: {
     contact: ContactWithChannels;
     channel: ContactChannel;
+    status: ChannelStatus;
+    policy: ChannelPolicy;
+    role: ContactRole;
   } | null;
   /** Trust classification. */
   trustClass: TrustClass;
@@ -175,21 +191,27 @@ export function resolveActorTrust(
   }
 
   // --- Guardian lookup ---
-  const guardianResult = findGuardianForChannel(input.sourceChannel);
+  // Sync read of the gateway guardian delivery from the IO-free cache snapshot
+  // (kept warm by the async hot paths + daemon-startup warm). A cold cache
+  // yields no guardian match, the same outcome as no binding.
+  const cachedGuardians = peekCachedGuardianDelivery({
+    channelTypes: [input.sourceChannel],
+  });
+  const guardianDelivery = cachedGuardians
+    ? guardianForChannel(cachedGuardians, input.sourceChannel)
+    : undefined;
   let guardianBindingMatch: ActorTrustContext["guardianBindingMatch"] = null;
   let guardianPrincipalId: string | undefined;
   let isGuardian = false;
 
-  if (guardianResult) {
-    const { contact: guardianContact, channel: guardianChannel } =
-      guardianResult;
+  if (guardianDelivery) {
     guardianBindingMatch = {
-      guardianExternalUserId: guardianChannel.address,
-      guardianDeliveryChatId: guardianChannel.externalChatId,
+      guardianExternalUserId: guardianDelivery.address,
+      guardianDeliveryChatId: guardianDelivery.externalChatId ?? null,
     };
-    guardianPrincipalId = guardianContact.principalId ?? undefined;
+    guardianPrincipalId = guardianDelivery.principalId ?? undefined;
     isGuardian =
-      guardianChannel.address.toLowerCase() === canonicalSenderId.toLowerCase();
+      guardianDelivery.address.toLowerCase() === canonicalSenderId.toLowerCase();
   }
 
   log.debug(
@@ -213,7 +235,12 @@ export function resolveActorTrust(
       ch.address.toLowerCase() === canonicalSenderId.toLowerCase(),
   );
   if (byAddress && byAddressChannel) {
-    memberRecord = { contact: byAddress, channel: byAddressChannel };
+    const acl = getCachedMemberAcl(input.sourceChannel, canonicalSenderId);
+    if (acl) {
+      memberRecord = { contact: byAddress, channel: byAddressChannel, ...acl };
+    }
+    // Fail-closed: already in the sync fallback (no live verdict) and no cached
+    // verdict → leave memberRecord null so trustClass resolves to unknown.
   }
 
   log.debug(
@@ -252,7 +279,7 @@ export function resolveActorTrust(
   if (isGuardian) {
     trustClass = "guardian";
   } else if (memberMatchesSender && memberRecord) {
-    const status = memberRecord.channel.status;
+    const status = memberRecord.status;
     if (status === "active") {
       trustClass = "trusted_contact";
     } else if (status === "unverified" || status === "pending") {
@@ -323,12 +350,12 @@ export function toTrustContext(
     requesterMemberDisplayName: ctx.actorMetadata.memberDisplayName,
     requesterExternalUserId: ctx.canonicalSenderId ?? undefined,
     requesterChatId: conversationExternalId,
-    // Member grounding from a real memberRecord (voice path); the verdict path
-    // (memberRecord=null) stamps these from the verdict instead.
+    // Member grounding from the resolved memberRecord (voice + verdict paths
+    // both populate it).
     requesterContactId: ctx.memberRecord?.contact.id,
     memberStatus: ctx.memberRecord
-      ? channelStatusToMemberStatus(ctx.memberRecord.channel.status)
+      ? channelStatusToMemberStatus(ctx.memberRecord.status)
       : undefined,
-    memberPolicy: ctx.memberRecord?.channel.policy,
+    memberPolicy: ctx.memberRecord?.policy,
   };
 }

package/src/runtime/anchored-guardian.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Unit tests for `resolveAnchoredGuardian`.
+ *
+ * Covers the gateway arms (source-channel match validated against the vellum
+ * anchor, vellum-anchor fallback) and the cosmetic `requireAnchorPrincipal`
+ * guard.
+ */
+import { describe, expect, test } from "bun:test";
+
+import type { GuardianDelivery } from "@vellumai/gateway-client";
+
+import { resolveAnchoredGuardian } from "./anchored-guardian.js";
+
+function gw(g: Partial<GuardianDelivery> & { channelType: string; address: string }): GuardianDelivery {
+  return {
+    contactId: `c-${g.channelType}`,
+    status: "active",
+    ...g,
+  };
+}
+
+describe("resolveAnchoredGuardian — gateway arm", () => {
+  test("source-channel guardian matching the anchor wins", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: [
+        gw({ channelType: "vellum", address: "v-addr", principalId: "p-anchor", displayName: "Vellum" }),
+        gw({ channelType: "telegram", address: "tg-addr", principalId: "p-anchor", displayName: "Alice" }),
+      ],
+      sourceChannel: "telegram",
+    });
+    expect(result).toEqual({
+      principalId: "p-anchor",
+      address: "tg-addr",
+      displayName: "Alice",
+      channelType: "telegram",
+      source: "source-channel-contact",
+    });
+  });
+
+  test("source-channel guardian NOT matching the anchor falls back to vellum-anchor", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: [
+        gw({ channelType: "vellum", address: "v-addr", principalId: "p-anchor", displayName: "Vellum" }),
+        gw({ channelType: "telegram", address: "tg-addr", principalId: "p-other", displayName: "Stale" }),
+      ],
+      sourceChannel: "telegram",
+    });
+    expect(result).toEqual({
+      principalId: "p-anchor",
+      address: "v-addr",
+      displayName: "Vellum",
+      channelType: "vellum",
+      source: "vellum-anchor",
+    });
+  });
+
+  test("no source-channel guardian falls back to vellum-anchor", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: [
+        gw({ channelType: "vellum", address: "v-addr", principalId: "p-anchor", displayName: "Vellum" }),
+      ],
+      sourceChannel: "telegram",
+    });
+    expect(result?.source).toBe("vellum-anchor");
+    expect(result?.principalId).toBe("p-anchor");
+  });
+});
+
+describe("resolveAnchoredGuardian — gateway empty", () => {
+  test("null gateway list returns null", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: null,
+      sourceChannel: "telegram",
+    });
+    expect(result).toBeNull();
+  });
+
+  test("empty gateway list returns null", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: [],
+      sourceChannel: "telegram",
+    });
+    expect(result).toBeNull();
+  });
+});
+
+describe("resolveAnchoredGuardian — requireAnchorPrincipal (cosmetic label)", () => {
+  test("vellum guardian with a null principal degrades to null", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: [
+        gw({ channelType: "vellum", address: "v-addr", principalId: null, displayName: "Vellum" }),
+      ],
+      sourceChannel: "telegram",
+      requireAnchorPrincipal: true,
+    });
+    expect(result).toBeNull();
+  });
+
+  test("without requireAnchorPrincipal a null-principal vellum still resolves", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: [
+        gw({ channelType: "vellum", address: "v-addr", principalId: null, displayName: "Vellum" }),
+      ],
+      sourceChannel: "telegram",
+    });
+    expect(result?.source).toBe("vellum-anchor");
+    expect(result?.principalId).toBeNull();
+  });
+});

package/src/runtime/anchored-guardian.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared anchored-guardian resolution.
+ *
+ * Resolves the guardian identity for an inbound access request using the
+ * assistant's vellum principal as the trust anchor: a source-channel guardian
+ * is only accepted when its principal matches the anchor, otherwise the vellum
+ * anchor identity is used. This blocks stale or cross-assistant contacts from
+ * being bound to a request.
+ *
+ * Resolves from the gateway delivery list, the source of truth for guardian
+ * principals.
+ */
+
+import type { GuardianDelivery } from "@vellumai/gateway-client";
+
+import type { ChannelId } from "../channels/types.js";
+import { guardianForChannel } from "../contacts/guardian-delivery-reader.js";
+import type { GuardianResolutionSource } from "../notifications/signal.js";
+
+/** Resolved guardian identity, anchored on the assistant's vellum principal. */
+export interface AnchoredGuardian {
+  principalId: string | null;
+  address: string;
+  displayName: string | null;
+  channelType: string;
+  source: GuardianResolutionSource;
+}
+
+export interface ResolveAnchoredGuardianInput {
+  /** Gateway delivery list; `null` when the gateway read failed/was empty. */
+  guardians: GuardianDelivery[] | null;
+  sourceChannel: ChannelId;
+  /**
+   * Require a non-null anchor principal for the vellum-anchor arm. When the
+   * vellum guardian has no principal, return `null` instead of a vellum-anchor
+   * record. Matches the cosmetic label path, which degrades to the default
+   * reference when the anchor principal is absent.
+   */
+  requireAnchorPrincipal?: boolean;
+}
+
+/**
+ * Resolve the anchored guardian for `sourceChannel`, or `null` when none can be
+ * resolved. Gateway source-channel match → that record; gateway anchor-only →
+ * vellum-anchor.
+ */
+export function resolveAnchoredGuardian(
+  input: ResolveAnchoredGuardianInput,
+): AnchoredGuardian | null {
+  const { sourceChannel, requireAnchorPrincipal } = input;
+  const guardians = input.guardians ?? [];
+
+  const vellumGuardian = guardianForChannel(guardians, "vellum");
+  const anchorPrincipalId = vellumGuardian?.principalId;
+
+  let resolved: AnchoredGuardian | null = null;
+
+  // Source-channel guardian, but only when it maps to the assistant's anchored
+  // principal. This blocks cross-assistant/stale binding selection.
+  const sourceGuardian = guardianForChannel(guardians, sourceChannel);
+  if (
+    anchorPrincipalId &&
+    sourceGuardian &&
+    sourceGuardian.principalId === anchorPrincipalId
+  ) {
+    resolved = {
+      principalId: sourceGuardian.principalId,
+      address: sourceGuardian.address,
+      displayName: sourceGuardian.displayName ?? null,
+      channelType: sourceGuardian.channelType,
+      source: "source-channel-contact",
+    };
+  } else if (vellumGuardian && !(requireAnchorPrincipal && !anchorPrincipalId)) {
+    // Source-channel resolution did not match the anchor → use the anchored
+    // vellum identity.
+    resolved = {
+      principalId: anchorPrincipalId ?? null,
+      address: vellumGuardian.address,
+      displayName: vellumGuardian.displayName ?? null,
+      channelType: "vellum",
+      source: "vellum-anchor",
+    };
+  }
+
+  return resolved;
+}

package/src/runtime/assistant-event-hub.ts

@@ -749,7 +749,7 @@ async function createCanonicalRequestForConfirmation(
     });
 
     if (trustContext && conversation) {
-      bridgeConfirmationRequestToGuardian({
+      await bridgeConfirmationRequestToGuardian({
         canonicalRequest,
         trustContext,
         conversationId,

package/src/runtime/assistant-stream-state.ts

@@ -50,14 +50,21 @@
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
+import {
+  SSE_REPLAY_RING_AGE_LIMIT_MS,
+  SSE_REPLAY_RING_COUNT_LIMIT,
+} from "../api/constants/sse-replay.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import type { AssistantEvent } from "./assistant-event.js";
 
 // ── Tunables ─────────────────────────────────────────────────────────
 
-const RING_COUNT_LIMIT = 200;
+// Count and age bounds on the replay ring. Shared with the web client
+// (via `@vellumai/assistant-api`) so its seq-gap tolerance is sized
+// against the same numbers the daemon buffers against.
+const RING_COUNT_LIMIT = SSE_REPLAY_RING_COUNT_LIMIT;
 const RING_SIZE_LIMIT_BYTES = 256 * 1024;
-const RING_AGE_LIMIT_MS = 30_000;
+const RING_AGE_LIMIT_MS = SSE_REPLAY_RING_AGE_LIMIT_MS;
 
 /**
  * Cap on how many conversations retain a persisted-seq entry. Unlike the

package/src/runtime/auth/__tests__/require-bound-guardian.test.ts

@@ -0,0 +1,99 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { GuardianDelivery } from "@vellumai/gateway-client";
+
+let mockGuardians: GuardianDelivery[] | null = null;
+let authDisabled = false;
+
+mock.module("../../../contacts/guardian-delivery-reader.js", () => ({
+  getGuardianDelivery: async () => mockGuardians,
+  // Real active-status selector so the auth gate enforces status==="active".
+  guardianForChannel: (list: GuardianDelivery[], channelType: string) =>
+    list.find((g) => g.channelType === channelType && g.status === "active"),
+}));
+
+mock.module("../../../config/env.js", () => ({
+  isHttpAuthDisabled: () => authDisabled,
+}));
+
+import { requireBoundGuardian } from "../require-bound-guardian.js";
+import type { AuthContext } from "../types.js";
+
+function ctx(actorPrincipalId?: string): AuthContext {
+  return {
+    subject: "sub",
+    principalType: "actor",
+    assistantId: "self",
+    actorPrincipalId,
+    scopeProfile: "actor_client_v1",
+    scopes: new Set(),
+    policyEpoch: 0,
+  };
+}
+
+function guardian(principalId: string): GuardianDelivery {
+  return {
+    channelType: "vellum",
+    contactId: "guardian-contact",
+    principalId,
+    address: principalId,
+    status: "active",
+  };
+}
+
+describe("requireBoundGuardian", () => {
+  beforeEach(() => {
+    mockGuardians = null;
+    authDisabled = false;
+  });
+
+  test("admits the bound guardian", async () => {
+    mockGuardians = [guardian("vellum-principal-abc")];
+    const result = await requireBoundGuardian(ctx("vellum-principal-abc"));
+    expect(result).toBeNull();
+  });
+
+  test("denies a non-guardian actor", async () => {
+    mockGuardians = [guardian("vellum-principal-abc")];
+    const result = await requireBoundGuardian(ctx("vellum-principal-other"));
+    expect(result).not.toBeNull();
+    expect(result!.status).toBe(403);
+  });
+
+  test("denies when actor principal is missing", async () => {
+    mockGuardians = [guardian("vellum-principal-abc")];
+    const result = await requireBoundGuardian(ctx(undefined));
+    expect(result).not.toBeNull();
+    expect(result!.status).toBe(403);
+  });
+
+  test("fails closed on a null list (gateway unreachable)", async () => {
+    mockGuardians = null;
+    const result = await requireBoundGuardian(ctx("vellum-principal-abc"));
+    expect(result).not.toBeNull();
+    expect(result!.status).toBe(403);
+  });
+
+  test("denies when no vellum guardian is bound", async () => {
+    mockGuardians = [];
+    const result = await requireBoundGuardian(ctx("vellum-principal-abc"));
+    expect(result).not.toBeNull();
+    expect(result!.status).toBe(403);
+  });
+
+  test("denies a non-active (revoked) vellum row matching the actor", async () => {
+    mockGuardians = [
+      { ...guardian("vellum-principal-abc"), status: "revoked" },
+    ];
+    const result = await requireBoundGuardian(ctx("vellum-principal-abc"));
+    expect(result).not.toBeNull();
+    expect(result!.status).toBe(403);
+  });
+
+  test("dev bypass admits when auth is disabled", async () => {
+    authDisabled = true;
+    mockGuardians = null;
+    const result = await requireBoundGuardian(ctx(undefined));
+    expect(result).toBeNull();
+  });
+});

package/src/runtime/auth/require-bound-guardian.ts

@@ -1,15 +1,20 @@
 import { isHttpAuthDisabled } from "../../config/env.js";
-import { findGuardianForChannel } from "../../contacts/contact-store.js";
+import {
+  getGuardianDelivery,
+  guardianForChannel,
+} from "../../contacts/guardian-delivery-reader.js";
 import { httpError } from "../http-errors.js";
 import type { AuthContext } from "./types.js";
 
 /**
  * Verify the actor from AuthContext is the bound guardian for the vellum channel.
- * Returns an error Response if not, or null if allowed.
+ * Sources the guardian from the gateway binding and fails closed when the
+ * gateway is unreachable (null list). Returns an error Response if not
+ * authorized, or null if allowed.
  */
-export function requireBoundGuardian(
+export async function requireBoundGuardian(
   authContext: AuthContext,
-): Response | null {
+): Promise<Response | null> {
   // Dev bypass: when auth is disabled, skip guardian binding check
   // (mirrors enforcePolicy dev bypass in route-policy.ts)
   if (isHttpAuthDisabled()) {
@@ -22,17 +27,22 @@ export function requireBoundGuardian(
       403,
     );
   }
-  const guardianResult = findGuardianForChannel("vellum");
-  if (!guardianResult) {
-    // No guardian yet — in pre-bootstrap state, allow through
-    return null;
-  }
-  if (guardianResult.channel.address !== authContext.actorPrincipalId) {
+  const guardians = await getGuardianDelivery({ channelTypes: ["vellum"] });
+  if (!guardians) {
+    // Gateway unreachable — fail closed.
     return httpError(
       "FORBIDDEN",
       "Actor is not the bound guardian for this channel",
       403,
     );
   }
-  return null;
+  const guardian = guardianForChannel(guardians, "vellum");
+  if (guardian && guardian.principalId === authContext.actorPrincipalId) {
+    return null;
+  }
+  return httpError(
+    "FORBIDDEN",
+    "Actor is not the bound guardian for this channel",
+    403,
+  );
 }