@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/ipc/assistant-server.ts

@@ -28,13 +28,14 @@
  * back to a shorter deterministic path so CLI commands can still connect.
  */
 
-import { existsSync, unlinkSync } from "node:fs";
 import { createServer, type Server, type Socket } from "node:net";
 
 import {
   ensureSocketDir,
   type IpcEnvelope,
   IpcFrameReader,
+  ipcListenOptions,
+  removeIpcEndpointFile,
   SocketWatchdog,
   writeLegacyMessage,
   writeMessage,
@@ -60,6 +61,7 @@ import { CONTACTS_INFO_IPC_METHODS } from "./routes/contacts-info-ipc-routes.js"
 import { CONTACTS_MIRROR_IPC_METHODS } from "./routes/contacts-mirror-ipc-routes.js";
 import { CONVERSATION_SYNC_IPC_METHODS } from "./routes/conversation-sync-ipc-routes.js";
 import { type DbProxyParams, handleDbProxy } from "./routes/db-proxy.js";
+import { DOCUMENTS_SYNC_IPC_METHODS } from "./routes/documents-sync-ipc-routes.js";
 import { EVENTS_IPC_METHODS } from "./routes/events-ipc-routes.js";
 import { GUARDIAN_LABEL_IPC_METHODS } from "./routes/guardian-label-ipc-routes.js";
 import { INVITE_IPC_METHODS } from "./routes/invite-ipc-routes.js";
@@ -215,6 +217,7 @@ export class AssistantIpcServer {
       CONTACTS_MIRROR_IPC_METHODS,
       GUARDIAN_LABEL_IPC_METHODS,
       CONVERSATION_SYNC_IPC_METHODS,
+      DOCUMENTS_SYNC_IPC_METHODS,
       EVENTS_IPC_METHODS,
     ]) {
       for (const [operationId, handler] of Object.entries(methodMap)) {
@@ -257,8 +260,18 @@ export class AssistantIpcServer {
     await ensureSocketPathFree(this.socketPath);
 
     this.server = this.createListeningServer();
-    this.server.listen(this.socketPath, () => {
-      log.info({ path: this.socketPath }, "Assistant IPC server listening");
+    await new Promise<void>((resolve, reject) => {
+      const server = this.server!;
+      const onError = (err: Error): void => {
+        this.server = null;
+        reject(err);
+      };
+      server.once("error", onError);
+      server.listen(ipcListenOptions(this.socketPath), () => {
+        server.off("error", onError);
+        log.info({ path: this.socketPath }, "Assistant IPC server listening");
+        resolve();
+      });
     });
 
     this.watchdog.start();
@@ -290,13 +303,7 @@ export class AssistantIpcServer {
       this.server = null;
     }
 
-    if (existsSync(this.socketPath)) {
-      try {
-        unlinkSync(this.socketPath);
-      } catch {
-        // Ignore
-      }
-    }
+    removeIpcEndpointFile(this.socketPath);
   }
 
   /** Get the socket path (for diagnostics). */

package/src/ipc/cli-client.ts

@@ -58,6 +58,15 @@ export interface CliIpcCallResult<T = unknown> {
    * when the originating daemon-side error carried a `details` field.
    */
   errorDetails?: unknown;
+  /**
+   * Set when the call was abandoned because `timeoutMs` elapsed with no
+   * response. Distinct from every other `ok: false` shape: the request WAS
+   * delivered and the daemon may still be executing it — closing the client
+   * socket does not abort the handler. Callers that would otherwise retry a
+   * transport failure must not retry this one until the original can no
+   * longer be in flight.
+   */
+  timedOut?: boolean;
 }
 
 /**
@@ -178,7 +187,7 @@ export async function cliIpcCall<T = unknown>(
           { method, socketPath, timeoutMs: callTimeoutMs },
           "CLI IPC call timed out waiting for response",
         );
-        finish({ ok: false, error: "Request timed out" });
+        finish({ ok: false, error: "Request timed out", timedOut: true });
       }, callTimeoutMs);
 
       socket.on("data", (chunk) => {

package/src/ipc/routes/__tests__/documents-sync-ipc-routes.test.ts

@@ -0,0 +1,56 @@
+/**
+ * The daemon-side handler for the worker → daemon documents-changed hand-off.
+ * A sidecar worker's own hub has no SSE subscriber, so it asks the daemon to
+ * republish the invalidation where clients actually observe it.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+const publishCalls: Array<string | undefined> = [];
+
+mock.module("../../../runtime/sync/resource-sync-events.js", () => ({
+  publishDocumentsChanged: (originClientId?: string) => {
+    publishCalls.push(originClientId);
+  },
+}));
+
+import { DB_MIGRATION_READINESS_EXEMPT_OPERATIONS } from "../../../daemon/daemon-readiness.js";
+import { NOTIFY_DOCUMENTS_CHANGED_IPC_METHOD } from "../../../runtime/sync/worker-daemon-notify.js";
+import {
+  DOCUMENTS_SYNC_IPC_METHODS,
+  handleNotifyDocumentsChanged,
+} from "../documents-sync-ipc-routes.js";
+
+describe("documents-sync IPC route", () => {
+  beforeEach(() => {
+    publishCalls.length = 0;
+  });
+
+  test("republishes the documents-changed invalidation on the daemon", () => {
+    const result = handleNotifyDocumentsChanged({ body: {} });
+
+    expect(result).toEqual({ ok: true });
+    expect(publishCalls).toEqual([undefined]);
+  });
+
+  test("carries no origin client id, so no client suppresses it", () => {
+    // The hand-off comes from a background turn with no originating client.
+    handleNotifyDocumentsChanged({ body: {} });
+
+    expect(publishCalls[0]).toBeUndefined();
+  });
+
+  test("is reachable on the IPC surface under the shared method name", () => {
+    expect(
+      typeof DOCUMENTS_SYNC_IPC_METHODS[NOTIFY_DOCUMENTS_CHANGED_IPC_METHOD],
+    ).toBe("function");
+  });
+
+  test("is DB-migration readiness gated (absent from the exempt set)", () => {
+    expect(
+      DB_MIGRATION_READINESS_EXEMPT_OPERATIONS.has(
+        NOTIFY_DOCUMENTS_CHANGED_IPC_METHOD,
+      ),
+    ).toBe(false);
+  });
+});

package/src/ipc/routes/documents-sync-ipc-routes.ts

@@ -0,0 +1,42 @@
+/**
+ * IPC-only route the sidecar workers (schedule, memory) call after a turn
+ * changed a document.
+ *
+ * Workers disable SSE seq stamping (`disableStreamSeqStamping`) so the daemon
+ * is the sole seq authority, and the SSE subscribers live in the daemon too. A
+ * worker that published `documents:list` on its own hub would reach nobody, so
+ * a scheduled or background turn's document edit would stay invisible: the
+ * conversation assets pill and the Library would keep serving their cached
+ * list. That is precisely the case the changed-document surfacing exists for.
+ *
+ * This route runs the publish on the daemon instead, where real subscribers
+ * observe it. The hand-off carries no originating client, so nothing suppresses
+ * the broadcast as its own echo.
+ *
+ * IPC-only: registered directly on the assistant IPC server (see
+ * `assistant-server.ts`), never in the shared `ROUTES` array. The handler
+ * touches no database, but the IPC server's uniform DB-migration gate still
+ * applies (the method is not exempt); the worker's call is best-effort and
+ * tolerates that.
+ */
+
+import type { RouteHandlerArgs } from "../../runtime/routes/types.js";
+import { publishDocumentsChanged } from "../../runtime/sync/resource-sync-events.js";
+import { NOTIFY_DOCUMENTS_CHANGED_IPC_METHOD } from "../../runtime/sync/worker-daemon-notify.js";
+
+/** Republish a worker's documents-changed invalidation to daemon subscribers. */
+export function handleNotifyDocumentsChanged(_args: RouteHandlerArgs) {
+  publishDocumentsChanged();
+  return { ok: true };
+}
+
+/**
+ * IPC-only documents-sync methods, keyed by operationId. Registered directly on
+ * the assistant IPC server (see `assistant-server.ts`).
+ */
+export const DOCUMENTS_SYNC_IPC_METHODS: Record<
+  string,
+  (args: RouteHandlerArgs) => unknown
+> = {
+  [NOTIFY_DOCUMENTS_CHANGED_IPC_METHOD]: handleNotifyDocumentsChanged,
+};

package/src/ipc/socket-cleanup.ts

@@ -7,9 +7,14 @@
  * inode, leaving two daemons in conflict with no error.
  */
 
-import { existsSync, unlinkSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { connect } from "node:net";
 
+import {
+  isNamedPipePath,
+  removeIpcEndpointFile,
+} from "@vellumai/ipc-server-utils";
+
 /**
  * Maximum time to wait for the probe `connect()` to settle before declaring
  * the path occupied. Without a bound, a hung process holding the socket would
@@ -44,7 +49,8 @@ function makeAddrInUseError(message: string): NodeJS.ErrnoException {
  *   - Any other socket error → propagate.
  */
 export async function ensureSocketPathFree(socketPath: string): Promise<void> {
-  if (!existsSync(socketPath)) {
+  const namedPipe = isNamedPipePath(socketPath);
+  if (!namedPipe && !existsSync(socketPath)) {
     return;
   }
   await new Promise<void>((resolve, reject) => {
@@ -81,11 +87,7 @@ export async function ensureSocketPathFree(socketPath: string): Promise<void> {
     client.once("error", (err: NodeJS.ErrnoException) => {
       if (err.code === "ECONNREFUSED" || err.code === "ENOENT") {
         settle(() => {
-          try {
-            unlinkSync(socketPath);
-          } catch {
-            // Ignore — may already be gone
-          }
+          removeIpcEndpointFile(socketPath);
           resolve();
         });
       } else {

package/src/ipc/socket-path.ts

@@ -1,106 +1,14 @@
-import { createHash } from "node:crypto";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { resolveIpcEndpoint } from "@vellumai/ipc-server-utils";
 
 import { getWorkspaceDir } from "../util/platform.js";
 
-const DARWIN_UNIX_SOCKET_MAX_PATH_BYTES = 103;
-const DEFAULT_UNIX_SOCKET_MAX_PATH_BYTES = 107;
-const IPC_TMP_DIR_NAME = "vellum-ipc";
-
-export type IpcSocketPathSource =
-  | "env-override"
-  | "workspace"
-  | "tmp-hash"
-  | "tmp-short-hash";
-
-export interface IpcSocketPathResolution {
+export function resolveIpcSocketPath(socketName: string): {
   path: string;
-  source: IpcSocketPathSource;
-}
-
-function getUnixSocketMaxPathBytes(): number {
-  return process.platform === "darwin"
-    ? DARWIN_UNIX_SOCKET_MAX_PATH_BYTES
-    : DEFAULT_UNIX_SOCKET_MAX_PATH_BYTES;
-}
-
-function isPathWithinSocketLimit(path: string, maxPathBytes: number): boolean {
-  return Buffer.byteLength(path, "utf8") <= maxPathBytes;
-}
-
-/**
- * Derive the env var name and socket filename from a socket name.
- *
- * Examples (hyphens in the name become underscores in the env var):
- *   "gateway"   → { envVar: "GATEWAY_IPC_SOCKET_DIR", fileName: "gateway.sock" }
- *   "assistant" → { envVar: "ASSISTANT_IPC_SOCKET_DIR", fileName: "assistant.sock" }
- */
-function deriveSocketNames(socketName: string): {
-  envVar: string;
-  fileName: string;
+  source: string;
 } {
-  const envVar = `${socketName.toUpperCase().replace(/-/g, "_")}_IPC_SOCKET_DIR`;
-  const fileName = `${socketName}.sock`;
-  return { envVar, fileName };
-}
-
-/**
- * Resolve the path to an IPC socket file.
- *
- * Resolution order:
- *   1. `${SOCKET_NAME}_IPC_SOCKET_DIR` env var override — used in
- *      containerized deployments (emptyDir volume) and by hatch on macOS
- *      when the workspace path would exceed the AF_UNIX limit.
- *   2. `{workspaceDir}/{socketName}.sock` — default for local dev.
- *   3. tmpdir fallback — if the workspace path exceeds the platform's
- *      AF_UNIX path limit (103 bytes on macOS, 107 on Linux).
- */
-export function resolveIpcSocketPath(
-  socketName: string,
-): IpcSocketPathResolution {
-  const workspaceDir = getWorkspaceDir();
-  const { envVar, fileName } = deriveSocketNames(socketName);
-
-  // Explicit override via env var.
-  const envSocketDir = process.env[envVar]?.trim();
-  if (envSocketDir) {
-    return {
-      path: join(envSocketDir, fileName),
-      source: "env-override",
-    };
-  }
-
-  const maxPathBytes = getUnixSocketMaxPathBytes();
-  const workspacePath = join(workspaceDir, fileName);
-
-  if (isPathWithinSocketLimit(workspacePath, maxPathBytes)) {
-    return {
-      path: workspacePath,
-      source: "workspace",
-    };
-  }
-
-  // Workspace path exceeds AF_UNIX limit — fall back to tmpdir.
-  const hash = createHash("sha256")
-    .update(workspacePath)
-    .digest("hex")
-    .slice(0, 12);
-  const hashedPath = join(tmpdir(), IPC_TMP_DIR_NAME, `${hash}-${fileName}`);
-  if (isPathWithinSocketLimit(hashedPath, maxPathBytes)) {
-    return {
-      path: hashedPath,
-      source: "tmp-hash",
-    };
-  }
-
-  return {
-    path: join(tmpdir(), `v-${hash}.sock`),
-    source: "tmp-short-hash",
-  };
+  return resolveIpcEndpoint(socketName, { workspaceDir: getWorkspaceDir() });
 }
 
-/** Shorthand — resolves the assistant CLI IPC socket path. */
 export function getAssistantSocketPath(): string {
   return resolveIpcSocketPath("assistant").path;
 }

package/src/live-voice/__tests__/live-voice-archive.test.ts

@@ -96,7 +96,7 @@ describe("live voice audio archive", () => {
     const { message } = await createMessage("user");
     const audio = Buffer.from("user audio bytes");
 
-    const result = archiveLiveVoiceUserUtteranceAudio({
+    const result = await archiveLiveVoiceUserUtteranceAudio({
       messageId: message.id,
       sessionId: "session-123",
       turnId: "turn-abc",
@@ -148,7 +148,7 @@ describe("live voice audio archive", () => {
     const audio = Buffer.from("assistant audio bytes");
     writeFileSync(sourcePath, audio);
 
-    const result = archiveLiveVoiceAssistantResponseAudio({
+    const result = await archiveLiveVoiceAssistantResponseAudio({
       messageId: message.id,
       sessionId: "session-456",
       turnId: "turn-def",
@@ -202,7 +202,7 @@ describe("live voice audio archive", () => {
   test("links user utterance audio to a persisted user message id", async () => {
     const { message } = await createMessage("user");
 
-    const result = linkLiveVoiceUserUtteranceAudioToMessage({
+    const result = await linkLiveVoiceUserUtteranceAudioToMessage({
       messageId: message.id,
       sessionId: "session-user-link",
       turnId: "turn-user-link",
@@ -228,7 +228,7 @@ describe("live voice audio archive", () => {
   test("links assistant response audio when the assistant message id is available", async () => {
     const { message } = await createMessage("assistant");
 
-    const result = linkLiveVoiceAssistantResponseAudioToMessage({
+    const result = await linkLiveVoiceAssistantResponseAudioToMessage({
       messageId: message.id,
       sessionId: "session-assistant-link",
       turnId: "turn-assistant-link",
@@ -254,8 +254,8 @@ describe("live voice audio archive", () => {
     expect(getLiveVoiceArtifacts(message.id)).toEqual([result.artifact]);
   });
 
-  test("returns an unlinked result when the assistant message id is unavailable", () => {
-    const result = linkLiveVoiceAssistantResponseAudioToMessage({
+  test("returns an unlinked result when the assistant message id is unavailable", async () => {
+    const result = await linkLiveVoiceAssistantResponseAudioToMessage({
       messageId: undefined,
       sessionId: "session-assistant-unlinked",
       turnId: "turn-assistant-unlinked",
@@ -283,7 +283,7 @@ describe("live voice audio archive", () => {
   test("is idempotent for the session turn role key", async () => {
     const { message } = await createMessage("user");
 
-    const first = archiveLiveVoiceAudioArtifact({
+    const first = await archiveLiveVoiceAudioArtifact({
       messageId: message.id,
       sessionId: "session-repeat",
       turnId: "turn-repeat",
@@ -295,7 +295,7 @@ describe("live voice audio archive", () => {
         dataBase64: Buffer.from("first audio").toString("base64"),
       },
     });
-    const second = archiveLiveVoiceAudioArtifact({
+    const second = await archiveLiveVoiceAudioArtifact({
       messageId: message.id,
       sessionId: "session-repeat",
       turnId: "turn-repeat",
@@ -320,7 +320,7 @@ describe("live voice audio archive", () => {
       "first audio",
     );
 
-    const assistantResult = archiveLiveVoiceAudioArtifact({
+    const assistantResult = await archiveLiveVoiceAudioArtifact({
       messageId: message.id,
       sessionId: "session-repeat",
       turnId: "turn-repeat",
@@ -337,7 +337,7 @@ describe("live voice audio archive", () => {
 
   test("restores metadata idempotency from the deterministic attachment filename", async () => {
     const { message } = await createMessage("assistant");
-    const first = archiveLiveVoiceAssistantResponseAudio({
+    const first = await archiveLiveVoiceAssistantResponseAudio({
       messageId: message.id,
       sessionId: "session-crash",
       turnId: "turn-crash",
@@ -360,7 +360,7 @@ describe("live voice audio archive", () => {
       message.id,
     );
 
-    const second = archiveLiveVoiceAssistantResponseAudio({
+    const second = await archiveLiveVoiceAssistantResponseAudio({
       messageId: message.id,
       sessionId: "session-crash",
       turnId: "turn-crash",
@@ -408,7 +408,7 @@ describe("live voice audio archive", () => {
       },
     );
 
-    const archived = archiveLiveVoiceUserUtteranceAudio({
+    const archived = await archiveLiveVoiceUserUtteranceAudio({
       messageId: sourceMessage.id,
       sessionId: "session-artifact-link",
       turnId: "turn-artifact-link",
@@ -452,7 +452,7 @@ describe("live voice audio archive", () => {
   test("returns typed warnings for non-fatal archive failures", async () => {
     const { message } = await createMessage("user");
 
-    const missingFile = archiveLiveVoiceUserUtteranceAudio({
+    const missingFile = await archiveLiveVoiceUserUtteranceAudio({
       messageId: message.id,
       sessionId: "session-warning",
       turnId: "turn-warning",
@@ -470,7 +470,7 @@ describe("live voice audio archive", () => {
       },
     });
 
-    const unsupportedMime = archiveLiveVoiceUserUtteranceAudio({
+    const unsupportedMime = await archiveLiveVoiceUserUtteranceAudio({
       messageId: message.id,
       sessionId: "session-warning",
       turnId: "turn-warning-2",
@@ -488,7 +488,7 @@ describe("live voice audio archive", () => {
       },
     });
 
-    const missingMessage = archiveLiveVoiceUserUtteranceAudio({
+    const missingMessage = await archiveLiveVoiceUserUtteranceAudio({
       messageId: "missing-message",
       sessionId: "session-warning",
       turnId: "turn-warning-3",
@@ -509,7 +509,7 @@ describe("live voice audio archive", () => {
   test("keeps archive metadata scoped to allowed live voice fields", async () => {
     const { message } = await createMessage("assistant");
 
-    const result = archiveLiveVoiceAssistantResponseAudio({
+    const result = await archiveLiveVoiceAssistantResponseAudio({
       messageId: message.id,
       sessionId: "session-metadata",
       turnId: "turn-metadata",

package/src/live-voice/__tests__/live-voice-attach-image.test.ts

@@ -0,0 +1,209 @@
+/**
+ * Photos taken mid-call (the voice room's camera).
+ *
+ * The behaviour under test is the parking rule: an `attach_image` frame does
+ * not dispatch anything, it waits for the next turn and rides that turn's own
+ * user message. That is what makes a bare "what's this?" resolve against the
+ * picture instead of producing one turn about the image racing another about
+ * the words.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+
+import type { VoiceTurnOptions } from "../../calls/voice-session-bridge.js";
+import type {
+  StreamingTranscriber,
+  SttStreamServerEvent,
+} from "../../stt/types.js";
+import {
+  LiveVoiceSession,
+  type LiveVoiceTurnStarter,
+} from "../live-voice-session.js";
+import type { LiveVoiceSessionFactoryContext } from "../live-voice-session-manager.js";
+import {
+  createLiveVoiceServerFrameSequencer,
+  type LiveVoiceClientStartFrame,
+  type LiveVoiceServerFrame,
+  validateLiveVoiceClientFrame,
+} from "../protocol.js";
+
+const START_FRAME = {
+  type: "start",
+  conversationId: "conversation-123",
+  audio: { mimeType: "audio/pcm", sampleRate: 24_000, channels: 1 },
+} as const satisfies LiveVoiceClientStartFrame;
+
+class MockStreamingTranscriber implements StreamingTranscriber {
+  readonly providerId = "deepgram" as const;
+  readonly boundaryId = "daemon-streaming" as const;
+  private onEvent: ((event: SttStreamServerEvent) => void) | null = null;
+
+  async start(onEvent: (event: SttStreamServerEvent) => void): Promise<void> {
+    this.onEvent = onEvent;
+  }
+
+  sendAudio(): void {}
+
+  stop(): void {
+    this.emit({ type: "closed" });
+  }
+
+  emit(event: SttStreamServerEvent): void {
+    this.onEvent?.(event);
+  }
+}
+
+function createSessionHarness() {
+  const sequencer = createLiveVoiceServerFrameSequencer();
+  const frames: LiveVoiceServerFrame[] = [];
+  const context: LiveVoiceSessionFactoryContext = {
+    sessionId: "session-123",
+    startFrame: START_FRAME,
+    sendFrame: mock(async (payload) => {
+      const frame = sequencer.next(payload);
+      frames.push(frame);
+      return frame;
+    }),
+  };
+
+  const transcriber = new MockStreamingTranscriber();
+  const startVoiceTurn: LiveVoiceTurnStarter = mock(
+    async (_options: VoiceTurnOptions) => ({
+      turnId: "bridge-turn-1",
+      abort: mock(),
+    }),
+  );
+
+  const session = new LiveVoiceSession(context, {
+    resolveTranscriber: mock(async () => transcriber),
+    startVoiceTurn,
+    createTurnId: () => "live-turn-1",
+    emitMetrics: false,
+  });
+
+  return { frames, session, startVoiceTurn, transcriber };
+}
+
+/** Drive one utterance to a dispatched assistant turn. */
+async function speakAndRelease(
+  harness: Awaited<ReturnType<typeof createSessionHarness>>,
+  text: string,
+): Promise<void> {
+  harness.transcriber.emit({ type: "final", text });
+  await harness.session.handleClientFrame({ type: "ptt_release" });
+  for (let attempt = 0; attempt < 40; attempt += 1) {
+    if (
+      (harness.startVoiceTurn as ReturnType<typeof mock>).mock.calls.length > 0
+    ) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+}
+
+function turnOptionsAt(
+  startVoiceTurn: LiveVoiceTurnStarter,
+  index: number,
+): VoiceTurnOptions | undefined {
+  return (startVoiceTurn as ReturnType<typeof mock>).mock.calls[index]?.[0] as
+    | VoiceTurnOptions
+    | undefined;
+}
+
+describe("live-voice attach_image frame", () => {
+  test("accepts a well-formed frame", () => {
+    const result = validateLiveVoiceClientFrame({
+      type: "attach_image",
+      attachmentId: "att-1",
+    });
+    expect(result).toEqual({
+      ok: true,
+      frame: { type: "attach_image", attachmentId: "att-1" },
+    });
+  });
+
+  test("rejects a missing attachmentId", () => {
+    const result = validateLiveVoiceClientFrame({ type: "attach_image" });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe("missing_required_field");
+      expect(result.error.field).toBe("attachmentId");
+    }
+  });
+
+  test("rejects an empty attachmentId", () => {
+    const result = validateLiveVoiceClientFrame({
+      type: "attach_image",
+      attachmentId: "",
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe("invalid_field");
+    }
+  });
+});
+
+describe("live-voice photos taken mid-call", () => {
+  test("a photo does not dispatch a turn of its own", async () => {
+    // The photo becomes its own user message via `persistLiveVoicePhoto`; no
+    // assistant turn runs for it. Dispatching one would answer the picture
+    // while the user is still saying the sentence it belongs to.
+    const harness = createSessionHarness();
+    await harness.session.start();
+
+    await harness.session.handleClientFrame({
+      type: "attach_image",
+      attachmentId: "att-1",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    expect(harness.startVoiceTurn).not.toHaveBeenCalled();
+  });
+
+  test("a spoken turn carries no attachments of its own", async () => {
+    // Photos reach the model through conversation history, not through the
+    // turn's options, which is what makes shutter-then-speak and
+    // speak-then-shutter behave identically.
+    const harness = createSessionHarness();
+    await harness.session.start();
+
+    await harness.session.handleClientFrame({
+      type: "attach_image",
+      attachmentId: "att-1",
+    });
+    await speakAndRelease(harness, "what's this");
+
+    const options = turnOptionsAt(harness.startVoiceTurn, 0) as
+      | (VoiceTurnOptions & { attachmentIds?: string[] })
+      | undefined;
+    expect(options?.content).toBe("what's this");
+    expect(options?.attachmentIds).toBeUndefined();
+  });
+
+  test("a photo that cannot be stored is reported to the client", async () => {
+    // `att-missing` resolves to nothing (no attachment row in this harness),
+    // so the persist fails. Silence would leave the user believing the
+    // assistant can see something it never received.
+    const harness = createSessionHarness();
+    await harness.session.start();
+    const before = harness.frames.length;
+
+    await harness.session.handleClientFrame({
+      type: "attach_image",
+      attachmentId: "att-missing",
+    });
+    for (let attempt = 0; attempt < 40; attempt += 1) {
+      if (harness.frames.length > before) {
+        break;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+
+    const error = harness.frames
+      .slice(before)
+      .find((frame) => frame.type === "error");
+    expect(error).toMatchObject({ type: "error", recoverable: true });
+    // The session survives it: one failed photo is not a failed call.
+    expect(harness.startVoiceTurn).not.toHaveBeenCalled();
+  });
+});