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

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

@@ -7,12 +7,8 @@ import type { AdmissionPolicy, SourceMetadata } from "@vellumai/gateway-client";
 
 import { isInviteCodeRedemptionEnabled } from "../../../channels/config.js";
 import type { ChannelId } from "../../../channels/types.js";
-import { findGuardianForChannel } from "../../../contacts/contact-store.js";
+import { getGuardianDelivery } from "../../../contacts/guardian-delivery-reader.js";
 import { channelStatusToMemberStatus } from "../../../contacts/member-status.js";
-import type {
-  ContactChannel,
-  ContactWithChannels,
-} from "../../../contacts/types.js";
 import { deleteInbound, recordInbound } from "../../../memory/delivery-crud.js";
 import { markProcessed } from "../../../memory/delivery-status.js";
 import {
@@ -25,6 +21,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,
@@ -38,7 +35,8 @@ import {
   redeemInviteByCode,
 } from "../../invite-redemption-service.js";
 import { getInviteRedemptionReply } from "../../invite-redemption-templates.js";
-import { resolvedMemberFromVerdict } from "../../trust-verdict-consumer.js";
+import type { VerdictMember } from "../../trust-verdict-consumer.js";
+import { verdictMemberFromVerdict } from "../../trust-verdict-consumer.js";
 
 const log = getLogger("runtime-http");
 
@@ -46,28 +44,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);
 }
 
 // ---------------------------------------------------------------------------
@@ -102,14 +92,8 @@ export interface AclEnforcementParams {
   effectiveAdmissionPolicy?: AdmissionPolicy;
 }
 
-/** Resolved contact + channel pair from ACL enforcement. */
-export type ResolvedMember = {
-  contact: ContactWithChannels;
-  channel: ContactChannel;
-};
-
 export interface AclResult {
-  resolvedMember: ResolvedMember | null;
+  resolvedMember: VerdictMember | null;
   /** When set, the caller must return this response immediately. */
   earlyResponse?: Record<string, unknown>;
   /**
@@ -173,9 +157,27 @@ export async function enforceIngressAcl(
     };
   }
 
+  // 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);
+  const resolvedMember: VerdictMember | null = verdictMemberFromVerdict(verdict);
 
   // A verdict carrying member identity but no resolvable member
   // (malformed/unknown ACL) fails closed, not treated as a stranger.
@@ -329,7 +331,7 @@ export async function enforceIngressAcl(
           if (slackVerifyResult.initiated) {
             // Still notify the guardian about the access attempt
             try {
-              notifyGuardianOfAccessRequest({
+              await notifyGuardianOfAccessRequest({
                 canonicalAssistantId,
                 sourceChannel,
                 conversationExternalId,
@@ -369,7 +371,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) {
@@ -404,7 +406,7 @@ export async function enforceIngressAcl(
 
           if (emailVerifyResult.initiated) {
             try {
-              notifyGuardianOfAccessRequest({
+              await notifyGuardianOfAccessRequest({
                 canonicalAssistantId,
                 sourceChannel,
                 conversationExternalId,
@@ -443,7 +445,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,
@@ -467,7 +469,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) {
@@ -507,8 +509,8 @@ export async function enforceIngressAcl(
     }
 
     if (resolvedMember) {
-      if (resolvedMember.channel.status !== "active") {
-        const isBlockedMember = resolvedMember.channel.status === "blocked";
+      if (resolvedMember.status !== "active") {
+        const isBlockedMember = resolvedMember.status === "blocked";
         // Bootstrap commands must pass through for re-verifiable states
         // (pending/revoked), but never for blocked members.
         let denyInactiveMember = true;
@@ -529,7 +531,7 @@ export async function enforceIngressAcl(
             log.info(
               {
                 sourceChannel,
-                channelId: resolvedMember.channel.id,
+                channelId: resolvedMember.channelId,
                 hasValidBootstrapSession: false,
               },
               "Ingress ACL: inactive member bootstrap bypass denied",
@@ -614,11 +616,11 @@ export async function enforceIngressAcl(
         if (!isBlockedMember && denyInactiveMember) {
           if (
             (effectiveAdmissionPolicy === "strangers" &&
-              resolvedMember.channel.status !== "revoked") ||
+              resolvedMember.status !== "revoked") ||
             ((effectiveAdmissionPolicy === "any_contact" ||
               effectiveAdmissionPolicy === "guardian_only") &&
-              (resolvedMember.channel.status === "pending" ||
-                resolvedMember.channel.status === "unverified"))
+              (resolvedMember.status === "pending" ||
+                resolvedMember.status === "unverified"))
           ) {
             denyInactiveMember = false;
           }
@@ -628,8 +630,8 @@ export async function enforceIngressAcl(
           log.info(
             {
               sourceChannel,
-              channelId: resolvedMember.channel.id,
-              status: resolvedMember.channel.status,
+              channelId: resolvedMember.channelId,
+              status: resolvedMember.status,
             },
             "Ingress ACL: member not active, denying",
           );
@@ -639,7 +641,7 @@ export async function enforceIngressAcl(
           // the guardian made an explicit decision to block them.
           if (
             sourceChannel === "slack" &&
-            resolvedMember.channel.status !== "blocked" &&
+            resolvedMember.status !== "blocked" &&
             (canonicalSenderId ?? rawSenderId)
           ) {
             const slackVerifyResult = initiateSlackVerificationChallenge({
@@ -649,7 +651,7 @@ export async function enforceIngressAcl(
 
             if (slackVerifyResult.initiated) {
               try {
-                notifyGuardianOfAccessRequest({
+                await notifyGuardianOfAccessRequest({
                   canonicalAssistantId,
                   sourceChannel,
                   conversationExternalId,
@@ -657,7 +659,7 @@ export async function enforceIngressAcl(
                   actorDisplayName,
                   actorUsername,
                   previousMemberStatus: channelStatusToMemberStatus(
-                    resolvedMember.channel.status,
+                    resolvedMember.status,
                   ),
                   messagePreview: truncate(
                     trimmedContent,
@@ -688,7 +690,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) {
@@ -715,9 +717,9 @@ export async function enforceIngressAcl(
           // re-approve. Blocked members are intentionally excluded — the
           // guardian already made an explicit decision to block them.
           let guardianNotified = false;
-          if (resolvedMember.channel.status !== "blocked") {
+          if (resolvedMember.status !== "blocked") {
             try {
-              const accessResult = notifyGuardianOfAccessRequest({
+              const accessResult = await notifyGuardianOfAccessRequest({
                 canonicalAssistantId,
                 sourceChannel,
                 conversationExternalId,
@@ -725,7 +727,7 @@ export async function enforceIngressAcl(
                 actorDisplayName,
                 actorUsername,
                 previousMemberStatus: channelStatusToMemberStatus(
-                  resolvedMember.channel.status,
+                  resolvedMember.status,
                 ),
                 messagePreview: truncate(
                   trimmedContent,
@@ -745,7 +747,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) {
@@ -779,16 +781,16 @@ export async function enforceIngressAcl(
             earlyResponse: {
               accepted: true,
               denied: true,
-              reason: `member_${channelStatusToMemberStatus(resolvedMember.channel.status)}`,
+              reason: `member_${channelStatusToMemberStatus(resolvedMember.status)}`,
               ...(!inactiveReplyDelivered && { replyText: inactiveReplyText }),
             },
           };
         }
       }
 
-      if (resolvedMember.channel.policy === "deny") {
+      if (resolvedMember.policy === "deny") {
         log.info(
-          { sourceChannel, channelId: resolvedMember.channel.id },
+          { sourceChannel, channelId: resolvedMember.channelId },
           "Ingress ACL: member policy deny",
         );
         const denyReplyText =

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

@@ -8,7 +8,10 @@
  * focused on orchestration.
  */
 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 +963,15 @@ 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 (display-only).
+          const guardians = await getGuardianDelivery({
+            channelTypes: [sourceChannel],
+          });
+          const displayName = guardians
+            ? (guardianForChannel(guardians, sourceChannel)?.displayName ??
+              undefined)
+            : undefined;
+          const guardianName = resolveGuardianName(displayName);
           const waitingText = `Waiting for ${guardianName}'s approval...`;
           try {
             await deliverChannelReply(replyCallbackUrl, {

package/src/runtime/routes/inbound-stages/escalation-intercept.ts

@@ -13,8 +13,8 @@ import { storePayload } from "../../../memory/delivery-crud.js";
 import { emitNotificationSignal } from "../../../notifications/emit-signal.js";
 import { getLogger } from "../../../util/logger.js";
 import { getGuardianBinding } from "../../channel-verification-service.js";
+import type { VerdictMember } from "../../trust-verdict-consumer.js";
 import { GUARDIAN_APPROVAL_TTL_MS } from "../channel-route-shared.js";
-import type { ResolvedMember } from "./acl-enforcement.js";
 
 const log = getLogger("runtime-http");
 
@@ -23,7 +23,7 @@ const log = getLogger("runtime-http");
 // ---------------------------------------------------------------------------
 
 export interface EscalationInterceptParams {
-  resolvedMember: ResolvedMember | null;
+  resolvedMember: VerdictMember | null;
   canonicalAssistantId: string;
   sourceChannel: ChannelId;
   sourceInterface: InterfaceId;
@@ -49,9 +49,9 @@ export interface EscalationInterceptParams {
  * Returns a Response if the escalation was handled (the pipeline should
  * short-circuit), or null to continue the pipeline.
  */
-export function handleEscalationIntercept(
+export async function handleEscalationIntercept(
   params: EscalationInterceptParams,
-): Record<string, unknown> | null {
+): Promise<Record<string, unknown> | null> {
   const {
     resolvedMember,
     canonicalAssistantId,
@@ -72,15 +72,15 @@ export function handleEscalationIntercept(
     rawSenderId,
   } = params;
 
-  if (resolvedMember?.channel.policy !== "escalate") {
+  if (resolvedMember?.policy !== "escalate") {
     return null;
   }
 
-  const binding = getGuardianBinding(canonicalAssistantId, sourceChannel);
+  const binding = await getGuardianBinding(canonicalAssistantId, sourceChannel);
   if (!binding) {
     // Fail-closed: can't escalate without a guardian to route to
     log.info(
-      { sourceChannel, channelId: resolvedMember.channel.id },
+      { sourceChannel, channelId: resolvedMember.channelId },
       "Ingress ACL: escalate policy but no guardian binding, denying",
     );
     return {

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/inbound-stages/reaction-intercept.ts

@@ -18,6 +18,7 @@
 import type { SourceMetadata } from "@vellumai/gateway-client";
 
 import type { ChannelId, InterfaceId } from "../../../channels/types.js";
+import { getGuardianDeliveryFresh } from "../../../contacts/guardian-delivery-reader.js";
 import { getDiskPressureStatus } from "../../../daemon/disk-pressure-guard.js";
 import { classifyDiskPressureTurnPolicy } from "../../../daemon/disk-pressure-policy.js";
 import { addMessage } from "../../../memory/conversation-crud.js";
@@ -35,6 +36,7 @@ import {
 import { getLogger } from "../../../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../../assistant-scope.js";
 import type { ApprovalConversationGenerator } from "../../http-types.js";
+import { setMemberVerdict } from "../../member-verdict-cache.js";
 import { resolveTrustContext } from "../../trust-context-resolver.js";
 import { handleGuardianReplyIntercept } from "./guardian-reply-intercept.js";
 
@@ -126,6 +128,23 @@ export async function handleSlackReactionIntercept(
     approvalConversationGenerator,
   } = params;
 
+  // Warm the channel-specific guardian-delivery cache before the SYNC trust
+  // resolve below. The sync resolver reads the IO-free cache snapshot; on a
+  // cold process only `vellum` is warmed at startup, so a Slack guardian
+  // reaction would otherwise misclassify as `unknown` and drop. Read fresh:
+  // gateway-side binding writes don't invalidate the daemon cache, so a stale
+  // empty snapshot would otherwise survive the TTL. This await runs in the
+  // already-async intercept, off the sync resolver's hot path.
+  await getGuardianDeliveryFresh({ channelTypes: [sourceChannel] });
+
+  // Reactions carry the gateway-stamped verdict but skip getInboundTrustVerdict,
+  // which warms the member-verdict cache the sync resolver reads. Seed it from
+  // the stamped verdict so an active non-guardian contact's reaction resolves
+  // instead of failing closed to `unknown` on a cold cache.
+  if (sourceMetadata?.trustVerdict) {
+    setMemberVerdict(sourceChannel, rawSenderId, sourceMetadata.trustVerdict);
+  }
+
   // Classify the reactor. No timezone enrichment — reactions never drive an
   // agent turn, so only the trust class / guardian principal matter.
   const trustCtx = resolveTrustContext({

package/src/runtime/routes/index.ts

@@ -102,6 +102,7 @@ import { ROUTES as OAUTH_COMMANDS_ROUTES } from "./oauth-commands-routes.js";
 import { ROUTES as OAUTH_CONNECT_ROUTES } from "./oauth-connect-routes.js";
 import { ROUTES as OAUTH_LIFECYCLE_ROUTES } from "./oauth-lifecycle-routes.js";
 import { ROUTES as OAUTH_PROVIDERS_ROUTES } from "./oauth-providers.js";
+import { ROUTES as ONBOARDING_CHECKIN_ROUTES } from "./onboarding-checkin-routes.js";
 import { ROUTES as PLATFORM_ROUTES } from "./platform-routes.js";
 import { ROUTES as PLAYGROUND_ROUTES } from "./playground/index.js";
 import { ROUTES as PLUGINS_ROUTES } from "./plugins-routes.js";
@@ -234,6 +235,7 @@ export const ROUTES: RouteDefinition[] = [
   ...OAUTH_LIFECYCLE_ROUTES,
   ...OAUTH_COMMANDS_ROUTES,
   ...OAUTH_PROVIDERS_ROUTES,
+  ...ONBOARDING_CHECKIN_ROUTES,
   ...PLATFORM_ROUTES,
   ...PLAYGROUND_ROUTES,
   ...PLUGINS_ROUTES,

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

@@ -40,10 +40,31 @@ 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;
+  apiErrorCode?: string;
+  apiErrorType?: string;
+  apiErrorParam?: string;
+  requestId?: string;
+}
+
 export interface LlmContextNormalizationResult {
   summary?: LlmContextSummary;
   requestSections?: LlmContextSection[];
   responseSections?: LlmContextSection[];
+  error?: LlmContextError;
 }
 
 interface NormalizedPayloadCandidate {
@@ -55,6 +76,68 @@ 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;
+  const apiErrorCode = asString(error.apiErrorCode);
+  if (apiErrorCode !== undefined) normalized.apiErrorCode = apiErrorCode;
+  const apiErrorType = asString(error.apiErrorType);
+  if (apiErrorType !== undefined) normalized.apiErrorType = apiErrorType;
+  const apiErrorParam = asString(error.apiErrorParam);
+  if (apiErrorParam !== undefined) normalized.apiErrorParam = apiErrorParam;
+  const requestId = asString(error.requestId);
+  if (requestId !== undefined) normalized.requestId = requestId;
+  return normalized;
+}
+
+function normalizeSuccessPayloads(
+  input: LlmContextNormalizationInput,
 ): LlmContextNormalizationResult {
   const requestCandidates = [
     normalizeOpenAiRequestPayload(input.requestPayload),