@vellumai/assistant 0.11.7 → 0.11.8-staging.1

package/src/acp/session-manager.ts

@@ -11,10 +11,15 @@ import { eq, inArray } from "drizzle-orm";
 import type { AcpSessionUpdateEvent } from "../api/events/acp-session-update.js";
 import type { AssistantEvent } from "../api/index.js";
 import { findConversation } from "../daemon/conversation-registry.js";
+import { SYNC_TAGS } from "../daemon/message-types/sync.js";
 import { getDb } from "../persistence/db-connection.js";
 import { acpSessionHistory } from "../persistence/schema/index.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { getLogger } from "../util/logger.js";
+import {
+  acpAuthMarkerStillCurrent,
+  noteClaudeTokenRefused,
+} from "./acp-auth-marker-store.js";
 import { markAcpConnectCardRaised } from "./acp-connect-card-state.js";
 import { AcpAgentProcess } from "./agent-process.js";
 import {
@@ -113,6 +118,12 @@ interface SessionEntry {
    *  gate resume hints to the only adapter (claude-agent-acp) whose CLI
    *  accepts `--resume`. */
   command: string;
+  /** Identity of the Claude token this session ran with, whichever source it
+   *  came from. Recorded on the history row alongside the failure code, so the
+   *  marker can be compared against the credential a later spawn resolves
+   *  rather than needing a sweep to retire it. Absent for agents that use no
+   *  Claude credential. */
+  credentialDigest?: string;
 }
 
 /**
@@ -275,6 +286,14 @@ export class AcpSessionManager {
       );
     } catch (err) {
       log.error({ acpSessionId, agentId, err }, "ACP spawn failed");
+      // Here rather than at the tool boundary, because the HTTP spawn route
+      // reaches this method directly and would otherwise never record it. A
+      // configured CLAUDE_CODE_OAUTH_TOKEN that Claude refused keeps winning
+      // over whatever Connect stores until this is written down, so every
+      // later spawn repeats the same failure.
+      if (isAcpAuthRequired(err)) {
+        noteClaudeTokenRefused(agentConfig.credentialDigest, Date.now());
+      }
       // No prompt has fired yet, so no permissions can be pending.
       this.teardownSession(acpSessionId, entry);
       throw err;
@@ -374,6 +393,7 @@ export class AcpSessionManager {
       parentToolUseId: opts.parentToolUseId,
       task: opts.task,
       command: basename(opts.agentConfig.command),
+      credentialDigest: opts.agentConfig.credentialDigest,
     };
 
     this.sessions.set(acpSessionId, entry);
@@ -972,6 +992,8 @@ export class AcpSessionManager {
     const usageColumns = {
       task: entry.state.task ?? null,
       parentToolUseId: entry.state.parentToolUseId ?? null,
+      authErrorCode: entry.state.authErrorCode ?? null,
+      authErrorCredential: entry.state.authErrorCredential ?? null,
       usedTokens: usage?.usedTokens ?? null,
       contextSize: usage?.contextSize ?? null,
       costAmount: usage?.costAmount ?? null,
@@ -1114,7 +1136,7 @@ export class AcpSessionManager {
           }
         }
       })
-      .catch((err: Error) => {
+      .catch(async (err: Error) => {
         const current = this.sessions.get(acpSessionId);
         // Same guards: entry must exist, prompt must be current, and status
         // must not have been set to "cancelled".
@@ -1158,7 +1180,59 @@ export class AcpSessionManager {
             errorCode !== undefined && current.state.status !== "cancelled"
               ? current.parentToolUseId
               : undefined;
-          if (errorCode !== undefined && recoveryAnchor !== undefined) {
+          // Claude refused this credential, so no later spawn should resolve
+          // it again. Recorded before the card is raised and independently of
+          // the marker, because the user may delete this run and clearing
+          // history must not put the revoked value back in play.
+          if (errorCode !== undefined) {
+            noteClaudeTokenRefused(current.credentialDigest, Date.now());
+          }
+          // The live event reaches clients that are listening now, and the
+          // card it raises deliberately skips connected-state self-healing, so
+          // nothing retires it until the next snapshot. If the credential has
+          // already been replaced, that snapshot is the only thing that would
+          // have withheld it, and it may be a navigation away. Ask the same
+          // question the read path asks, against the same source of truth.
+          //
+          // An optimisation, not the authority: a write landing right after
+          // this read raises a card the next snapshot withholds. The marker is
+          // written either way, so the read path still has the final say.
+          const stillCurrent =
+            errorCode !== undefined &&
+            recoveryAnchor !== undefined &&
+            acpAuthMarkerStillCurrent(
+              current.credentialDigest,
+              // Imported at call time so this module's load graph stays as it
+              // was: several suites stub `prepare-agent-env` with a partial
+              // factory, and a new static import from here would break their
+              // module resolution rather than their assertions.
+              await import("./prepare-agent-env.js")
+                .then((m) =>
+                  m.resolvedClaudeCredentialDigest(current.state.agentId),
+                )
+                // Unknown reads as current, matching the comparison itself:
+                // failing toward a card the next snapshot can withdraw beats
+                // withholding the user's only route back to auth.
+                .catch(() => current.credentialDigest),
+            );
+          // The credential read above suspends this handler, and a cancel
+          // landing in that window runs to completion first: `cancel()`
+          // persists the cancelled row, drops the event buffer and tears the
+          // session down. Carrying on would emit a card for a run the user
+          // stopped and, worse, persist a second time over a buffer that is
+          // already gone, replacing the stored event log with an empty one.
+          // The map is the evidence: `teardownSession` removes the entry, so an
+          // entry that is no longer the registered one means someone else has
+          // already finished this session and there is nothing left here to
+          // do.
+          if (this.sessions.get(acpSessionId) !== current) {
+            return;
+          }
+          if (
+            errorCode !== undefined &&
+            recoveryAnchor !== undefined &&
+            stillCurrent
+          ) {
             current.sendToVellum({
               type: "acp_auth_required",
               acpSessionId,
@@ -1169,7 +1243,36 @@ export class AcpSessionManager {
             // Same registry as the missing-token spawn path, so the
             // credential-prompt route redirects a redundant secure prompt at
             // the card instead of stacking a second one.
-            markAcpConnectCardRaised(current.parentConversationId);
+            markAcpConnectCardRaised(
+              current.parentConversationId,
+              current.state.agentId,
+            );
+            // The event above only reaches clients listening right now. The
+            // code goes on the state so `persistTerminal` (called just below)
+            // carries it to the history row, which is what a client that
+            // reopens the conversation re-raises the card from.
+            current.state.authErrorCode = errorCode;
+            // Tell clients to re-read the snapshot, which is the only thing
+            // that can withdraw this card. The check above reads the vault
+            // and then this branch runs, so a replacement completing in
+            // between publishes its own invalidation before the event goes
+            // out, and a client that acted on it would never look again. This
+            // nudge lands after, so whatever the snapshot says wins.
+            void import("../runtime/sync/sync-publisher.js")
+              .then(({ publishSyncInvalidation }) =>
+                publishSyncInvalidation([SYNC_TAGS.acpAuthRecovery]),
+              )
+              .catch((err: unknown) => {
+                log.warn(
+                  { err },
+                  "failed to publish ACP auth recovery invalidation",
+                );
+              });
+            // Named beside the code so the marker can answer for itself later.
+            // Without it the row says auth broke but not on what, and a reader
+            // has no way to tell a failure the user has since repaired from one
+            // still waiting on them.
+            current.state.authErrorCredential = current.credentialDigest;
           }
 
           // Persist the terminal row before teardown clears the buffer.
@@ -1187,9 +1290,10 @@ export class AcpSessionManager {
             this.notifyParent(
               current,
               `[ACP agent "${current.state.agentId}" failed]\n\n${failureMessage}` +
-                (recoveryAnchor !== undefined
-                  ? `\n\n${ACP_AUTH_RECOVERY_GUIDANCE}`
-                  : ""),
+                // Same predicate as the recovery surface above. Telling the
+                // model a Connect card is waiting when none was raised sends
+                // it to an affordance that does not exist.
+                (stillCurrent ? `\n\n${ACP_AUTH_RECOVERY_GUIDANCE}` : ""),
             );
           }
         }

package/src/acp/types.ts

@@ -12,6 +12,13 @@ export interface AcpAgentConfig {
   args: string[];
   description?: string;
   env?: Record<string, string>;
+  /**
+   * Identity of the Claude token `prepareAgentEnv` resolved into `env`,
+   * whichever source it came from. Recorded on the history row when Claude
+   * refuses it, so the marker can later be compared against the credential a
+   * spawn would resolve now. Absent for agents that use no Claude credential.
+   */
+  credentialDigest?: string;
 }
 
 /**
@@ -32,6 +39,16 @@ export interface AcpSessionState {
   task?: string;
   /** Tool-use id of the `acp_spawn` call that spawned this session, if any. */
   parentToolUseId?: string;
+  /**
+   * Credential failure that ended the run, when one did. Persisted on the
+   * history row so a client that reopens the conversation can re-raise the
+   * inline Connect card, and cleared there when a replacement token lands.
+   */
+  authErrorCode?: string;
+  /** Digest of the Claude token that failure was refused on, carried to the
+   *  history row so the marker can be compared against the credential a later
+   *  spawn resolves. */
+  authErrorCredential?: string;
   /** Latest context-window usage gauge, from the most recent `usage_update`. */
   latestUsage?: AcpUsageSnapshot;
 }

package/src/agent/attachments.ts

@@ -1,4 +1,8 @@
-import type { ContentBlock, Message } from "../providers/types.js";
+import {
+  attachmentIdFragment,
+  type ContentBlock,
+  type Message,
+} from "../providers/types.js";
 import { optimizeImageForTransport } from "./image-optimize.js";
 
 export interface MessageAttachmentInput {
@@ -91,6 +95,7 @@ export function attachmentsToContentBlocks(
             media_type: mediaType,
             data,
           },
+          ...attachmentIdFragment(attachment.id),
         } as ContentBlock;
       }
 
@@ -103,7 +108,7 @@ export function attachmentsToContentBlocks(
           filename: attachment.filename,
         },
         extracted_text: attachment.extractedText,
-        ...(attachment.id ? { _attachmentId: attachment.id } : {}),
+        ...attachmentIdFragment(attachment.id),
       } as ContentBlock;
     }),
   );

package/src/agent/loop.ts

@@ -797,6 +797,22 @@ export interface AgentLoopConstructorOptions {
    * result-time pass and the post-turn truncation covers the turn instead.
    */
   resolveConversationDir?: () => string | null;
+  /**
+   * Trim a freshly compacted history before it becomes the loop's working set.
+   *
+   * Compaction rebuilds history from the stored rows, so it can reintroduce
+   * content the caller had already trimmed out of the array it handed to
+   * `run()` (camera-frame retention is the case this exists for: the compaction
+   * model may retain any number of older frames, and the rebuilt history is
+   * sent on the very next request). The caller closes over whatever
+   * conversation state its trimming needs, which is what keeps this module free
+   * of any dependency on the daemon's conversation layer.
+   *
+   * Must be total: the loop treats a throw as "no trim" rather than failing the
+   * turn. Callers that hold no conversation (workflow leaf runs) omit it and
+   * the compacted history is installed as built.
+   */
+  transformCompactedHistory?: (messages: Message[]) => Message[];
 }
 
 export class AgentLoop {
@@ -818,6 +834,11 @@ export class AgentLoop {
   /** See {@link AgentLoopConstructorOptions.resolveConversationDir}. */
   private readonly resolveConversationDir: (() => string | null) | null;
 
+  /** See {@link AgentLoopConstructorOptions.transformCompactedHistory}. */
+  private readonly transformCompactedHistory:
+    | ((messages: Message[]) => Message[])
+    | null;
+
   /**
    * Loop-held compaction circuit breaker. The loop has a 1:1 lifetime with its
    * conversation, so it is the source of truth for the cross-turn failure
@@ -837,6 +858,7 @@ export class AgentLoop {
       resolveTools,
       conversationId,
       resolveConversationDir,
+      transformCompactedHistory,
     } = options;
     this.provider = provider;
     this.systemPrompt = systemPrompt;
@@ -846,6 +868,7 @@ export class AgentLoop {
     this.toolExecutor = toolExecutor ?? null;
     this.conversationId = conversationId;
     this.resolveConversationDir = resolveConversationDir ?? null;
+    this.transformCompactedHistory = transformCompactedHistory ?? null;
     this.compactionCircuit = new CompactionCircuit(this.conversationId);
   }
 
@@ -925,6 +948,34 @@ export class AgentLoop {
     }
   }
 
+  /**
+   * Run the caller's post-compaction trim over a freshly compacted history,
+   * falling back to the untrimmed array when no transform is configured or the
+   * transform throws.
+   *
+   * The trim narrows what the next request carries, so failing it is strictly
+   * worse than skipping it: the turn still has a valid history either way, and
+   * the caller's own passes cover the next turn. Kept best-effort for the same
+   * reason the caller's pre-run pass is.
+   */
+  private applyCompactedHistoryTransform(
+    compacted: Message[],
+    rlog: ReturnType<typeof getLogger>,
+  ): Message[] {
+    if (!this.transformCompactedHistory) {
+      return compacted;
+    }
+    try {
+      return this.transformCompactedHistory(compacted);
+    } catch (err) {
+      rlog.warn(
+        { err },
+        "Post-compaction history transform failed (non-fatal); keeping the compacted history as built",
+      );
+      return compacted;
+    }
+  }
+
   /**
    * Compact the running history in place when the budget gate trips.
    *
@@ -1363,7 +1414,14 @@ export class AgentLoop {
                   overflowSignal ?? undefined,
                 );
                 if (attempt.history) {
-                  history = attempt.history;
+                  // Trim before anything else reads the rebuilt array: the
+                  // provider call further down this same iteration sends it, so
+                  // content compaction reintroduced has to be brought back
+                  // within the caller's bounds here or it ships un-trimmed.
+                  history = this.applyCompactedHistoryTransform(
+                    attempt.history,
+                    rlog,
+                  );
                   // The compacted, re-injected array is the new base; output
                   // produced after this point is what the wrapper persists.
                   newMessagesStart = history.length;

package/src/api/events/contact-form-closed.ts

@@ -0,0 +1,32 @@
+/**
+ * `contact_form_closed` SSE event.
+ *
+ * Tells every connected client that a contact form is over, so the card comes
+ * down instead of sitting there offering to submit an answer the gateway will
+ * now refuse.
+ *
+ * Both contact forms are workspace-global, broadcast without a conversation,
+ * which is why this is its own event rather than `interaction_resolved`: that
+ * one is conversation-scoped on the wire and is deliberately not broadcast for
+ * a conversation-less interaction.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly from
+ * this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const ContactFormClosedEventSchema = z.object({
+  type: z.literal("contact_form_closed"),
+  requestId: z.string(),
+  /**
+   * Why it closed. Every client saw the form, so every client needs to know:
+   * "answered" and "cancelled" retire the card on the clients that did not
+   * answer it, and "timed_out" retires it on all of them.
+   */
+  reason: z.enum(["answered", "cancelled", "timed_out"]),
+});
+
+export type ContactFormClosedEvent = z.infer<
+  typeof ContactFormClosedEventSchema
+>;

package/src/api/events/contact-record-request.ts

@@ -0,0 +1,63 @@
+/**
+ * `contact_record_request` SSE event.
+ *
+ * Server to client form asking the guardian to confirm a contact record write
+ * the assistant proposed: a create, an update, or a delete. Emitted by the
+ * `contacts/record-prompt` IPC route while a `pendingContactPrompts` entry
+ * awaits a reply.
+ *
+ * The proposed values are a starting point, not a decision. The guardian may
+ * edit the name and notes before submitting, and the client posts the result
+ * straight to the gateway, which owns the write.
+ *
+ * The form closes when the guardian answers it, or with a
+ * `contact_form_closed` event if it times out first. `interaction_resolved`
+ * does not cover it: that event is conversation-scoped on the wire and is
+ * deliberately not broadcast for a conversation-less interaction like this
+ * one.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly from
+ * this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const ContactRecordRequestEventSchema = z.object({
+  type: z.literal("contact_record_request"),
+  requestId: z.string(),
+  operation: z.enum(["create", "update", "delete"]),
+  /** Target of an update or delete. Absent on create. */
+  contactId: z.string().optional(),
+  /** Current name of the target, so the form can show what is changing. */
+  currentDisplayName: z.string().optional(),
+  /**
+   * The target's current notes. The form submits a field only when it differs
+   * from what is stored, so it needs what is stored to compare against.
+   */
+  currentNotes: z.string().optional(),
+  /**
+   * The target's channels, so a delete confirmation can say which of two
+   * same-named contacts it is about, and what access is about to be lost.
+   */
+  channels: z
+    .array(z.object({ type: z.string(), address: z.string() }))
+    .optional(),
+
+  /** Proposed name, prefilled into the form. */
+  displayName: z.string().optional(),
+  /** Proposed notes, prefilled into the form. */
+  notes: z.string().optional(),
+  /**
+   * Whether the caller asked for these notes explicitly. A proposal that
+   * happens to match what is stored is still a change the guardian confirmed,
+   * and an unreadable mirror reports stored notes as empty, so the form cannot
+   * tell "clear them" from "nothing to do" by comparison alone.
+   */
+  notesProposed: z.boolean().optional(),
+  label: z.string().optional(),
+  description: z.string().optional(),
+});
+
+export type ContactRecordRequestEvent = z.infer<
+  typeof ContactRecordRequestEventSchema
+>;

package/src/api/events/contact-request.ts

@@ -5,9 +5,11 @@
  * address (phone, email, etc.). Emitted by the `contacts/prompt` IPC
  * route while a `pendingContactPrompts` entry awaits a reply.
  *
- * Resolved by a paired `interaction_resolved` event (`kind:
- * "contact"`, `state: "answered" | "cancelled"`) once the user
- * responds or the timeout fires.
+ * The form closes when the user answers it, or with a
+ * `contact_form_closed` event if it times out first. `interaction_resolved`
+ * does not cover it: that event is conversation-scoped on the wire and is
+ * deliberately not broadcast for a conversation-less interaction like this
+ * one.
  *
  * `channel` and `role` are advisory hints, not enforced enums — the
  * client may render any input it likes and post back a structured
@@ -29,6 +31,11 @@ export const ContactRequestEventSchema = z.object({
   label: z.string().optional(),
   description: z.string().optional(),
   role: z.string().optional(),
+  /**
+   * Initial state of the form's "mark verified" checkbox, from the CLI's
+   * `--verify`. What the guardian submits is what gets attested.
+   */
+  verify: z.boolean().optional(),
 });
 
 export type ContactRequestEvent = z.infer<typeof ContactRequestEventSchema>;

package/src/api/index.ts

@@ -23,6 +23,8 @@ import { CompactionCircuitOpenEventSchema } from "./events/compaction-circuit-op
 import { ConfigChangedEventSchema } from "./events/config-changed.js";
 import { ConfirmationRequestEventSchema } from "./events/confirmation-request.js";
 import { ConfirmationStateChangedEventSchema } from "./events/confirmation-state-changed.js";
+import { ContactFormClosedEventSchema } from "./events/contact-form-closed.js";
+import { ContactRecordRequestEventSchema } from "./events/contact-record-request.js";
 import { ContactRequestEventSchema } from "./events/contact-request.js";
 import { ContactsChangedEventSchema } from "./events/contacts-changed.js";
 import { ContextCompactedEventSchema } from "./events/context-compacted.js";
@@ -285,6 +287,14 @@ export {
   type ConfirmationStateChangedEvent,
   ConfirmationStateChangedEventSchema,
 } from "./events/confirmation-state-changed.js";
+export {
+  type ContactFormClosedEvent,
+  ContactFormClosedEventSchema,
+} from "./events/contact-form-closed.js";
+export {
+  type ContactRecordRequestEvent,
+  ContactRecordRequestEventSchema,
+} from "./events/contact-record-request.js";
 export {
   type ContactRequestEvent,
   ContactRequestEventSchema,
@@ -767,6 +777,12 @@ export {
   type FeedItemDetailPanelKind,
   FeedItemDetailPanelKindSchema,
   FeedItemDetailPanelSchema,
+  type FeedItemGuardianIntent,
+  FeedItemGuardianIntentSchema,
+  type FeedItemGuardianRequest,
+  FeedItemGuardianRequestSchema,
+  type FeedItemGuardianStatus,
+  FeedItemGuardianStatusSchema,
   FeedItemSchema,
   type FeedItemSourceType,
   FeedItemSourceTypeSchema,
@@ -776,8 +792,10 @@ export {
   FeedItemTypeSchema,
   type FeedItemUrgency,
   FeedItemUrgencySchema,
+  GUARDIAN_TERMINAL_REASON_SUPERSEDED,
   type HomeFeedResponse,
   HomeFeedResponseSchema,
+  isPendingGuardianFeedItem,
   type RelationshipState,
   RelationshipStateSchema,
   type RelationshipTier,
@@ -952,6 +970,8 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   ConfigChangedEventSchema,
   ConfirmationRequestEventSchema,
   ConfirmationStateChangedEventSchema,
+  ContactFormClosedEventSchema,
+  ContactRecordRequestEventSchema,
   ContactRequestEventSchema,
   ContactsChangedEventSchema,
   ContextCompactedEventSchema,

package/src/api/responses/conversation-message.ts

@@ -607,6 +607,26 @@ export const ConversationMessageSchema = z.object({
    *  system notices — no avatar, no persona bubble — and never group them
    *  with adjacent assistant turns. */
   systemCard: z.boolean().optional(),
+  /** Set on a turn whose whole reply was the `<no_response/>` sentinel
+   *  (`metadata.messageKind === "no_response"`): the assistant deliberately
+   *  chose silence. Clients render a quiet standalone notice instead of the
+   *  sentinel text, and treat the row as the turn's reply so nothing keeps
+   *  waiting for one. */
+  noResponse: z.boolean().optional(),
+  /** Present on a reaction row, either direction: an inbound reaction the
+   *  daemon persisted, or the assistant's own (`selfAuthored`). Clients
+   *  render a reaction line from this instead of the row's stored sentinel
+   *  text. Slack rows additionally carry their own `slackMessage` envelope,
+   *  which Slack-aware renderers may prefer. */
+  reaction: z
+    .object({
+      emoji: z.string(),
+      op: z.enum(["added", "removed"]),
+      targetMessageId: z.string(),
+      actorDisplayName: z.string().optional(),
+      selfAuthored: z.boolean().optional(),
+    })
+    .optional(),
   /** Present when this assistant row is a daemon-persisted provider-failure
    *  notice (`metadata.messageKind === "provider_error"`); clients may render
    *  a themed card instead of a persona bubble. `code` is the stable

package/src/api/responses/home.ts

@@ -107,6 +107,83 @@ export const FeedItemDetailPanelSchema = z.object({
 });
 export type FeedItemDetailPanel = z.infer<typeof FeedItemDetailPanelSchema>;
 
+/**
+ * Canonical guardian-request status projected onto a feed item.
+ *
+ * Values mirror `GuardianRequestStatusSchema` in
+ * `@vellumai/gateway-client` (this file is copied verbatim into client
+ * packages, so it cannot import the contract; the daemon's projection
+ * writer asserts the two stay aligned at compile time).
+ */
+export const FeedItemGuardianStatusSchema = z.enum([
+  "pending",
+  "approved",
+  "denied",
+  "expired",
+  "cancelled",
+]);
+export type FeedItemGuardianStatus = z.infer<
+  typeof FeedItemGuardianStatusSchema
+>;
+
+/** Whether the guardian is being asked to approve or to answer. */
+export const FeedItemGuardianIntentSchema = z.enum(["approval", "question"]);
+export type FeedItemGuardianIntent = z.infer<
+  typeof FeedItemGuardianIntentSchema
+>;
+
+/**
+ * Read projection of one canonical guardian request onto its feed item.
+ *
+ * The feed item carrying this is the request's single "Needs attention"
+ * home: exactly one item per `requestId`, kept current by the daemon's
+ * status fan-out. Clients derive every affordance from `status` +
+ * `intent`: a `pending` approval offers Approve/Reject (via
+ * `POST /v1/guardian-actions/decision`), a `pending` question routes to
+ * the source conversation, and a terminal status renders as a receipt.
+ * Nothing here is an independent delivery record; it restates gateway
+ * `guardian_requests` state and is never a source of truth on its own.
+ */
+export const FeedItemGuardianRequestSchema = z.object({
+  requestId: z.string(),
+  /**
+   * Guardian request kind (`tool_approval`, `tool_grant_request`,
+   * `pending_question`, `access_request`). A string rather than an enum so
+   * rows written by a newer daemon still parse.
+   */
+  kind: z.string(),
+  intent: FeedItemGuardianIntentSchema,
+  status: FeedItemGuardianStatusSchema,
+  /** Display name or identifier of the requester (e.g. "Alice"). */
+  requesterLabel: z.string().optional(),
+  /** Tool the request is about, when it is a tool approval/grant. */
+  toolName: z.string().optional(),
+  /** Channel the request originated from (e.g. "slack"). */
+  sourceChannel: z.string().optional(),
+  /** Display label for the originating chat (e.g. "#user-feedback"). */
+  sourceContextLabel: z.string().optional(),
+  /** Permalink to the originating channel message, when derivable. */
+  sourceUrl: z.string().optional(),
+  /** Web URL of the Slack guardian-DM approval card ("Open in Slack"). */
+  slackCardUrl: z.string().optional(),
+  /** slack:// deep link for the same card, preferred on devices with the app. */
+  slackCardAppUrl: z.string().optional(),
+  /** Action that resolved the request, for terminal statuses. */
+  decidedAction: z.string().optional(),
+  /** Display label of the decider, when the decision came from a person. */
+  decidedByLabel: z.string().optional(),
+  /** ISO-8601 time the request reached its terminal status. */
+  decidedAt: z.string().optional(),
+  /**
+   * Why a non-decision terminal status was reached (e.g. `superseded`
+   * when a newer message auto-denied the request). Display-only.
+   */
+  terminalReason: z.string().optional(),
+});
+export type FeedItemGuardianRequest = z.infer<
+  typeof FeedItemGuardianRequestSchema
+>;
+
 /**
  * A single item rendered in the Home feed.
  *
@@ -135,6 +212,9 @@ export const FeedItemSchema = z.object({
   urgency: FeedItemUrgencySchema.optional(),
   conversationId: z.string().optional(),
   detailPanel: FeedItemDetailPanelSchema.optional(),
+  // Present only on the canonical "Needs attention" item projecting a
+  // guardian request; see FeedItemGuardianRequestSchema.
+  guardianRequest: FeedItemGuardianRequestSchema.optional(),
   category: FeedItemCategorySchema.optional(),
   noteworthy: z.boolean().optional(),
   fromAssistant: z.boolean().optional(),
@@ -150,6 +230,27 @@ export const FeedItemSchema = z.object({
 });
 export type FeedItem = z.infer<typeof FeedItemSchema>;
 
+/**
+ * `terminalReason` value for a request auto-denied because a newer
+ * inbound message superseded it. Shared by the daemon rails that record
+ * it and the clients that render "Superseded" instead of a rejection.
+ */
+export const GUARDIAN_TERMINAL_REASON_SUPERSEDED = "superseded";
+
+/**
+ * Whether a feed item is the live projection of an unresolved guardian
+ * request. Shared by the daemon (bulk-dismiss protection in the feed
+ * writer) and clients (visibility carve-outs, bulk-action id sets) so
+ * "pending guardian item" means the same thing on both sides: such an
+ * item must stay actionable until the canonical request resolves, and
+ * only its terminal receipt is ordinarily clearable.
+ */
+export function isPendingGuardianFeedItem(
+  item: Pick<FeedItem, "guardianRequest">,
+): boolean {
+  return item.guardianRequest?.status === "pending";
+}
+
 // ---------------------------------------------------------------------------
 // Suggested prompt
 // ---------------------------------------------------------------------------