@vellumai/assistant 0.11.4-staging.3 → 0.11.4

package/docs/guardian-request-flow.md

@@ -54,6 +54,41 @@ anti-pattern was retired in #35642 and again in the ask_question redesign).
 | Kind-specific follow-through            | resolver registry (`kind` → resolver)                    | switch statements in the router     |
 | Reply understanding                     | guardian reply router (codes, buttons, reactions, modes) | per-feature inbound intercepts      |
 
+## Cards are not conversation history
+
+`pairDeliveryWithConversation` persists one message row per delivery so the
+card renders and deep-links. For a guardian card that row is addressed to a
+conversation the request is _about_, not one the assistant is speaking in:
+`buildVellumCardAffinity` pins the vellum card to the originating
+conversation, and a channel card lands in whatever conversation the guardian's
+chat binds to. Either way the row is written straight to the DB by the
+notification pipeline, so the live turn's in-memory history never sees it.
+
+That row must never be replayed to the model. The conversation it lands in is
+typically parked mid-approval, with its last assistant message carrying the
+`tool_use` still waiting on this very decision. Replayed, the card sits
+between that `tool_use` and its `tool_result`; history repair reads the pair
+as broken, synthesizes a stub result, and downgrades the real one to text. A
+card left as the tail row instead ends the history on an assistant message,
+which extended-thinking models reject outright ("does not support assistant
+message prefill").
+
+`isGuardianCardRow` (`notifications/approval-card-data.ts`) is the one
+definition of which rows those are, read off the card's own `ui_surface` id
+using the same prefixes `approvalCardSurfaceId` recomputes for withdrawal. It
+is derived rather than stored so a row written before the rule existed is
+recognized on the same terms as a new one, with no marker to backfill.
+
+**Both history assemblers must consult it.** `Conversation.loadFromDb` builds
+`this.messages`, but Slack conversations do not use that list:
+`loadSlackChronologicalContext` re-reads the rows. A rule applied to only one
+exempts the other channel. Each applies it _after_ its own compaction boundary,
+since both boundaries are computed against unfiltered row lists.
+
+Surface state is deliberately NOT filtered this way. `restoreSurfaceStateFromHistory`
+takes the pre-filter window, because a card's Approve/Reject buttons must keep
+routing after a restart even though the card is absent from the model's history.
+
 Two instruction modes exist per request kind (`notifications/guardian-question-mode.ts`):
 **approval** ("CODE approve" / approve–reject buttons) and **answer**
 ("CODE <your answer>" / option buttons). `pending_question` is answer-mode.

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -11,6 +11,12 @@
  *       (`gateway/src/http/routes/remote-web-pairing-verification.ts`)
  *   - `POST /v1/remote-web/pairing-token`         poll + exchange device code
  *       (`gateway/src/http/routes/remote-web-pairing-token.ts`)
+ *   - `GET  /v1/remote-web/pairing-requests`          list pending challenges
+ *       (loopback-only)
+ *   - `POST /v1/remote-web/pairing-requests/approve`  approve by request id
+ *       (loopback-only)
+ *   - `POST /v1/remote-web/pairing-requests/deny`     deny (delete) by request id
+ *       (loopback-only)
  *
  * These shapes mirror those handlers' request/response bodies exactly so the
  * gateway, the `vellum pair` CLI (`cli/src/commands/pair.ts`), and the web SPA
@@ -68,6 +74,60 @@ export interface RemoteWebPairingVerificationResponse {
   expiresAt: string;
 }
 
+/**
+ * One pending challenge as shown on a host approval surface.
+ *
+ * The requesting device already sees the plaintext `userCode` in its own
+ * challenge response ({@link RemoteWebPairingChallengeResponse.userCode});
+ * the loopback-gated list route is the only host-side re-exposure. Displaying
+ * it there is what lets the approver match the code against the requesting
+ * device's screen: the device-flow anti-phishing binding.
+ */
+export interface RemoteWebPairingRequestSummary {
+  /** Opaque server-side id used to approve or deny this request. */
+  requestId: string;
+  /** The human-readable code the requesting device is displaying (e.g. "ABCD-EFGH"). */
+  userCode: string;
+  /** Public base URL the challenge was minted for. */
+  publicBaseUrl: string;
+  /** ISO-8601 instant the challenge was minted. */
+  requestedAt: string;
+  /** ISO-8601 instant the challenge expires. */
+  expiresAt: string;
+  /**
+   * Client IP of the mint request: the loopback/host address when minted
+   * locally, or the edge-observed client address when the mint arrived
+   * through the nginx tunnel edge (which stamps it via `proxy_set_header`,
+   * so a remote client cannot smuggle a value).
+   */
+  requesterIp: string;
+  /** User-Agent header of the mint request, or null when absent. */
+  requesterUserAgent: string | null;
+  /**
+   * Whether the mint arrived through the public tunnel edge rather than the
+   * host itself.
+   */
+  viaEdgeProxy: boolean;
+}
+
+/** `GET /v1/remote-web/pairing-requests` success response body (200). */
+export interface RemoteWebPairingRequestListResponse {
+  requests: RemoteWebPairingRequestSummary[];
+}
+
+/**
+ * Request body for the pairing-request approve and deny routes. The approve
+ * route's success body reuses {@link RemoteWebPairingVerificationResponse}.
+ */
+export interface RemoteWebPairingRequestActionRequest {
+  requestId: string;
+}
+
+/** `POST /v1/remote-web/pairing-requests/deny` success response body (200). */
+export interface RemoteWebPairingRequestDenyResponse {
+  status: "denied";
+}
+
 /** `POST /v1/remote-web/pairing-token` request body. */
 export interface RemoteWebPairingTokenRequest {
   /** The `deviceCode` from the challenge. */

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -11,6 +11,12 @@
  *       (`gateway/src/http/routes/remote-web-pairing-verification.ts`)
  *   - `POST /v1/remote-web/pairing-token`         poll + exchange device code
  *       (`gateway/src/http/routes/remote-web-pairing-token.ts`)
+ *   - `GET  /v1/remote-web/pairing-requests`          list pending challenges
+ *       (loopback-only)
+ *   - `POST /v1/remote-web/pairing-requests/approve`  approve by request id
+ *       (loopback-only)
+ *   - `POST /v1/remote-web/pairing-requests/deny`     deny (delete) by request id
+ *       (loopback-only)
  *
  * These shapes mirror those handlers' request/response bodies exactly so the
  * gateway, the `vellum pair` CLI (`cli/src/commands/pair.ts`), and the web SPA
@@ -68,6 +74,60 @@ export interface RemoteWebPairingVerificationResponse {
   expiresAt: string;
 }
 
+/**
+ * One pending challenge as shown on a host approval surface.
+ *
+ * The requesting device already sees the plaintext `userCode` in its own
+ * challenge response ({@link RemoteWebPairingChallengeResponse.userCode});
+ * the loopback-gated list route is the only host-side re-exposure. Displaying
+ * it there is what lets the approver match the code against the requesting
+ * device's screen: the device-flow anti-phishing binding.
+ */
+export interface RemoteWebPairingRequestSummary {
+  /** Opaque server-side id used to approve or deny this request. */
+  requestId: string;
+  /** The human-readable code the requesting device is displaying (e.g. "ABCD-EFGH"). */
+  userCode: string;
+  /** Public base URL the challenge was minted for. */
+  publicBaseUrl: string;
+  /** ISO-8601 instant the challenge was minted. */
+  requestedAt: string;
+  /** ISO-8601 instant the challenge expires. */
+  expiresAt: string;
+  /**
+   * Client IP of the mint request: the loopback/host address when minted
+   * locally, or the edge-observed client address when the mint arrived
+   * through the nginx tunnel edge (which stamps it via `proxy_set_header`,
+   * so a remote client cannot smuggle a value).
+   */
+  requesterIp: string;
+  /** User-Agent header of the mint request, or null when absent. */
+  requesterUserAgent: string | null;
+  /**
+   * Whether the mint arrived through the public tunnel edge rather than the
+   * host itself.
+   */
+  viaEdgeProxy: boolean;
+}
+
+/** `GET /v1/remote-web/pairing-requests` success response body (200). */
+export interface RemoteWebPairingRequestListResponse {
+  requests: RemoteWebPairingRequestSummary[];
+}
+
+/**
+ * Request body for the pairing-request approve and deny routes. The approve
+ * route's success body reuses {@link RemoteWebPairingVerificationResponse}.
+ */
+export interface RemoteWebPairingRequestActionRequest {
+  requestId: string;
+}
+
+/** `POST /v1/remote-web/pairing-requests/deny` success response body (200). */
+export interface RemoteWebPairingRequestDenyResponse {
+  status: "denied";
+}
+
 /** `POST /v1/remote-web/pairing-token` request body. */
 export interface RemoteWebPairingTokenRequest {
   /** The `deviceCode` from the challenge. */

package/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -11,6 +11,12 @@
  *       (`gateway/src/http/routes/remote-web-pairing-verification.ts`)
  *   - `POST /v1/remote-web/pairing-token`         poll + exchange device code
  *       (`gateway/src/http/routes/remote-web-pairing-token.ts`)
+ *   - `GET  /v1/remote-web/pairing-requests`          list pending challenges
+ *       (loopback-only)
+ *   - `POST /v1/remote-web/pairing-requests/approve`  approve by request id
+ *       (loopback-only)
+ *   - `POST /v1/remote-web/pairing-requests/deny`     deny (delete) by request id
+ *       (loopback-only)
  *
  * These shapes mirror those handlers' request/response bodies exactly so the
  * gateway, the `vellum pair` CLI (`cli/src/commands/pair.ts`), and the web SPA
@@ -68,6 +74,60 @@ export interface RemoteWebPairingVerificationResponse {
   expiresAt: string;
 }
 
+/**
+ * One pending challenge as shown on a host approval surface.
+ *
+ * The requesting device already sees the plaintext `userCode` in its own
+ * challenge response ({@link RemoteWebPairingChallengeResponse.userCode});
+ * the loopback-gated list route is the only host-side re-exposure. Displaying
+ * it there is what lets the approver match the code against the requesting
+ * device's screen: the device-flow anti-phishing binding.
+ */
+export interface RemoteWebPairingRequestSummary {
+  /** Opaque server-side id used to approve or deny this request. */
+  requestId: string;
+  /** The human-readable code the requesting device is displaying (e.g. "ABCD-EFGH"). */
+  userCode: string;
+  /** Public base URL the challenge was minted for. */
+  publicBaseUrl: string;
+  /** ISO-8601 instant the challenge was minted. */
+  requestedAt: string;
+  /** ISO-8601 instant the challenge expires. */
+  expiresAt: string;
+  /**
+   * Client IP of the mint request: the loopback/host address when minted
+   * locally, or the edge-observed client address when the mint arrived
+   * through the nginx tunnel edge (which stamps it via `proxy_set_header`,
+   * so a remote client cannot smuggle a value).
+   */
+  requesterIp: string;
+  /** User-Agent header of the mint request, or null when absent. */
+  requesterUserAgent: string | null;
+  /**
+   * Whether the mint arrived through the public tunnel edge rather than the
+   * host itself.
+   */
+  viaEdgeProxy: boolean;
+}
+
+/** `GET /v1/remote-web/pairing-requests` success response body (200). */
+export interface RemoteWebPairingRequestListResponse {
+  requests: RemoteWebPairingRequestSummary[];
+}
+
+/**
+ * Request body for the pairing-request approve and deny routes. The approve
+ * route's success body reuses {@link RemoteWebPairingVerificationResponse}.
+ */
+export interface RemoteWebPairingRequestActionRequest {
+  requestId: string;
+}
+
+/** `POST /v1/remote-web/pairing-requests/deny` success response body (200). */
+export interface RemoteWebPairingRequestDenyResponse {
+  status: "denied";
+}
+
 /** `POST /v1/remote-web/pairing-token` request body. */
 export interface RemoteWebPairingTokenRequest {
   /** The `deviceCode` from the challenge. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.4-staging.3",
+  "version": "0.11.4",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/conversation-load-history-repair.test.ts

@@ -713,3 +713,212 @@ describe("loadFromDb tool-result truncation", () => {
     ).toBe(preStubbed);
   });
 });
+
+/**
+ * A guardian card is written into the conversation the request came from by
+ * the notification pairing layer, straight to the DB, while that
+ * conversation's turn is parked awaiting the approval. On the next load it
+ * lands between the parked turn's `tool_use` and its `tool_result`.
+ *
+ * The card is recognized by its own `ui_surface` id rather than a stored
+ * marker, so rows written before this rule existed are dropped on the same
+ * terms as new ones.
+ */
+describe("guardian card rows are not replayed as conversation history", () => {
+  const baseConversation = {
+    id: "conv-1",
+    contextSummary: null,
+    contextCompactedMessageCount: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalEstimatedCost: 0,
+  };
+
+  /** The parked turn: an approval-gated `tool_use` and the result it got. */
+  const toolUseRow = {
+    id: "m-use",
+    role: "assistant",
+    content: [
+      { type: "text", text: "Running that now." },
+      { type: "tool_use", id: "tu_1", name: "bash", input: { cmd: "ls" } },
+    ],
+  };
+  const toolResultRow = {
+    id: "m-result",
+    role: "user",
+    content: [
+      { type: "tool_result", tool_use_id: "tu_1", content: "REAL RESULT" },
+    ],
+  };
+
+  /** What `buildApprovalCardBlocks` persists: the surface, then its text. */
+  function cardRow(surfaceId: string) {
+    return {
+      id: "m-card",
+      role: "assistant",
+      content: [
+        {
+          type: "ui_surface",
+          surfaceId,
+          surfaceType: "card",
+          title: "Tool Approval",
+          data: {},
+          display: "inline",
+        },
+        { type: "text", text: "Tool Approval\nbash - requested by Alice" },
+      ],
+    };
+  }
+
+  function allBlocks(messages: Message[]) {
+    return messages.flatMap((m) => m.content);
+  }
+
+  function toolResultsFor(messages: Message[], toolUseId: string) {
+    return allBlocks(messages).filter(
+      (b) => b.type === "tool_result" && b.tool_use_id === toolUseId,
+    );
+  }
+
+  function serialized(value: unknown): string {
+    return JSON.stringify(value);
+  }
+
+  beforeEach(() => {
+    nextMockMessageId = 1;
+    mockConversation = { ...baseConversation };
+  });
+
+  // Sensitivity check for the drop below: an ordinary assistant turn in the
+  // same position still corrupts the pair. If the rule ever widened past
+  // guardian cards, this test fails first and says so.
+  test("an ordinary assistant turn between a tool_use and its result still corrupts it", async () => {
+    mockDbMessages = [
+      toolUseRow,
+      {
+        id: "m-card",
+        role: "assistant",
+        content: [{ type: "text", text: "Still working on it." }],
+      },
+      toolResultRow,
+    ];
+
+    const conversation = makeConversation();
+    await conversation.loadFromDb();
+    const messages = conversation.getMessages();
+
+    expect(serialized(messages)).toContain("tool result missing from history");
+    expect(serialized(messages)).toContain("[orphaned tool_result for tu_1]");
+    expect(serialized(toolResultsFor(messages, "tu_1"))).not.toContain(
+      "REAL RESULT",
+    );
+  });
+
+  test("a guardian card is dropped and the real tool_result survives", async () => {
+    mockDbMessages = [
+      toolUseRow,
+      cardRow("tool-approval-req-1"),
+      toolResultRow,
+    ];
+
+    const conversation = makeConversation();
+    await conversation.loadFromDb();
+    const messages = conversation.getMessages();
+
+    // The pair is adjacent and intact: no stub, no downgrade, and exactly one
+    // tool_result for tu_1 carrying the tool's own output.
+    expect(serialized(messages)).not.toContain(
+      "tool result missing from history",
+    );
+    expect(serialized(messages)).not.toContain("[orphaned tool_result");
+    const results = toolResultsFor(messages, "tu_1");
+    expect(results).toHaveLength(1);
+    expect(results[0].type === "tool_result" && results[0].content).toBe(
+      "REAL RESULT",
+    );
+    expect(serialized(messages)).not.toContain("Tool Approval");
+    expect(messages).toHaveLength(2);
+  });
+
+  test("an access-request card is dropped on the same terms", async () => {
+    mockDbMessages = [
+      toolUseRow,
+      cardRow("access-request-req-9"),
+      toolResultRow,
+    ];
+
+    const conversation = makeConversation();
+    await conversation.loadFromDb();
+    const messages = conversation.getMessages();
+
+    expect(serialized(messages)).not.toContain("[orphaned tool_result");
+    expect(messages).toHaveLength(2);
+  });
+
+  test("a card as the tail row leaves history ending on a user message", async () => {
+    // The prefill shape: the approval was delivered and the turn never
+    // resumed, so the card is the last row. Replayed, it makes the history
+    // end on an assistant turn, which extended-thinking models reject with
+    // "does not support assistant message prefill".
+    mockDbMessages = [toolUseRow, cardRow("tool-approval-req-1")];
+
+    const conversation = makeConversation();
+    await conversation.loadFromDb();
+    const messages = conversation.getMessages();
+
+    expect(messages[messages.length - 1].role).toBe("user");
+    // The tail is repair's fill for the still-unanswered tool_use, which is
+    // correct here: the tool genuinely never ran.
+    expect(toolResultsFor(messages, "tu_1")).toHaveLength(1);
+  });
+
+  test("a dropped card still restores its ui_surface for action routing", async () => {
+    // Surface lifecycle and model context are different questions. The card is
+    // absent from history, but its Approve/Reject buttons must keep routing
+    // after a restart, which `findConversationBySurfaceId` resolves through
+    // surfaceState rebuilt at load.
+    mockDbMessages = [toolUseRow, cardRow("tool-approval-req-1")];
+
+    const conversation = makeConversation();
+    await conversation.loadFromDb();
+
+    expect(serialized(conversation.getMessages())).not.toContain(
+      "tool-approval-req-1",
+    );
+    expect(
+      (
+        conversation as unknown as { surfaceState: Map<string, unknown> }
+      ).surfaceState.has("tool-approval-req-1"),
+    ).toBe(true);
+  });
+
+  test("an assistant turn carrying a non-approval surface stays in history", async () => {
+    // A wake card is unshifted onto a real turn's own content. Its surface id
+    // uses a different prefix, and dropping that row would discard speech.
+    mockDbMessages = [
+      { id: "m-ask", role: "user", content: [{ type: "text", text: "hi" }] },
+      {
+        id: "m-wake",
+        role: "assistant",
+        content: [
+          {
+            type: "ui_surface",
+            surfaceId: "wake-conv-1-1700000000",
+            surfaceType: "card",
+            title: "Conversation Woke",
+            data: {},
+            display: "inline",
+          },
+          { type: "text", text: "Picking this back up." },
+        ],
+      },
+    ];
+
+    const conversation = makeConversation();
+    await conversation.loadFromDb();
+
+    expect(serialized(conversation.getMessages())).toContain(
+      "Picking this back up.",
+    );
+  });
+});

package/src/__tests__/conversation-runtime-assembly.test.ts

@@ -4024,6 +4024,59 @@ describe("Slack channel chronological rendering — multi-thread", () => {
     expect(allText).not.toContain("private guardian-only context");
   });
 
+  // Slack builds provider history from rows rather than `this.messages`, so a
+  // guardian card dropped only at `Conversation.loadFromDb` would still reach
+  // the model here -- the channel the incident happened on.
+  test("loadSlackChronologicalContext drops guardian card rows", () => {
+    const caps: ChannelCapabilities = {
+      channel: "slack",
+      dashboardCapable: false,
+      supportsDynamicUi: false,
+      supportsVoiceInput: false,
+      chatType: "channel",
+    };
+    const cardRow: MessageRow = {
+      id: "m-card",
+      conversationId: "conv-1",
+      role: "assistant",
+      content: [
+        {
+          type: "ui_surface",
+          surfaceId: "tool-approval-req-1",
+          surfaceType: "card",
+          title: "Tool Approval",
+          data: {},
+          display: "inline",
+        },
+        { type: "text", text: "Tool Approval card body" },
+      ],
+      createdAt: 1700000035_000,
+      metadata: null,
+      clientMessageId: null,
+      finalized: 1,
+    } as MessageRow;
+    const rows: MessageRow[] = [
+      userRow({
+        id: "asked",
+        createdAt: 1700000030_000,
+        text: "please run it",
+        slackMeta: buildSlackMeta({ channelTs: T2, displayName: "carol" }),
+      }),
+      cardRow,
+    ];
+
+    const result = loadSlackChronologicalContext("conv-1", caps, {
+      loader: () => rows,
+      trustClass: "guardian",
+    });
+
+    expect(result).not.toBeNull();
+    const renderedText = JSON.stringify(result!.messages);
+    expect(renderedText).toContain("please run it");
+    expect(renderedText).not.toContain("Tool Approval card body");
+    expect(renderedText).not.toContain("tool-approval-req-1");
+  });
+
   test("loadSlackChronologicalContext preserves summary and filters by Slack watermark", () => {
     const caps: ChannelCapabilities = {
       channel: "slack",