@vellumai/assistant 0.11.7 → 0.11.8-staging.1

package/src/calls/__tests__/voice-session-bridge.test.ts

@@ -39,6 +39,31 @@ mock.module("../../plugin-api/vision-support.js", () => ({
   doesSupportVision: () => pinProfileSupportsVision,
 }));
 
+// Attachment hydration for the parked-camera-frame path. Only `att-frame-*`
+// ids exist; anything else resolves to nothing, which is how an id the client
+// invented reaches the bridge. `collectedAttachmentIds` is the store's other
+// half: the fake `deleteMessageById` below writes into it under the real
+// orphan rule, so an id the cleanup ate stops resolving here, exactly as a
+// deleted attachment row would.
+import * as realAttachmentsStore from "../../persistence/attachments-store.js";
+
+const collectedAttachmentIds = new Set<string>();
+
+mock.module("../../persistence/attachments-store.js", () => ({
+  ...realAttachmentsStore,
+  resolveAttachmentsForPersist: (ids: string[]) =>
+    ids
+      .filter(
+        (id) => id.startsWith("att-frame-") && !collectedAttachmentIds.has(id),
+      )
+      .map((id) => ({
+        id,
+        filename: `${id}.png`,
+        mimeType: "image/png",
+        data: "ZnJhbWU=",
+      })),
+}));
+
 // Conversation-CRUD doubles for the teardown transcript-hygiene pass. The
 // real module is spread so every other export keeps its production behavior;
 // only the functions the hygiene pass (and discard) touch are recorded.
@@ -48,15 +73,22 @@ let getMessageByIdImpl: (
   messageId: string,
   conversationId?: string,
 ) => unknown = () => null;
+// Attachment ids each persisted message links, so the fake delete below can
+// apply the orphan rule to the same candidate set the real one would collect.
+const messageAttachmentLinks = new Map<string, string[]>();
 const crudLog: {
   reads: string[];
   updates: Array<{ messageId: string; content: string }>;
   deletes: string[];
-} = { reads: [], updates: [], deletes: [] };
+  retained: Array<{ messageId: string; ids: readonly string[] }>;
+} = { reads: [], updates: [], deletes: [], retained: [] };
 function resetCrudLog(): void {
   crudLog.reads.length = 0;
   crudLog.updates.length = 0;
   crudLog.deletes.length = 0;
+  crudLog.retained.length = 0;
+  messageAttachmentLinks.clear();
+  collectedAttachmentIds.clear();
   getMessageByIdImpl = () => null;
 }
 
@@ -69,8 +101,23 @@ mock.module("../../persistence/conversation-crud.js", () => ({
   updateMessageContent: (messageId: string, content: string) => {
     crudLog.updates.push({ messageId, content });
   },
-  deleteMessageById: (messageId: string) => {
+  deleteMessageById: (
+    messageId: string,
+    options?: { retainAttachmentIds?: readonly string[] },
+  ) => {
     crudLog.deletes.push(messageId);
+    const retained = options?.retainAttachmentIds ?? [];
+    crudLog.retained.push({ messageId, ids: retained });
+    // Mirrors the real cleanup: the row's own attachment links are the
+    // candidate set, and a candidate nothing else references is collected
+    // unless the caller retained it. Every id here is referenced by this one
+    // row, which is the case the rollback path is about.
+    for (const id of messageAttachmentLinks.get(messageId) ?? []) {
+      if (!retained.includes(id)) {
+        collectedAttachmentIds.add(id);
+      }
+    }
+    messageAttachmentLinks.delete(messageId);
     return { segmentIds: [], deletedSummaryIds: [] };
   },
   // The echo path advances the snapshot anchor for a real-user turn; the
@@ -132,6 +179,7 @@ interface FakeConversation {
     content: string;
     requestId: string;
     metadata?: Record<string, unknown>;
+    attachments?: Array<Record<string, unknown>>;
   }) => Promise<{ id: string }>;
   workingDir: string;
   addEventObserver: (observer: unknown) => () => void;
@@ -167,7 +215,12 @@ function makeFakeConversation(opts: {
   let clientCallback: ((msg: unknown) => Promise<void>) | undefined;
   let persistCount = 0;
   let lastPersistOpts:
-    | { content: string; requestId: string; metadata?: Record<string, unknown> }
+    | {
+        content: string;
+        requestId: string;
+        metadata?: Record<string, unknown>;
+        attachments?: Array<Record<string, unknown>>;
+      }
     | undefined;
   const conversation: FakeConversation = {
     conversationId: "conv-voice-bridge-test",
@@ -196,6 +249,14 @@ function makeFakeConversation(opts: {
     persistUserMessage: async (persistOpts) => {
       persistCount += 1;
       lastPersistOpts = persistOpts;
+      // The link rows the real persist writes, which is what makes an
+      // attachment a cleanup candidate when this message is deleted.
+      if (persistOpts.attachments && persistOpts.attachments.length > 0) {
+        messageAttachmentLinks.set(
+          `msg-${persistCount}`,
+          persistOpts.attachments.map((a) => a.id as string),
+        );
+      }
       // Recorded before `onPersist` so scripted persist FAILURES also
       // appear in the event stream — ordering tests need the losing
       // attempt visible.
@@ -496,6 +557,125 @@ describe("startVoiceTurn escalation-continuation persistence", () => {
   });
 });
 
+describe("startVoiceTurn camera-frame attachments", () => {
+  test("hydrates parked ids onto the turn's own user message", async () => {
+    // The live-voice session parks an ambient camera frame and hands the id
+    // over; the row it lands on is the one carrying the user's words, so the
+    // picture and the sentence about it are one message.
+    const fake = makeFakeConversation({ processing: false });
+    fakeConversation = fake.conversation;
+
+    await startVoiceTurn({
+      ...makeTurnOptions(),
+      content: "what is this",
+      attachments: ["att-frame-1"],
+    });
+
+    expect(fake.lastPersistOpts()?.attachments).toEqual([
+      {
+        id: "att-frame-1",
+        filename: "att-frame-1.png",
+        mimeType: "image/png",
+        data: "ZnJhbWU=",
+      },
+    ]);
+    // `UserMessageAttachment` carries no metadata of its own, so which of a
+    // row's attachments were ambient frames is recorded on the message.
+    expect(fake.lastPersistOpts()?.metadata).toMatchObject({
+      voiceSessionTurn: true,
+      sightFrameAttachmentIds: ["att-frame-1"],
+    });
+  });
+
+  test("an id that resolves to nothing costs the caller no turn", async () => {
+    const fake = makeFakeConversation({ processing: false });
+    fakeConversation = fake.conversation;
+
+    await startVoiceTurn({
+      ...makeTurnOptions(),
+      content: "what is this",
+      attachments: ["att-missing"],
+    });
+
+    expect(fake.persistCount()).toBe(1);
+    expect(fake.lastPersistOpts()).not.toHaveProperty("attachments");
+    expect(fake.lastPersistOpts()?.metadata).not.toHaveProperty(
+      "sightFrameAttachmentIds",
+    );
+  });
+
+  test("a discarded turn leaves its camera frame attachable again", async () => {
+    // The hold verdict rolls the speculative turn back and the session parks
+    // the id again for the replay. The rollback deletes the row, and the row
+    // was the attachment's only reference, so without the retention the
+    // cleanup takes the frame with it and the replayed utterance speaks
+    // without the picture the user is holding up, with nothing said.
+    resetCrudLog();
+    const fake = makeFakeConversation({ processing: false });
+    fakeConversation = fake.conversation;
+
+    const handle = await startVoiceTurn({
+      ...makeTurnOptions(),
+      content: "what is this",
+      attachments: ["att-frame-1"],
+    });
+    expect(fake.lastPersistOpts()?.attachments).toHaveLength(1);
+
+    await handle.discard?.();
+
+    // The replay: the same parked id, and the row it lands on still carries
+    // the frame.
+    await startVoiceTurn({
+      ...makeTurnOptions(),
+      content: "what is this",
+      attachments: ["att-frame-1"],
+    });
+
+    expect(fake.lastPersistOpts()?.attachments).toEqual([
+      {
+        id: "att-frame-1",
+        filename: "att-frame-1.png",
+        mimeType: "image/png",
+        data: "ZnJhbWU=",
+      },
+    ]);
+    expect(fake.lastPersistOpts()?.metadata).toMatchObject({
+      sightFrameAttachmentIds: ["att-frame-1"],
+    });
+    // The rollback asked for exactly the ids its own row linked.
+    expect(crudLog.retained).toEqual([
+      { messageId: "msg-1", ids: ["att-frame-1"] },
+    ]);
+  });
+
+  test("a discard with no parked frame retains nothing", async () => {
+    resetCrudLog();
+    const fake = makeFakeConversation({ processing: false });
+    fakeConversation = fake.conversation;
+
+    const handle = await startVoiceTurn({
+      ...makeTurnOptions(),
+      content: "what is this",
+    });
+    await handle.discard?.();
+
+    expect(crudLog.deletes).toEqual(["msg-1"]);
+    expect(crudLog.retained).toEqual([{ messageId: "msg-1", ids: [] }]);
+  });
+
+  test("a turn with no parked frame persists exactly as before", async () => {
+    const fake = makeFakeConversation({ processing: false });
+    fakeConversation = fake.conversation;
+
+    await startVoiceTurn({ ...makeTurnOptions(), content: "what is this" });
+
+    expect(fake.lastPersistOpts()).not.toHaveProperty("attachments");
+    expect(fake.lastPersistOpts()?.metadata).toEqual({
+      voiceSessionTurn: true,
+    });
+  });
+});
+
 describe("startVoiceTurn hiddenSyntheticPrompt", () => {
   // A caller whose internal instruction is composed per call carries no
   // sentinel for the content comparisons to recognize, so it declares itself.

package/src/calls/guardian-action-sweep.ts

@@ -6,6 +6,8 @@
  * channels (telegram, slack) get a direct channel reply.
  */
 
+import { DELIVERY_STATUS } from "@vellumai/gateway-client";
+
 import { addMessage } from "../persistence/conversation-crud.js";
 import { deliverChannelReply } from "../runtime/gateway-client.js";
 import { composeGuardianActionMessageGenerative } from "../runtime/guardian-action-message-composer.js";
@@ -35,7 +37,10 @@ export async function sendGuardianExpiryNotices(
   assistantId: string,
 ): Promise<void> {
   for (const delivery of deliveries) {
-    if (delivery.status !== "sent" && delivery.status !== "pending") {
+    if (
+      delivery.status !== DELIVERY_STATUS.sent &&
+      delivery.status !== DELIVERY_STATUS.pending
+    ) {
       continue;
     }
 

package/src/calls/voice-session-bridge.ts

@@ -28,6 +28,7 @@ import { CONVERSATION_BUSY_MESSAGE } from "../daemon/conversation-messaging.js";
 import { resolveChannelCapabilities } from "../daemon/conversation-runtime-assembly.js";
 import { getOrCreateConversation } from "../daemon/conversation-store.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
+import { resolveAttachmentsForPersist } from "../persistence/attachments-store.js";
 import {
   deleteMessageById,
   getMessageById,
@@ -323,6 +324,20 @@ export interface VoiceTurnOptions {
   };
   /** Per-turn control prompt. Undefined uses the phone prompt; null disables it. */
   voiceControlPrompt?: string | null;
+  /**
+   * Ids of already-uploaded attachments to hang on this turn's persisted user
+   * message, hydrated here into the shape the message stores.
+   *
+   * Filled by the live-voice session from the camera frame a client parked on
+   * it (`attach_frame`), which is why these are ambient rather than chosen:
+   * they ride the turn's own user message so the picture and the words about it
+   * are one message, and so the media survives a context-overflow retry, which
+   * preserves it only on the newest user message.
+   *
+   * Ids that resolve to nothing are dropped: an unresolvable frame must not
+   * cost the caller their turn.
+   */
+  attachments?: readonly string[];
   /** The transcribed caller utterance or synthetic marker. */
   content: string;
   /** Assistant scope for multi-assistant channels. */
@@ -1023,9 +1038,20 @@ export async function startVoiceTurn(
 
   const requestId = uuidv7();
   const turnId = crypto.randomUUID();
+  // Ids this turn's row actually links, read back by `discardFn` so a rollback
+  // does not take the attachments down with the row.
+  let linkedAttachmentIds: string[] = [];
   const persistTurnUserMessage = async (): Promise<string> => {
+    // Resolved inside the persist, not once outside it, so the retry after a
+    // lost lock race stores exactly what the first attempt would have.
+    const turnAttachments =
+      opts.attachments && opts.attachments.length > 0
+        ? resolveAttachmentsForPersist([...opts.attachments])
+        : [];
+    linkedAttachmentIds = turnAttachments.map((a) => a.id);
     const persistResult = await conversation.persistUserMessage({
       content: persistedContent,
+      ...(turnAttachments.length > 0 ? { attachments: turnAttachments } : {}),
       requestId,
       metadata: {
         // Durable "this turn came from an open voice session" marker; see
@@ -1069,6 +1095,14 @@ export async function startVoiceTurn(
               },
             }
           : {}),
+        // Names which of the row's attachments arrived as ambient camera
+        // frames rather than files the user picked, so retention can treat
+        // them differently. `UserMessageAttachment` carries no metadata of its
+        // own, so the marking lives on the message and refers to the
+        // attachments by id.
+        ...(turnAttachments.length > 0
+          ? { sightFrameAttachmentIds: turnAttachments.map((a) => a.id) }
+          : {}),
       },
     });
     return persistResult.id;
@@ -1865,7 +1899,18 @@ export async function startVoiceTurn(
       // Same rollback pattern as the pointer-turn runner: delete the row,
       // then rebuild in-memory history from the clean DB (a plain pop is
       // fragile against concurrent compaction reassigning the array).
-      deleteMessageById(messageId);
+      //
+      // The row's own attachments are exempted from the orphan cleanup. A
+      // discard unwinds the turn as though it never ran, so an ambient camera
+      // frame goes back to being uploaded-but-unsent, which is exactly what
+      // the live-voice session's parked slot expects to find when the held
+      // utterance is replayed. Collecting it here would delete the row and
+      // the bytes, and the replay would silently speak without the picture.
+      deleteMessageById(messageId, {
+        ...(linkedAttachmentIds.length > 0
+          ? { retainAttachmentIds: linkedAttachmentIds }
+          : {}),
+      });
       await conversation.loadFromDb();
       publishConversationMessagesChanged(opts.conversationId);
     } catch (err) {

package/src/channels/__tests__/gateway-guardian-requests.test.ts

@@ -524,30 +524,30 @@ describe("expiry lifecycle", () => {
     ]);
   });
 
-  test("sweepExpiredGuardianRequests passes now and returns the expired rows", async () => {
-    const expiredRow = makeWireRequest({ status: "expired" });
-    ipcResponse = { expired: [expiredRow] };
-    expect(
-      await client.sweepExpiredGuardianRequests(1_700_000_500_000),
-    ).toEqual([expiredRow]);
+  test("listExpiredPendingGuardianRequests passes the limit and returns pending rows", async () => {
+    const staleRow = makeWireRequest({ status: "pending" });
+    ipcResponse = [staleRow];
+    expect(await client.listExpiredPendingGuardianRequests(50)).toEqual([
+      staleRow,
+    ]);
     expect(ipcCalls).toEqual([
       {
-        method: "guardian_requests_sweep_expired",
-        params: { now: 1_700_000_500_000 },
+        method: "guardian_requests_list_expired_pending",
+        params: { limit: 50 },
       },
     ]);
   });
 
-  test("sweeps throw on transport failure and malformed responses", async () => {
+  test("the expired-pending list throws on transport failure and malformed responses", async () => {
     ipcError = new Error("gateway unavailable");
-    await expect(client.sweepExpiredGuardianRequests()).rejects.toThrow(
+    await expect(client.listExpiredPendingGuardianRequests()).rejects.toThrow(
       "gateway unavailable",
     );
 
     ipcError = null;
     ipcResponse = { expired: 3 };
-    await expect(client.sweepExpiredGuardianRequests()).rejects.toThrow(
-      "guardian_requests_sweep_expired",
+    await expect(client.listExpiredPendingGuardianRequests()).rejects.toThrow(
+      "guardian_requests_list_expired_pending",
     );
   });
 });
@@ -631,11 +631,7 @@ describe("isGuardianRequestInScopeOrFalse", () => {
   test("returns the gateway scope verdict", async () => {
     ipcResponse = { inScope: true };
     expect(
-      await client.isGuardianRequestInScopeOrFalse(
-        "req-1",
-        "conv-1",
-        "telegram",
-      ),
+      await client.isGuardianRequestInScopeOrFalse("req-1", "conv-1"),
     ).toBe(true);
     expect(ipcCalls).toEqual([
       {
@@ -643,7 +639,6 @@ describe("isGuardianRequestInScopeOrFalse", () => {
         params: {
           requestId: "req-1",
           conversationId: "conv-1",
-          channel: "telegram",
         },
       },
     ]);

package/src/channels/gateway-guardian-requests.ts

@@ -42,7 +42,6 @@ import {
   type GuardianRequestWire,
   type ListGuardianRequestsIpcParams,
   type ListPendingGuardianRequestsByDestinationIpcParams,
-  SweepExpiredGuardianRequestsIpcResponseSchema,
   type UpdateGuardianRequestDeliveryIpcParams,
 } from "@vellumai/gateway-client";
 import type { ZodType } from "zod";
@@ -158,7 +157,7 @@ export const getGuardianRequestByCodeOrNull = degradeOnFailure(
 );
 
 /** List guardian requests matching the filters. Throws on transport failure. */
-async function listGuardianRequests(
+export async function listGuardianRequests(
   filters: ListGuardianRequestsIpcParams = {},
 ): Promise<GuardianRequestWire[]> {
   return callGateway(
@@ -210,9 +209,10 @@ export async function expireGuardianRequest(id: string): Promise<void> {
 
 /**
  * Daemon-boot expiry: interaction-bound kinds die with the daemon's
- * in-memory pendingInteractions map, plus persistent kinds already past
- * `expiresAt`. Returns the expired count. Throws on any failure
- * (fail-closed).
+ * in-memory pendingInteractions map. Persistent kinds are never touched
+ * here, whatever their deadline; their expiry belongs to the sweep, whose
+ * per-request confirmation keeps the fan-out recoverable. Returns the
+ * expired count. Throws on any failure (fail-closed).
  */
 export async function expireInteractionBoundGuardianRequests(): Promise<number> {
   const response = await callGateway(
@@ -224,19 +224,21 @@ export async function expireInteractionBoundGuardianRequests(): Promise<number>
 }
 
 /**
- * Sweep persistent requests past their `expiresAt` (gateway CAS-expires;
- * `now` defaults gateway-side). Returns the expired rows so the daemon fan-out
- * needs no follow-up read. Throws on any failure (fail-closed).
+ * Bounded, read-only list of pending requests past their `expiresAt`,
+ * oldest deadline first. Rows stay pending (and so stay listed) until the
+ * sweep has run their expiry side effects and confirmed each with
+ * `expireGuardianRequest`, which is what makes the fan-out recoverable
+ * from state after a lost response or a crash. Throws on any failure
+ * (fail-closed).
  */
-export async function sweepExpiredGuardianRequests(
-  now?: number,
+export async function listExpiredPendingGuardianRequests(
+  limit?: number,
 ): Promise<GuardianRequestWire[]> {
-  const response = await callGateway(
-    GUARDIAN_REQUESTS_IPC_METHODS.sweepExpired,
-    { now },
-    SweepExpiredGuardianRequestsIpcResponseSchema,
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.listExpiredPending,
+    { limit },
+    GuardianRequestListIpcResponseSchema,
   );
-  return response.expired;
 }
 
 /**
@@ -281,6 +283,24 @@ export const listGuardianRequestDeliveriesOrEmpty = degradeOnFailure(
   [],
 );
 
+/**
+ * Every delivery row addressed to one channel-native chat, across all
+ * requests. Transcript importers use the recorded message ids to
+ * recognize guardian card messages as delivery projections. Throws on
+ * transport failure so callers can fail safe instead of importing a
+ * card as conversation content.
+ */
+export async function listGuardianRequestDeliveriesByChat(
+  channel: string,
+  chatId: string,
+): Promise<GuardianRequestDeliveryWire[]> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.listDeliveriesByChat,
+    { channel, chatId },
+    GuardianRequestDeliveryListIpcResponseSchema,
+  );
+}
+
 /**
  * Reaction routing: the pending request whose delivered card is the
  * reacted-to message. Throws on transport failure.
@@ -347,17 +367,16 @@ export const listPendingRequestsByScopeOrEmpty = degradeOnFailure(
 
 /**
  * Is a decision from this conversation allowed for the request (source
- * match, or delivery match optionally narrowed by `channel`)? Throws on
+ * match, or delivery match on any channel's paired conversation)? Throws on
  * transport failure.
  */
 async function isGuardianRequestInScope(
   requestId: string,
   conversationId: string,
-  channel?: string,
 ): Promise<boolean> {
   const response = await callGateway(
     GUARDIAN_REQUESTS_IPC_METHODS.inScope,
-    { requestId, conversationId, channel },
+    { requestId, conversationId },
     GuardianRequestInScopeIpcResponseSchema,
   );
   return response.inScope;