@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240317.ea25efe

package/src/runtime/anchored-guardian.ts

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ *
+ * Gateway-first: resolves from the gateway delivery list, then falls back to
+ * the LOCAL dual-written binding when the gateway read is empty/unavailable
+ * (restart, timeout, malformed IPC). The local fallback is transitional and is
+ * removed in a later step.
+ */
+
+import type { GuardianDelivery } from "@vellumai/gateway-client";
+
+import type { ChannelId } from "../channels/types.js";
+import { findGuardianForChannel } from "../contacts/contact-store.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;
+  /**
+   * Fall back to the LOCAL dual-written binding when the gateway arm resolves
+   * nothing. Access-request enables this to avoid an undecidable request; the
+   * cosmetic guardian-label path leaves it off so a missing gateway read
+   * degrades gracefully to the default reference.
+   */
+  useLocalFallback?: boolean;
+  /**
+   * 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; gateway empty + local has it → local fallback record.
+ */
+export function resolveAnchoredGuardian(
+  input: ResolveAnchoredGuardianInput,
+): AnchoredGuardian | null {
+  const { sourceChannel, useLocalFallback, 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",
+    };
+  }
+
+  // Gateway resolved a principal — done.
+  if (resolved?.principalId) {
+    return resolved;
+  }
+
+  if (!useLocalFallback) {
+    return resolved;
+  }
+
+  // Fallback: gateway read was empty/unavailable (or carried no principal), so
+  // resolve from the LOCAL dual-written binding to avoid an undecidable
+  // request. A local match overwrites the principal-less gateway record; with
+  // no local match the gateway record (if any) is retained.
+  const localVellum = findGuardianForChannel("vellum");
+  const localAnchorPrincipalId = localVellum?.contact.principalId;
+  const localSource = findGuardianForChannel(sourceChannel);
+  if (
+    localAnchorPrincipalId &&
+    localSource &&
+    localSource.contact.principalId === localAnchorPrincipalId
+  ) {
+    return {
+      principalId: localSource.contact.principalId,
+      address: localSource.channel.address,
+      displayName: localSource.contact.displayName,
+      channelType: localSource.channel.type,
+      source: "source-channel-contact",
+    };
+  }
+  if (localVellum) {
+    return {
+      principalId: localAnchorPrincipalId ?? null,
+      address: localVellum.channel.address,
+      displayName: localVellum.contact.displayName,
+      channelType: "vellum",
+      source: "vellum-anchor",
+    };
+  }
+
+  return resolved;
+}

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,
+  );
 }

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

@@ -1,3 +1,4 @@
+import { stripVellumLinks } from "../daemon/assistant-attachments.js";
 import type { RenderedHistoryContent } from "../daemon/handlers/shared.js";
 import { renderHistoryContent } from "../daemon/handlers/shared.js";
 import { getAttachmentMetadataForMessage } from "../memory/attachments-store.js";
@@ -64,9 +65,11 @@ function toDeliverableTextSegments(
   textSegments: string[],
   fallbackText?: string,
 ): string[] {
-  const nonEmptySegments = textSegments.filter(
-    (segment) => segment.trim().length > 0 && !NO_RESPONSE_RE.test(segment),
-  );
+  const nonEmptySegments = textSegments
+    .map(stripVellumLinks)
+    .filter(
+      (segment) => segment.trim().length > 0 && !NO_RESPONSE_RE.test(segment),
+    );
   if (nonEmptySegments.length > 0) return nonEmptySegments;
   // If the only text was <no_response/>, treat as intentional silence —
   // do not fall back to fallbackText.

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

@@ -11,6 +11,10 @@ import { v4 as uuid } from "uuid";
 
 import { findGuardianForChannel } from "../contacts/contact-store.js";
 import { revokeGuardianBinding } from "../contacts/contacts-write.js";
+import {
+  getGuardianDeliveryFresh,
+  guardianForChannel,
+} from "../contacts/guardian-delivery-reader.js";
 import type {
   GuardianBinding,
   IdentityBindingStatus,
@@ -348,6 +352,26 @@ export function getGuardianBinding(
   return null;
 }
 
+/**
+ * Gateway-backed guardian-existence check: is a guardian already bound for
+ * this channel? Presence-only idempotency guard, NOT an ACL-field read.
+ *
+ * Null-list fail direction: a `null` from the gateway (unreachable / malformed)
+ * is "unknown" — returns `true` so an unreachable gateway is treated as
+ * already-bound. Callers gate session creation on a falsy result, so this
+ * blocks a new binding on a transient miss rather than spuriously creating a
+ * second one.
+ */
+export async function isGuardianBoundForChannel(
+  channel: string,
+): Promise<boolean> {
+  // Existence guards read fresh because gateway-side binding writes don't
+  // invalidate the daemon cache.
+  const list = await getGuardianDeliveryFresh({ channelTypes: [channel] });
+  if (list === null) return true;
+  return !!guardianForChannel(list, channel);
+}
+
 /**
  * Check whether the given external user is the active guardian for
  * the specified assistant and channel.

package/src/runtime/guardian-decision-types.ts

@@ -1,9 +1,7 @@
 /**
- * Shared types for the guardian decision primitive.
- *
- * All decision entrypoints (callback buttons, conversational engine, legacy
- * parser, requester self-cancel) use these types to route through the
- * unified `applyGuardianDecision` primitive.
+ * Shared types and render helpers for guardian decision prompts: the prompt
+ * model shown to guardians, the canonical action constants, and the
+ * legend/fallback builders used to present them on rich and plain-text channels.
  */
 
 // ---------------------------------------------------------------------------
@@ -108,20 +106,3 @@ export function buildPlainTextFallback(
 ): string {
   return `${promptText}\n\nReply "yes" to approve or "no" to reject.`;
 }
-
-// ---------------------------------------------------------------------------
-// Apply decision result
-// ---------------------------------------------------------------------------
-
-export interface ApplyGuardianDecisionResult {
-  applied: boolean;
-  reason?:
-    | "stale"
-    | "identity_mismatch"
-    | "invalid_action"
-    | "not_found"
-    | "expired";
-  requestId?: string;
-  /** Feedback text when the action was parsed from user text. */
-  userText?: string;
-}

package/src/runtime/guardian-vellum-migration.ts

@@ -7,11 +7,22 @@
  * assistant-side since it reacts to incoming JWT principals.
  */
 
+import type { ChannelId } from "../channels/types.js";
 import {
   findGuardianForChannel,
   updateContactPrincipalAndChannel,
 } from "../contacts/contact-store.js";
+import {
+  getGuardianDelivery,
+  guardianForChannel,
+} from "../contacts/guardian-delivery-reader.js";
+import type { TrustContext } from "../daemon/trust-context.js";
 import { getLogger } from "../util/logger.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
+import {
+  resolveTrustContext,
+  withSourceChannel,
+} from "./trust-context-resolver.js";
 
 const log = getLogger("guardian-vellum-migration");
 
@@ -31,18 +42,37 @@ const log = getLogger("guardian-vellum-migration");
  * minted by this daemon's signing key.
  *
  * Returns true if healing occurred, false otherwise.
+ *
+ * The gateway binding supplies the authoritative principal; the local
+ * assistant-mirror row is repaired whenever it diverges from the JWT
+ * principal — even when the gateway binding already matches — because the
+ * /v1/messages trust path still resolves against the local mirror in this
+ * plan. A stale mirror must be repaired or valid guardians stay `unknown`.
  */
-export function healGuardianBindingDrift(incomingPrincipalId: string): boolean {
+export async function healGuardianBindingDrift(
+  incomingPrincipalId: string,
+): Promise<boolean> {
   if (!incomingPrincipalId.startsWith("vellum-principal-")) {
     return false;
   }
 
+  const guardians = await getGuardianDelivery({ channelTypes: ["vellum"] });
+  if (!guardians) return false;
+  const guardian = guardianForChannel(guardians, "vellum");
+  if (!guardian) return false;
+
+  const currentPrincipalId = guardian.principalId;
+  if (!currentPrincipalId?.startsWith("vellum-principal-")) return false;
+
+  // Resolve the assistant-mirror row whose principal drives local trust.
   const guardianResult = findGuardianForChannel("vellum");
   if (!guardianResult) return false;
 
-  const currentPrincipalId = guardianResult.contact.principalId;
-  if (!currentPrincipalId?.startsWith("vellum-principal-")) return false;
-  if (currentPrincipalId === incomingPrincipalId) return false;
+  const localPrincipalId = guardianResult.contact.principalId;
+  // Only repair auto-generated local principals — never overwrite a real one.
+  if (!localPrincipalId?.startsWith("vellum-principal-")) return false;
+  // No-op when the local mirror already matches the JWT principal.
+  if (localPrincipalId === incomingPrincipalId) return false;
 
   const updated = updateContactPrincipalAndChannel(
     guardianResult.contact.id,
@@ -53,7 +83,7 @@ export function healGuardianBindingDrift(incomingPrincipalId: string): boolean {
   if (!updated) {
     log.warn(
       {
-        oldPrincipalId: currentPrincipalId,
+        oldPrincipalId: localPrincipalId,
         newPrincipalId: incomingPrincipalId,
       },
       "Skipped guardian binding drift heal — address collision on contact_channels",
@@ -63,11 +93,40 @@ export function healGuardianBindingDrift(incomingPrincipalId: string): boolean {
 
   log.info(
     {
-      oldPrincipalId: currentPrincipalId,
+      oldPrincipalId: localPrincipalId,
       newPrincipalId: incomingPrincipalId,
     },
-    "Healed vellum guardian binding drift — updated principalId to match JWT actor",
+    "Healed vellum guardian binding drift — updated local mirror principalId to match JWT actor",
   );
 
   return true;
 }
+
+/**
+ * Re-resolve trust from the local mirror only for the narrow vellum-principal
+ * reset-drift case; null when it isn't drift (caller keeps the gateway verdict).
+ */
+export async function reResolveTrustOnResetDrift(
+  incomingPrincipalId: string,
+  sourceChannel: ChannelId,
+): Promise<TrustContext | null> {
+  const guardians = await getGuardianDelivery({ channelTypes: ["vellum"] });
+  const gatewayPrincipal = guardians
+    ? guardianForChannel(guardians, "vellum")?.principalId
+    : undefined;
+  const isResetDrift =
+    incomingPrincipalId.startsWith("vellum-principal-") &&
+    !!gatewayPrincipal?.startsWith("vellum-principal-") &&
+    gatewayPrincipal !== incomingPrincipalId;
+  if (!isResetDrift) return null;
+  await healGuardianBindingDrift(incomingPrincipalId);
+  return withSourceChannel(
+    sourceChannel,
+    resolveTrustContext({
+      assistantId: DAEMON_INTERNAL_ASSISTANT_ID,
+      sourceChannel: "vellum",
+      conversationExternalId: "local",
+      actorExternalId: incomingPrincipalId,
+    }),
+  );
+}

package/src/runtime/http-server.ts

@@ -24,7 +24,6 @@ import {
 import { isHttpAuthDisabled } from "../config/env.js";
 import { getIsPlatform } from "../config/env-registry.js";
 import { getConfig } from "../config/loader.js";
-import { createApprovalCopyGenerator } from "../daemon/approval-generators.js";
 import { processMessage } from "../daemon/process-message.js";
 import { createLiveVoiceSession } from "../live-voice/live-voice-session.js";
 import { LiveVoiceSessionManager } from "../live-voice/live-voice-session-manager.js";
@@ -77,10 +76,6 @@ import {
   startCanonicalGuardianExpirySweep,
   stopCanonicalGuardianExpirySweep,
 } from "./routes/canonical-guardian-expiry-sweep.js";
-import {
-  startGuardianExpirySweep,
-  stopGuardianExpirySweep,
-} from "./routes/channel-guardian-routes.js";
 import { RouteError } from "./routes/errors.js";
 import { handleHealth, handleReadyz } from "./routes/identity-routes.js";
 import {
@@ -92,10 +87,7 @@ import { matchSkillRoute } from "./skill-route-registry.js";
 // Re-export for consumers
 export { isPrivateAddress } from "./middleware/auth.js";
 
-import type {
-  ApprovalCopyGenerator,
-  RuntimeHttpServerOptions,
-} from "./http-types.js";
+import type { RuntimeHttpServerOptions } from "./http-types.js";
 
 const log = getLogger("runtime-http");
 
@@ -155,7 +147,6 @@ export class RuntimeHttpServer {
   private port: number;
   private hostname: string;
 
-  private readonly approvalCopyGenerator: ApprovalCopyGenerator;
   private retrySweepTimer: ReturnType<typeof setInterval> | null = null;
   private sweepInProgress = false;
 
@@ -166,7 +157,6 @@ export class RuntimeHttpServer {
     this.port = options.port ?? DEFAULT_PORT;
     this.hostname = options.hostname ?? DEFAULT_HOSTNAME;
 
-    this.approvalCopyGenerator = createApprovalCopyGenerator();
     this.liveVoiceSessionManager = new LiveVoiceSessionManager({
       createSession: (context) => createLiveVoiceSession(context),
     });
@@ -475,9 +465,6 @@ export class RuntimeHttpServer {
       }, 30_000);
     }
 
-    startGuardianExpirySweep(this.approvalCopyGenerator);
-    log.info("Guardian approval expiry sweep started");
-
     startCanonicalGuardianExpirySweep();
     log.info("Canonical guardian request expiry sweep started");
 
@@ -486,7 +473,6 @@ export class RuntimeHttpServer {
   }
 
   async stop(): Promise<void> {
-    stopGuardianExpirySweep();
     stopCanonicalGuardianExpirySweep();
     stopInferenceProfileSessionReaper();
     if (this.retrySweepTimer) {