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

package/src/runtime/routes/inbound-stages/acl-enforcement.ts

@@ -7,12 +7,9 @@ import type { AdmissionPolicy, SourceMetadata } from "@vellumai/gateway-client";
 
 import { isInviteCodeRedemptionEnabled } from "../../../channels/config.js";
 import type { ChannelId } from "../../../channels/types.js";
-import {
-  findContactChannel,
-  findGuardianForChannel,
-} from "../../../contacts/contact-store.js";
+import { getGuardianDelivery } from "../../../contacts/guardian-delivery-reader.js";
+import { channelStatusToMemberStatus } from "../../../contacts/member-status.js";
 import type {
-  ChannelStatus,
   ContactChannel,
   ContactWithChannels,
 } from "../../../contacts/types.js";
@@ -28,6 +25,7 @@ import { getLogger } from "../../../util/logger.js";
 import { truncate } from "../../../util/truncate.js";
 import { hashVoiceCode } from "../../../util/voice-code.js";
 import { notifyGuardianOfAccessRequest } from "../../access-request-helper.js";
+import { resolveAnchoredGuardian } from "../../anchored-guardian.js";
 import { getInviteAdapterRegistry } from "../../channel-invite-transport.js";
 import {
   createOutboundSession,
@@ -41,6 +39,7 @@ import {
   redeemInviteByCode,
 } from "../../invite-redemption-service.js";
 import { getInviteRedemptionReply } from "../../invite-redemption-templates.js";
+import { resolvedMemberFromVerdict } from "../../trust-verdict-consumer.js";
 
 const log = getLogger("runtime-http");
 
@@ -48,28 +47,20 @@ const log = getLogger("runtime-http");
  * Resolve the guardian's display name for use in requester-facing messages.
  *
  * Uses the assistant's anchored vellum principal to validate the guardian
- * contact, matching the same strategy used by `notifyGuardianOfAccessRequest`.
- * This prevents stale or cross-assistant contacts from leaking a wrong name.
+ * binding, matching the same strategy used by `notifyGuardianOfAccessRequest`.
+ * This prevents stale or cross-assistant bindings from leaking a wrong name.
+ * Cosmetic copy, not an admission decision, so a null gateway list degrades
+ * gracefully to the default reference.
  */
-function resolveGuardianLabel(sourceChannel: ChannelId): string {
-  const vellumGuardian = findGuardianForChannel("vellum");
-  const anchoredPrincipalId = vellumGuardian?.contact.principalId;
-
-  if (!anchoredPrincipalId) {
-    return resolveGuardianName(undefined);
-  }
-
-  // Try source-channel guardian, but only accept it when the principal
-  // matches the assistant's anchor.
-  const sourceGuardian = findGuardianForChannel(sourceChannel);
-  if (
-    sourceGuardian &&
-    sourceGuardian.contact.principalId === anchoredPrincipalId
-  ) {
-    return resolveGuardianName(sourceGuardian.contact.displayName);
-  }
-
-  return resolveGuardianName(vellumGuardian.contact.displayName);
+async function resolveGuardianLabel(sourceChannel: ChannelId): Promise<string> {
+  // Cosmetic copy, not an admission decision: no local-store fallback, and a
+  // missing anchor principal degrades to the default reference.
+  const anchored = resolveAnchoredGuardian({
+    guardians: await getGuardianDelivery(),
+    sourceChannel,
+    requireAnchorPrincipal: true,
+  });
+  return resolveGuardianName(anchored?.displayName);
 }
 
 // ---------------------------------------------------------------------------
@@ -122,14 +113,6 @@ export interface AclResult {
   isValidatedBootstrap?: boolean;
 }
 
-/** Map ChannelStatus to the API-facing member status (excludes "unverified"). */
-export function channelStatusToMemberStatus(
-  status: ChannelStatus,
-): Exclude<ChannelStatus, "unverified"> {
-  if (status === "unverified") return "pending";
-  return status;
-}
-
 /**
  * Enforce ingress ACL rules: member lookup, non-member/inactive denial,
  * policy enforcement (allow/deny/escalate bypass), invite token intercepts,
@@ -164,7 +147,63 @@ export async function enforceIngressAcl(
   // Slack message timestamp for permalink construction.
   const messageTs = sourceMetadata?.messageId ?? undefined;
 
-  let resolvedMember: ResolvedMember | null = null;
+  // Absent verdict = gateway could not vouch for this actor → fail-closed deny.
+  // A PRESENT verdict with no member (stranger) still flows through the
+  // intercepts below; only a missing verdict short-circuits here.
+  const verdict = sourceMetadata?.trustVerdict;
+  if (verdict == null) {
+    log.info(
+      { sourceChannel, externalUserId: canonicalSenderId },
+      "Ingress ACL: absent trust verdict, denying fail-closed",
+    );
+    return {
+      resolvedMember: null,
+      earlyResponse: {
+        accepted: true,
+        denied: true,
+        reason: "not_a_member",
+      },
+    };
+  }
+
+  // Gateway attempted resolution but failed (DB error) → fail-closed deny,
+  // distinct from an absent verdict and from a real stranger. TEXT does not
+  // fall back to local ACL reads; the sender can retry.
+  if (verdict.resolutionFailed === true) {
+    log.warn(
+      { sourceChannel, externalUserId: canonicalSenderId },
+      "Ingress ACL: gateway trust resolution failed, denying fail-closed",
+    );
+    return {
+      resolvedMember: null,
+      earlyResponse: {
+        accepted: true,
+        denied: true,
+        reason: "not_a_member",
+      },
+    };
+  }
+
+  // Member resolved from the gateway verdict (ACL + identity only); null for a
+  // stranger verdict, which falls through to the non-member intercepts.
+  const resolvedMember: ResolvedMember | null = resolvedMemberFromVerdict(verdict);
+
+  // A verdict carrying member identity but no resolvable member
+  // (malformed/unknown ACL) fails closed, not treated as a stranger.
+  if (!resolvedMember && (verdict.contactId || verdict.channelId)) {
+    log.info(
+      { sourceChannel, externalUserId: canonicalSenderId },
+      "Ingress ACL: member verdict with unresolvable ACL, denying fail-closed",
+    );
+    return {
+      resolvedMember: null,
+      earlyResponse: {
+        accepted: true,
+        denied: true,
+        reason: "not_a_member",
+      },
+    };
+  }
 
   // /start gv_<token> bootstrap commands must also bypass ACL — the user
   // hasn't been verified yet and needs to complete the bootstrap handshake.
@@ -181,23 +220,6 @@ export async function enforceIngressAcl(
   });
 
   if (canonicalSenderId || hasSenderIdentityClaim) {
-    // Only perform member lookup when we have a usable canonical ID.
-    // Whitespace-only senders (hasSenderIdentityClaim=true but
-    // canonicalSenderId=null) skip the lookup and fall into the deny path.
-    if (canonicalSenderId) {
-      const contactResult = findContactChannel({
-        channelType: sourceChannel,
-        address: canonicalSenderId,
-        externalChatId: conversationExternalId,
-      });
-      resolvedMember = contactResult
-        ? {
-            contact: contactResult.contact,
-            channel: contactResult.channel,
-          }
-        : null;
-    }
-
     if (!resolvedMember) {
       let denyNonMember = true;
 
@@ -318,7 +340,7 @@ export async function enforceIngressAcl(
           if (slackVerifyResult.initiated) {
             // Still notify the guardian about the access attempt
             try {
-              notifyGuardianOfAccessRequest({
+              await notifyGuardianOfAccessRequest({
                 canonicalAssistantId,
                 sourceChannel,
                 conversationExternalId,
@@ -358,7 +380,7 @@ export async function enforceIngressAcl(
               try {
                 await deliverChannelReply(dmCallbackUrl, {
                   chatId: senderUserId,
-                  text: `I don't recognize you yet! I've let ${resolveGuardianLabel(sourceChannel)} know you're trying to reach me. They'll need to share a 6-digit verification code with you — ask them directly if you know them. Once you have the code, reply here with it.`,
+                  text: `I don't recognize you yet! I've let ${await resolveGuardianLabel(sourceChannel)} know you're trying to reach me. They'll need to share a 6-digit verification code with you — ask them directly if you know them. Once you have the code, reply here with it.`,
                   assistantId,
                 });
               } catch (err) {
@@ -393,7 +415,7 @@ export async function enforceIngressAcl(
 
           if (emailVerifyResult.initiated) {
             try {
-              notifyGuardianOfAccessRequest({
+              await notifyGuardianOfAccessRequest({
                 canonicalAssistantId,
                 sourceChannel,
                 conversationExternalId,
@@ -432,7 +454,7 @@ export async function enforceIngressAcl(
         // deduplication, canonical request creation, and notification emission.
         let guardianNotified = false;
         try {
-          const accessResult = notifyGuardianOfAccessRequest({
+          const accessResult = await notifyGuardianOfAccessRequest({
             canonicalAssistantId,
             sourceChannel,
             conversationExternalId,
@@ -456,7 +478,7 @@ export async function enforceIngressAcl(
         }
 
         const replyText = guardianNotified
-          ? `Hmm looks like you don't have access to talk to me. I'll let ${resolveGuardianLabel(sourceChannel)} know you tried talking to me and get back to you.`
+          ? `Hmm looks like you don't have access to talk to me. I'll let ${await resolveGuardianLabel(sourceChannel)} know you tried talking to me and get back to you.`
           : "Sorry, you haven't been approved to message this assistant.";
         let replyDelivered = false;
         if (replyCallbackUrl) {
@@ -638,7 +660,7 @@ export async function enforceIngressAcl(
 
             if (slackVerifyResult.initiated) {
               try {
-                notifyGuardianOfAccessRequest({
+                await notifyGuardianOfAccessRequest({
                   canonicalAssistantId,
                   sourceChannel,
                   conversationExternalId,
@@ -677,7 +699,7 @@ export async function enforceIngressAcl(
                 try {
                   await deliverChannelReply(dmCallbackUrl, {
                     chatId: senderUserId,
-                    text: `I don't recognize you yet! I've let ${resolveGuardianLabel(sourceChannel)} know you're trying to reach me. They'll need to share a 6-digit verification code with you — ask them directly if you know them. Once you have the code, reply here with it.`,
+                    text: `I don't recognize you yet! I've let ${await resolveGuardianLabel(sourceChannel)} know you're trying to reach me. They'll need to share a 6-digit verification code with you — ask them directly if you know them. Once you have the code, reply here with it.`,
                     assistantId,
                   });
                 } catch (err) {
@@ -706,7 +728,7 @@ export async function enforceIngressAcl(
           let guardianNotified = false;
           if (resolvedMember.channel.status !== "blocked") {
             try {
-              const accessResult = notifyGuardianOfAccessRequest({
+              const accessResult = await notifyGuardianOfAccessRequest({
                 canonicalAssistantId,
                 sourceChannel,
                 conversationExternalId,
@@ -734,7 +756,7 @@ export async function enforceIngressAcl(
           }
 
           const inactiveReplyText = guardianNotified
-            ? `Hmm looks like you don't have access to talk to me. I'll let ${resolveGuardianLabel(sourceChannel)} know you tried talking to me and get back to you.`
+            ? `Hmm looks like you don't have access to talk to me. I'll let ${await resolveGuardianLabel(sourceChannel)} know you tried talking to me and get back to you.`
             : "Sorry, you haven't been approved to message this assistant.";
           let inactiveReplyDelivered = false;
           if (replyCallbackUrl) {
@@ -875,7 +897,7 @@ async function handleInviteTokenIntercept(params: {
     };
   }
 
-  const outcome = redeemInvite({
+  const outcome = await redeemInvite({
     rawToken,
     sourceChannel,
     externalUserId: senderExternalUserId,
@@ -1077,9 +1099,9 @@ async function handleInviteCodeIntercept(params: {
     };
   }
 
-  let outcome: ReturnType<typeof redeemInviteByCode>;
+  let outcome: Awaited<ReturnType<typeof redeemInviteByCode>>;
   try {
-    outcome = redeemInviteByCode({
+    outcome = await redeemInviteByCode({
       code,
       sourceChannel,
       externalUserId: senderExternalUserId,

package/src/runtime/routes/inbound-stages/admission-policy.ts

@@ -30,10 +30,7 @@ import {
 
 import type { ChannelId } from "../../../channels/types.js";
 import type { ChannelStatus } from "../../../contacts/types.js";
-import {
-  TRUST_CLASS_RANK,
-  type TrustClass,
-} from "../../actor-trust-resolver.js";
+import type { TrustClass } from "../../actor-trust-resolver.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -75,6 +72,23 @@ export type AdmissionPolicyResult =
 // Public API
 // ---------------------------------------------------------------------------
 
+/**
+ * Trust-class ordinal compared against {@link ADMISSION_FLOOR} to make the
+ * admission decision (`rank >= floor`). Higher rank = more trusted.
+ * Blocked/revoked never reach this comparison — they short-circuit to deny on
+ * member status above — so they carry no rank here.
+ *
+ * The two halves of the floor check: this table is keyed by `TrustClass`,
+ * `ADMISSION_FLOOR` (from `@vellumai/gateway-client`) by `AdmissionPolicy`.
+ * They are only ever read together, here, so they live next to their use.
+ */
+const TRUST_CLASS_RANK: Record<TrustClass, number> = {
+  guardian: 4,
+  trusted_contact: 3,
+  unverified_contact: 2,
+  unknown: 1,
+};
+
 /**
  * Policies under which completing verification could lift the sender past
  * the floor. Used to decide whether to fire the upgrade UX on deny.
@@ -116,7 +130,8 @@ export function enforceAdmissionPolicy(
   if (input.memberStatus === "blocked" || input.memberStatus === "revoked") {
     return {
       admitted: false,
-      reason: input.memberStatus === "blocked" ? "member_blocked" : "member_revoked",
+      reason:
+        input.memberStatus === "blocked" ? "member_blocked" : "member_revoked",
       shouldChallenge: false,
       effectivePolicy: input.policy,
     };

package/src/runtime/routes/inbound-stages/background-dispatch.ts

@@ -9,6 +9,10 @@
  */
 import type { ChannelId, InterfaceId } from "../../../channels/types.js";
 import { findGuardianForChannel } from "../../../contacts/contact-store.js";
+import {
+  getGuardianDelivery,
+  guardianForChannel,
+} from "../../../contacts/guardian-delivery-reader.js";
 import type { ServerMessage } from "../../../daemon/message-protocol.js";
 import type { TrustContext } from "../../../daemon/trust-context.js";
 import {
@@ -960,10 +964,18 @@ function startTrustedContactApprovalNotifier(params: {
 
         if (info && !globalNotifiedApprovalRequestIds.has(info.requestId)) {
           globalNotifiedApprovalRequestIds.set(info.requestId, conversationId);
-          const guardian = findGuardianForChannel(sourceChannel);
-          const guardianName = resolveGuardianName(
-            guardian?.contact.displayName,
-          );
+          // Gateway-resolved guardian display name with the transitional
+          // local fallback on null/no-match (display-only). Removed in Combo 11.
+          const guardians = await getGuardianDelivery({
+            channelTypes: [sourceChannel],
+          });
+          const gatewayDisplayName = guardians
+            ? guardianForChannel(guardians, sourceChannel)?.displayName
+            : undefined;
+          const displayName =
+            gatewayDisplayName ??
+            findGuardianForChannel(sourceChannel)?.contact.displayName;
+          const guardianName = resolveGuardianName(displayName);
           const waitingText = `Waiting for ${guardianName}'s approval...`;
           try {
             await deliverChannelReply(replyCallbackUrl, {

package/src/runtime/routes/inbound-stages/guardian-activation-intercept.test.ts

@@ -4,7 +4,9 @@ import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 // Mocks — must be set up before importing the module under test
 // ---------------------------------------------------------------------------
 
-let mockGuardian: { contact: unknown; channel: unknown } | null = null;
+// Gateway guardian-delivery list: empty = unbound, one entry = bound,
+// null = gateway unreachable.
+let mockGuardianList: Array<Record<string, unknown>> | null = [];
 let mockActiveSession: Record<string, unknown> | null = null;
 let mockSessionResult = {
   sessionId: "sess-1",
@@ -20,8 +22,14 @@ let deliverChannelReplyCalls: unknown[][] = [];
 let emitNotificationSignalCalls: unknown[] = [];
 let messageIdCounter = 0;
 
-mock.module("../../../contacts/contact-store.js", () => ({
-  findGuardianForChannel: () => mockGuardian,
+mock.module("../../../contacts/guardian-delivery-reader.js", () => ({
+  // Existence guard reads fresh (uncached) — only this variant is stubbed.
+  getGuardianDeliveryFresh: () => Promise.resolve(mockGuardianList),
+  guardianForChannel: (
+    list: Array<{ channelType: string; status: string }>,
+    channelType: string,
+  ) =>
+    list.find((g) => g.channelType === channelType && g.status === "active"),
 }));
 
 mock.module("../../channel-verification-service.js", () => ({
@@ -96,7 +104,7 @@ function makeParams(
 
 describe("handleGuardianActivationIntercept", () => {
   beforeEach(() => {
-    mockGuardian = null;
+    mockGuardianList = [];
     mockActiveSession = null;
     mockSessionResult = {
       sessionId: "sess-1",
@@ -155,10 +163,15 @@ describe("handleGuardianActivationIntercept", () => {
   });
 
   test("bare /start with existing guardian returns null", async () => {
-    mockGuardian = {
-      contact: { id: "contact-1", role: "guardian" },
-      channel: { id: "ch-1", type: "telegram" },
-    };
+    mockGuardianList = [{ channelType: "telegram", status: "active" }];
+
+    const result = await handleGuardianActivationIntercept(makeParams());
+    expect(result).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("null guardian list (gateway unreachable) does NOT auto-start", async () => {
+    mockGuardianList = null;
 
     const result = await handleGuardianActivationIntercept(makeParams());
     expect(result).toBeNull();

package/src/runtime/routes/inbound-stages/guardian-activation-intercept.ts

@@ -9,7 +9,10 @@
  * the guardian binding, and sends a success reply.
  */
 import type { ChannelId } from "../../../channels/types.js";
-import { findGuardianForChannel } from "../../../contacts/contact-store.js";
+import {
+  getGuardianDeliveryFresh,
+  guardianForChannel,
+} from "../../../contacts/guardian-delivery-reader.js";
 import { emitNotificationSignal } from "../../../notifications/emit-signal.js";
 import { getLogger } from "../../../util/logger.js";
 import {
@@ -88,8 +91,16 @@ export async function handleGuardianActivationIntercept(
   // Only proceed for Telegram (can be extended later)
   if (sourceChannel !== "telegram") return null;
 
-  // If a guardian already exists for this channel, continue to normal flow
-  if (findGuardianForChannel(sourceChannel)) return null;
+  // If a guardian already exists for this channel, continue to normal flow.
+  // Null-list (gateway unreachable) is treated as guardian-present so a
+  // transient miss does NOT spuriously auto-start verification.
+  // Read fresh: gateway-side binding writes don't invalidate the daemon cache.
+  const guardianList = await getGuardianDeliveryFresh({
+    channelTypes: [sourceChannel],
+  });
+  if (guardianList === null || guardianForChannel(guardianList, sourceChannel)) {
+    return null;
+  }
 
   // Can't bind a session without sender identity
   if (!rawSenderId) return null;

package/src/runtime/routes/llm-context-normalization.ts

@@ -40,10 +40,27 @@ export interface LlmContextSection {
   language?: string;
 }
 
+/**
+ * Structured error extracted from a rejected call's response payload.
+ * Mirrors the on-disk `responsePayload.error` shape produced by
+ * `buildProviderErrorResponsePayload`. Present only when the call failed
+ * before returning a response — consumers branch on its presence to
+ * render the call as failed.
+ */
+export interface LlmContextError {
+  name?: string;
+  message?: string;
+  code?: string;
+  provider?: string;
+  statusCode?: number;
+  retryAfterMs?: number;
+}
+
 export interface LlmContextNormalizationResult {
   summary?: LlmContextSummary;
   requestSections?: LlmContextSection[];
   responseSections?: LlmContextSection[];
+  error?: LlmContextError;
 }
 
 interface NormalizedPayloadCandidate {
@@ -55,6 +72,60 @@ interface NormalizedPayloadCandidate {
 
 export function normalizeLlmContextPayloads(
   input: LlmContextNormalizationInput,
+): LlmContextNormalizationResult {
+  const base = normalizeSuccessPayloads(input);
+  const error = normalizeProviderErrorPayload(input.responsePayload);
+  if (!error) {
+    return base;
+  }
+  // A rejected call has no response sections to render — only the request
+  // side normalized. Attach the structured error so the inspector can show
+  // a failure banner and treat the cost as $0.00 instead of silently
+  // falling back to "section rendering unavailable".
+  return { ...base, error };
+}
+
+/**
+ * Detect a provider/transport error stored in the response payload.
+ *
+ * Error rows are written as `{ error: { name, message, code?, provider?,
+ * statusCode?, retryAfterMs? } }` by `buildProviderErrorResponsePayload`.
+ * Successful provider responses never carry a top-level `error` object, so
+ * the presence of one (with at least one identifying field) is a reliable
+ * signal that the call failed.
+ */
+function normalizeProviderErrorPayload(
+  responsePayload: unknown,
+): LlmContextError | null {
+  const error = asRecord(asRecord(responsePayload)?.error);
+  if (!error) {
+    return null;
+  }
+
+  const name = asString(error.name);
+  const message = asString(error.message);
+  const code = asString(error.code);
+  // Require at least one identifying field so an unrelated `error` key on a
+  // success payload isn't misread as a provider failure.
+  if (name === undefined && message === undefined && code === undefined) {
+    return null;
+  }
+
+  const normalized: LlmContextError = {};
+  if (name !== undefined) normalized.name = name;
+  if (message !== undefined) normalized.message = message;
+  if (code !== undefined) normalized.code = code;
+  const provider = asString(error.provider);
+  if (provider !== undefined) normalized.provider = provider;
+  const statusCode = asNumber(error.statusCode);
+  if (statusCode !== undefined) normalized.statusCode = statusCode;
+  const retryAfterMs = asNumber(error.retryAfterMs);
+  if (retryAfterMs !== undefined) normalized.retryAfterMs = retryAfterMs;
+  return normalized;
+}
+
+function normalizeSuccessPayloads(
+  input: LlmContextNormalizationInput,
 ): LlmContextNormalizationResult {
   const requestCandidates = [
     normalizeOpenAiRequestPayload(input.requestPayload),

package/src/runtime/routes/log-export-routes.ts

@@ -22,7 +22,7 @@ import { join } from "node:path";
 import { and, desc, eq, gte, lte } from "drizzle-orm";
 import { z } from "zod";
 
-import { getDb } from "../../memory/db-connection.js";
+import { getDb, getLogsDb } from "../../memory/db-connection.js";
 import {
   llmRequestLogs,
   llmUsageEvents,
@@ -168,7 +168,7 @@ async function handleExport({
         : [];
 
       const llmLogRows = capRows(
-        db
+        (getLogsDb() ?? db)
           .select()
           .from(llmRequestLogs)
           .where(

package/src/runtime/routes/mcp-auth-routes.ts

@@ -24,7 +24,7 @@ import { getMcpAuthState } from "../../mcp/mcp-auth-state.js";
 import { deleteMcpOAuthCredentials } from "../../mcp/mcp-oauth-provider.js";
 import { getMcpToolsByServer } from "../../tools/registry.js";
 import { getLogger } from "../../util/logger.js";
-import { ACTOR_PRINCIPALS, GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
 import type { RouteDefinition } from "./types.js";
 
@@ -281,6 +281,7 @@ async function handleMcpUpdate({
     maxTools,
     allowedTools,
     blockedTools,
+    headers,
   } = body as {
     name: string;
     enabled?: boolean;
@@ -288,6 +289,7 @@ async function handleMcpUpdate({
     maxTools?: number;
     allowedTools?: string[] | null;
     blockedTools?: string[] | null;
+    headers?: Record<string, string> | null;
   };
 
   const raw = loadRawConfig();
@@ -326,6 +328,19 @@ async function handleMcpUpdate({
       server.blockedTools = blockedTools;
     }
   }
+  if (headers !== undefined) {
+    const transport = server.transport as Record<string, unknown> | undefined;
+    if (
+      transport &&
+      (transport.type === "sse" || transport.type === "streamable-http")
+    ) {
+      if (headers === null || Object.keys(headers).length === 0) {
+        delete transport.headers;
+      } else {
+        transport.headers = headers;
+      }
+    }
+  }
 
   saveRawConfig(raw);
   triggerReload("internal_mcp_update");
@@ -342,15 +357,17 @@ async function handleMcpAdd({
 }: {
   body?: Record<string, unknown>;
 }): Promise<{ added: true }> {
-  const { name, transportType, url, command, args, risk, disabled } = body as {
-    name: string;
-    transportType: string;
-    url?: string;
-    command?: string;
-    args?: string[];
-    risk?: string;
-    disabled?: boolean;
-  };
+  const { name, transportType, url, command, args, risk, disabled, headers } =
+    body as {
+      name: string;
+      transportType: string;
+      url?: string;
+      command?: string;
+      args?: string[];
+      risk?: string;
+      disabled?: boolean;
+      headers?: Record<string, string>;
+    };
 
   const riskLevel = risk ?? "high";
   if (!["low", "medium", "high"].includes(riskLevel)) {
@@ -374,7 +391,11 @@ async function handleMcpAdd({
           `--url is required for ${transportType} transport`,
         );
       }
-      transport = { type: transportType, url };
+      transport = {
+        type: transportType,
+        url,
+        ...(headers && Object.keys(headers).length > 0 ? { headers } : {}),
+      };
       break;
     default:
       throw new BadRequestError(
@@ -455,8 +476,8 @@ export const ROUTES: RouteDefinition[] = [
     endpoint: "internal/mcp/auth/start",
     method: "POST",
     policy: {
-      requiredScopes: ["internal.write"],
-      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
     },
     summary: "Start MCP OAuth flow",
     description:
@@ -470,8 +491,8 @@ export const ROUTES: RouteDefinition[] = [
     endpoint: "internal/mcp/auth/status/:serverId",
     method: "GET",
     policy: {
-      requiredScopes: ["internal.write"],
-      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
     },
     summary: "Poll MCP OAuth flow status",
     description:
@@ -579,6 +600,7 @@ export const ROUTES: RouteDefinition[] = [
       maxTools: z.number().optional(),
       allowedTools: z.array(z.string()).nullable().optional(),
       blockedTools: z.array(z.string()).nullable().optional(),
+      headers: z.record(z.string(), z.string()).nullable().optional(),
     }),
     handler: handleMcpUpdate,
   },
@@ -602,6 +624,7 @@ export const ROUTES: RouteDefinition[] = [
       args: z.array(z.string()).optional(),
       risk: z.string().optional(),
       disabled: z.boolean().optional(),
+      headers: z.record(z.string(), z.string()).optional(),
     }),
     handler: handleMcpAdd,
   },