@vellumai/assistant 0.11.5 → 0.11.6-staging.1

package/src/inbound/tunnel-probe.ts

@@ -0,0 +1,261 @@
+/**
+ * Reachability probe for the public URL a tunnel exposes.
+ *
+ * A tunnel's public URL is recorded in the workspace config, but a recorded
+ * URL says nothing about whether anything still answers on it: the tunnel
+ * process can die, the nginx edge can stay up while the gateway behind it is
+ * down, and a URL can end up fronting a different assistant entirely. The
+ * probe asks the edge two questions at once, and the two answers carry very
+ * different weight:
+ *
+ *   - `GET /healthz` is the liveness verdict. Every ingress shape answers it:
+ *     the nginx edge proxies it to the gateway, and a tunnel pointed straight
+ *     at the gateway port serves it from the gateway itself. Anything but a
+ *     2xx means the URL is not usable at all, which is `unreachable`.
+ *   - `GET /assistant/__config` decides whether that live edge is one a device
+ *     can pair against. Only the nginx remote-web SPA edge serves it
+ *     (`buildRemoteWebIngressLocations` in `cli/src/lib/nginx-ingress.ts`),
+ *     and that is the same edge serving `/assistant/pair`, so an edge that
+ *     answers the config request with anything but that edge's own config is
+ *     an edge whose pair URL would 404. That is `unpairable`: alive, and no
+ *     use to a card whose whole job is pairing. A tunnel pointed straight at
+ *     the gateway, a bring-your-own HTTPS front that only proxies the gateway,
+ *     and a catch-all that answers every path with some JSON all land there.
+ *     A config request that gets no answer at all, because it lost the shared
+ *     deadline or the connection dropped under it, proves nothing either way,
+ *     and the live `/healthz` stands.
+ *
+ * The served config also carries the assistant's id, which is what separates
+ * `healthy` from `foreign`.
+ *
+ * Neither path is denylisted, so both are publicly reachable.
+ *
+ * The module takes a URL and an expected id and returns a verdict: it reads no
+ * config and knows nothing about workspace paths, which is what lets callers
+ * probe an arbitrary URL and lets tests run without network access.
+ */
+
+import {
+  normalizeHttpPublicBaseUrlWithoutTrailingSlash,
+  trimmedNonEmptyString,
+} from "@vellumai/service-contracts/ingress";
+
+import { isPlainObject } from "../util/object.js";
+import { truncate } from "../util/truncate.js";
+
+/**
+ * Verdict for one probe.
+ *
+ * `unpairable` means the edge answered the config request with something that
+ * is not the pairing edge's config, so it is alive without fronting the
+ * pairing app.
+ * `foreign` means the edge positively identified itself as a different
+ * assistant. Any case where either id is unknown is `healthy`: a config
+ * served by a CLI that predates the id, or a URL recorded before the id was
+ * saved, is version skew, not someone else's assistant.
+ */
+export type TunnelProbeResult =
+  | { kind: "healthy"; assistantId?: string; assistantName?: string }
+  | { kind: "unreachable"; detail: string }
+  | { kind: "unpairable"; detail?: string }
+  | { kind: "foreign"; assistantId?: string; assistantName?: string };
+
+const DEFAULT_TIMEOUT_MS = 4_000;
+
+/** Placeholder swapped in for the probed URL so `detail` stays URL-free. */
+const REDACTED_URL = "<url>";
+
+/** `detail` is rendered inline in a settings card, so it has to stay short. */
+const MAX_DETAIL_LENGTH = 120;
+
+/** Bound on the `cause` walk, so a self-referential chain cannot spin. */
+const MAX_CAUSE_DEPTH = 5;
+
+/** Wrappers fetch layers raise when the real reason sits one `cause` down. */
+const GENERIC_FETCH_MESSAGES = new Set(["fetch failed", "failed to fetch"]);
+
+/** Reported when the config path answers with a body that is not a config. */
+const UNREADABLE_CONFIG_DETAIL = "no assistant config served";
+
+/** Reported when a served body parses but is not the pairing edge's config. */
+const UNMARKED_CONFIG_DETAIL = "not a pairing edge config";
+
+/**
+ * Stamped into the served config by the nginx pairing edge and nothing else
+ * (`remoteWebIngressConfig` in `cli/src/lib/nginx-ingress.ts`), which makes it
+ * the marker that separates that edge from any other JSON a live URL serves.
+ */
+const PAIRING_EDGE_MODE = "remote-gateway";
+
+export async function probeTunnel(args: {
+  publicBaseUrl: string;
+  /** Id recorded when this URL was saved; omit to skip the identity check. */
+  expectedAssistantId?: string;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+}): Promise<TunnelProbeResult> {
+  if (args.publicBaseUrl.trim().length === 0) {
+    return { kind: "unreachable", detail: "no public base URL" };
+  }
+  // The same validation the config writers apply, so a value they would have
+  // rejected is named as malformed rather than handed to `fetch` and reported
+  // through whatever string that layer happens to produce.
+  const base = normalizeHttpPublicBaseUrlWithoutTrailingSlash(
+    args.publicBaseUrl,
+  );
+  if (base === undefined) {
+    return { kind: "unreachable", detail: "not an http(s) URL" };
+  }
+
+  const fetchImpl = args.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  // One deadline covers both requests: only an answered config request can
+  // demote a live edge, so a slow edge that answers `/healthz` and loses the
+  // config request to the same deadline keeps its liveness verdict.
+  const signal = AbortSignal.timeout(args.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  const [health, config] = await Promise.allSettled([
+    fetchImpl(`${base}/healthz`, { signal }),
+    fetchImpl(`${base}/assistant/__config`, { signal }),
+  ]);
+  const configResponse =
+    config.status === "fulfilled" ? config.value : undefined;
+
+  if (health.status === "rejected") {
+    await discardBody(configResponse);
+    return unreachable(describeError(health.reason), base);
+  }
+  // Liveness is the status line; the health body is never read.
+  await discardBody(health.value);
+  if (!health.value.ok) {
+    await discardBody(configResponse);
+    return unreachable(`HTTP ${health.value.status}`, base);
+  }
+
+  const served = await readServedConfig(configResponse);
+  if (served.kind === "notServed") {
+    return { kind: "unpairable", detail: served.detail };
+  }
+
+  const identity = served.kind === "served" ? served.config : {};
+  const expected = trimmedNonEmptyString(args.expectedAssistantId);
+  const isForeign =
+    expected !== undefined &&
+    identity.assistantId !== undefined &&
+    identity.assistantId !== expected;
+
+  return { kind: isForeign ? "foreign" : "healthy", ...identity };
+}
+
+/**
+ * Fetch layers vary in how much of the request they echo into an error
+ * message, and the caller already knows which URL it asked about.
+ */
+function unreachable(detail: string, base: string): TunnelProbeResult {
+  return {
+    kind: "unreachable",
+    detail: truncate(detail.replaceAll(base, REDACTED_URL), MAX_DETAIL_LENGTH),
+  };
+}
+
+/**
+ * An unread fetch body pins its socket until GC under Bun and undici, and the
+ * probe runs on every settings mount, resume, and manual refresh.
+ */
+async function discardBody(response: Response | undefined): Promise<void> {
+  try {
+    await response?.body?.cancel();
+  } catch {
+    /* best effort */
+  }
+}
+
+function isTimeoutError(error: unknown): boolean {
+  return (
+    isPlainObject(error) &&
+    (error.name === "TimeoutError" || error.name === "AbortError")
+  );
+}
+
+function isGenericFetchMessage(message: string): boolean {
+  return GENERIC_FETCH_MESSAGES.has(message.toLowerCase());
+}
+
+/**
+ * A dead tunnel surfaces as a generic wrapper ("fetch failed") whose `cause`
+ * carries the reason worth reading (`ECONNREFUSED`, `ENOTFOUND`), so walk the
+ * chain for a code, then for the first message that says something.
+ */
+function describeError(error: unknown): string {
+  let message: string | undefined;
+  let current: unknown = error;
+
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth += 1) {
+    if (!isPlainObject(current)) {
+      break;
+    }
+    if (isTimeoutError(current)) {
+      return "timeout";
+    }
+    const code = trimmedNonEmptyString(current.code);
+    if (code !== undefined) {
+      return code;
+    }
+    // A wrapper only holds the slot until a deeper level fills it.
+    if (message === undefined || isGenericFetchMessage(message)) {
+      message = trimmedNonEmptyString(current.message) ?? message;
+    }
+    current = current.cause;
+  }
+
+  return message ?? String(error);
+}
+
+interface ServedEdgeConfig {
+  assistantId?: string;
+  assistantName?: string;
+}
+
+/**
+ * What the config request settled: the identity the pairing edge reports, a
+ * positive "whatever is here does not serve the pairing app", or nothing.
+ */
+type ServedConfigReading =
+  | { kind: "unanswered" }
+  | { kind: "notServed"; detail: string }
+  | { kind: "served"; config: ServedEdgeConfig };
+
+/**
+ * A 2xx JSON object carrying the pairing edge's marker is that edge
+ * identifying itself, any other answer is an edge that does not serve the
+ * pairing app, and no answer is no evidence.
+ */
+async function readServedConfig(
+  response: Response | undefined,
+): Promise<ServedConfigReading> {
+  if (response === undefined) {
+    return { kind: "unanswered" };
+  }
+  if (!response.ok) {
+    await discardBody(response);
+    return { kind: "notServed", detail: `HTTP ${response.status}` };
+  }
+  let detail = UNREADABLE_CONFIG_DETAIL;
+  try {
+    const body: unknown = await response.json();
+    if (isPlainObject(body)) {
+      if (body.mode === PAIRING_EDGE_MODE) {
+        return {
+          kind: "served",
+          config: {
+            assistantId: trimmedNonEmptyString(body.assistantId),
+            assistantName: trimmedNonEmptyString(body.assistantName),
+          },
+        };
+      }
+      detail = UNMARKED_CONFIG_DETAIL;
+    }
+  } catch {
+    /* an unparseable body is an edge answering with something else */
+  }
+  await discardBody(response);
+  return { kind: "notServed", detail };
+}

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

@@ -115,6 +115,31 @@ describe("createLiveVoiceConnection", () => {
     ]);
   });
 
+  test("drops a pending start when its transport closes mid-wait", async () => {
+    const { sessions } = installFakeManager((_session, ctx) =>
+      ctx.sessionId === "session-1"
+        ? { close: mock(() => new Promise<void>(() => {})) }
+        : {},
+    );
+    const first = createConnection();
+    const second = createConnection();
+
+    await first.connection.handleMessage(START_MESSAGE);
+    // The first transport goes away and its session begins a teardown that
+    // never finishes, so the next start has to wait for the slot.
+    first.connection.release();
+
+    const pending = second.connection.handleMessage(START_MESSAGE);
+    await Promise.resolve();
+    second.connection.release();
+    await pending;
+
+    // No session was built for the socket that is already gone.
+    expect(sessions).toHaveLength(1);
+    expect(second.connection.sessionId).toBeUndefined();
+    expect(second.frames).toEqual([]);
+  });
+
   test("assigns monotonically increasing sequence numbers", async () => {
     installFakeManager();
     const { connection, frames } = createConnection();

package/src/live-voice/__tests__/live-voice-flux-turn-end.test.ts

@@ -410,7 +410,10 @@ describe("LiveVoiceSession Flux end-of-turn", () => {
     await waitFor(() => turnCalls.length === 1);
 
     const metricsFrame = await waitForTurnMetrics(frames);
-    expect(metricsFrame.endpointCommitLatencyMs).toBeGreaterThanOrEqual(250);
+    // Date.now() vs setTimeout can undershoot the sleep by a millisecond on
+    // a loaded runner. The assertion is that the speech-stop anchor saw the
+    // pause, not that the timer is exact.
+    expect(metricsFrame.endpointCommitLatencyMs).toBeGreaterThanOrEqual(240);
 
     await session.close("client_end");
   });
@@ -435,7 +438,10 @@ describe("LiveVoiceSession Flux end-of-turn", () => {
     // the two arms one population rather than two.
     const metricsFrame = await waitForTurnMetrics(frames);
     expect(metricsFrame.endpointDecisionSource).toBeUndefined();
-    expect(metricsFrame.endpointCommitLatencyMs).toBeGreaterThanOrEqual(40);
+    // The silence timer is 40 ms. CI clock jitter can report 39. The
+    // assertion is that the front-door path recorded a silence-scale
+    // latency, not that setTimeout fired on the exact millisecond.
+    expect(metricsFrame.endpointCommitLatencyMs).toBeGreaterThanOrEqual(30);
 
     await session.close("client_end");
   });

package/src/live-voice/__tests__/live-voice-session-manager.test.ts

@@ -6,6 +6,7 @@ import {
   type LiveVoiceSessionFactoryContext,
   LiveVoiceSessionManager,
   LiveVoiceSessionStartupError,
+  type LiveVoiceSlotEvent,
 } from "../live-voice-session-manager.js";
 import type {
   LiveVoiceClientFrame,
@@ -328,7 +329,7 @@ describe("LiveVoiceSessionManager", () => {
     expect(manager.activeSessionId).toBe("session-1");
   });
 
-  test("holds the session lock until close completes", async () => {
+  test("makes a start that arrives mid-close wait for the slot", async () => {
     const sessions: TestSession[] = [];
     let resolveClose: (() => void) | undefined;
     const manager = new LiveVoiceSessionManager({
@@ -349,28 +350,28 @@ describe("LiveVoiceSessionManager", () => {
     });
     const first = createSink();
     const second = createSink();
-    const third = createSink();
 
     await manager.startSession(START_FRAME, first.sink);
     const releasePromise = manager.releaseSession("session-1", "client_end");
-    const concurrent = await manager.startSession(START_FRAME, second.sink);
+    // The reconnect: a fresh transport asking for a session while the previous
+    // one is still unwinding. It must not be told the dying session is active.
+    const concurrent = manager.startSession(START_FRAME, second.sink);
     const concurrentDispatch = await manager.handleClientFrame("session-1", {
       type: "interrupt",
     });
 
-    expect(concurrent).toEqual({
-      status: "busy",
-      activeSessionId: "session-1",
-      frame: { type: "busy", seq: 1, activeSessionId: "session-1" },
-    });
     expect(concurrentDispatch).toEqual({ status: "not_found" });
+    // The lock still holds: no second session exists alongside the closing one.
     expect(sessions).toHaveLength(1);
+    expect(second.frames).toEqual([]);
 
     resolveClose?.();
     await releasePromise;
 
-    const next = await manager.startSession(START_FRAME, third.sink);
-    expect(next).toEqual({ status: "accepted", sessionId: "session-2" });
+    expect(await concurrent).toEqual({
+      status: "accepted",
+      sessionId: "session-2",
+    });
     expect(manager.activeSessionId).toBe("session-2");
   });
 
@@ -393,3 +394,204 @@ describe("LiveVoiceSessionManager", () => {
     }
   });
 });
+
+/**
+ * Closure assurance (LUM-3440): the slot must come back on its own from every
+ * way a session can stop being usable, because the client whose transport
+ * died cannot ask for it back and a user who force-quits the app does not get
+ * a second chance either.
+ */
+describe("LiveVoiceSessionManager slot reclamation", () => {
+  const SERVER_VAD_START = {
+    ...START_FRAME,
+    turnDetection: "server_vad",
+  } as const satisfies LiveVoiceClientStartFrame;
+
+  const sleep = (ms: number) =>
+    new Promise((resolve) => setTimeout(resolve, ms));
+
+  test("frees the slot when a session's close never finishes", async () => {
+    const events: LiveVoiceSlotEvent[] = [];
+    const sessions: TestSession[] = [];
+    const manager = new LiveVoiceSessionManager({
+      createSessionId: mock(() => `session-${sessions.length + 1}`),
+      closeTimeoutMs: 25,
+      createSession: () => {
+        const session = createTestSession({
+          // A teardown that hangs: the shape of a close awaiting a
+          // continuation delivery or a provider that never answers.
+          close: mock(() => new Promise<void>(() => {})),
+        });
+        sessions.push(session);
+        return session;
+      },
+      onSlotEvent: (event) => events.push(event),
+    });
+
+    await manager.startSession(START_FRAME, createSink().sink);
+    await manager.releaseSession("session-1", "websocket_close");
+
+    expect(manager.activeSessionId).toBeNull();
+    expect(events).toEqual([
+      {
+        kind: "close_timed_out",
+        sessionId: "session-1",
+        reason: "websocket_close",
+        timeoutMs: 25,
+      },
+    ]);
+
+    // The whole point: the next session starts instead of being told the
+    // wedged one is still active.
+    const next = await manager.startSession(START_FRAME, createSink().sink);
+    expect(next).toEqual({ status: "accepted", sessionId: "session-2" });
+  });
+
+  test("releases a server_vad session whose client goes silent", async () => {
+    const events: LiveVoiceSlotEvent[] = [];
+    const session = createTestSession();
+    const manager = new LiveVoiceSessionManager({
+      createSessionId: () => "session-1",
+      clientSilenceTimeoutMs: 30,
+      createSession: () => session,
+      onSlotEvent: (event) => events.push(event),
+    });
+
+    await manager.startSession(SERVER_VAD_START, createSink().sink);
+    expect(manager.activeSessionId).toBe("session-1");
+
+    await sleep(90);
+
+    expect(manager.activeSessionId).toBeNull();
+    expect(session.closeReasons).toEqual(["client_timeout"]);
+    expect(events).toEqual([
+      {
+        kind: "client_silence_timeout",
+        sessionId: "session-1",
+        timeoutMs: 30,
+      },
+    ]);
+  });
+
+  test("hangs up the transport it reclaimed the slot from", async () => {
+    const session = createTestSession();
+    const manager = new LiveVoiceSessionManager({
+      createSessionId: () => "session-1",
+      clientSilenceTimeoutMs: 30,
+      createSession: () => session,
+    });
+    const closeTransport = mock(() => {});
+    const { sink } = createSink();
+
+    await manager.startSession(SERVER_VAD_START, { ...sink, closeTransport });
+    await sleep(90);
+
+    // Reclaiming the slot alone would leave the client streaming into a
+    // session that no longer exists, and every socket out to it open.
+    expect(closeTransport).toHaveBeenCalledTimes(1);
+    expect(session.closeReasons).toEqual(["client_timeout"]);
+  });
+
+  test("inbound audio pushes the silence deadline out", async () => {
+    const session = createTestSession();
+    const manager = new LiveVoiceSessionManager({
+      createSessionId: () => "session-1",
+      clientSilenceTimeoutMs: 60,
+      createSession: () => session,
+    });
+
+    await manager.startSession(SERVER_VAD_START, createSink().sink);
+    await sleep(40);
+    await manager.handleBinaryAudio("session-1", new Uint8Array([1, 2, 3]));
+    // Past the original deadline: only the refresh keeps this session alive.
+    await sleep(40);
+
+    expect(manager.activeSessionId).toBe("session-1");
+    expect(session.closeReasons).toEqual([]);
+  });
+
+  test("leaves a manual session alone, its silence is not evidence", async () => {
+    const session = createTestSession();
+    const manager = new LiveVoiceSessionManager({
+      createSessionId: () => "session-1",
+      clientSilenceTimeoutMs: 20,
+      createSession: () => session,
+    });
+
+    await manager.startSession(
+      { ...START_FRAME, turnDetection: "manual" },
+      createSink().sink,
+    );
+    await sleep(70);
+
+    expect(manager.activeSessionId).toBe("session-1");
+    expect(session.closeReasons).toEqual([]);
+  });
+
+  test("abandons a start whose transport went away while it waited", async () => {
+    const sessions: TestSession[] = [];
+    const manager = new LiveVoiceSessionManager({
+      createSessionId: mock(() => `session-${sessions.length + 1}`),
+      createSession: () => {
+        const session = createTestSession({
+          close: mock(() => new Promise<void>(() => {})),
+        });
+        sessions.push(session);
+        return session;
+      },
+    });
+    const second = createSink();
+
+    await manager.startSession(START_FRAME, createSink().sink);
+    void manager.releaseSession("session-1", "transport_closed");
+
+    const abort = new AbortController();
+    const pending = manager.startSession(START_FRAME, second.sink, {
+      signal: abort.signal,
+    });
+    await sleep(0);
+    // The socket that asked gave up while the outgoing slot was still
+    // unwinding. Building its session anyway would hand the slot to nobody.
+    abort.abort();
+
+    expect(await pending).toEqual({ status: "aborted" });
+    expect(sessions).toHaveLength(1);
+    expect(second.frames).toEqual([]);
+  });
+
+  test("hangs up the transport when the slot is force-ended", async () => {
+    const session = createTestSession();
+    const manager = new LiveVoiceSessionManager({
+      createSessionId: () => "session-1",
+      createSession: () => session,
+    });
+    const closeTransport = mock(() => {});
+    const { sink } = createSink();
+
+    await manager.startSession(START_FRAME, { ...sink, closeTransport });
+    await manager.endActiveSession();
+
+    // Otherwise the client whose session was ended from elsewhere keeps
+    // showing an active call until it happens to send another frame.
+    expect(closeTransport).toHaveBeenCalledTimes(1);
+    expect(session.closeReasons).toEqual(["forced_end"]);
+  });
+
+  test("ends the active session on request, whoever holds it", async () => {
+    const session = createTestSession();
+    const manager = new LiveVoiceSessionManager({
+      createSessionId: () => "session-1",
+      createSession: () => session,
+    });
+
+    expect(await manager.endActiveSession()).toEqual({ released: false });
+
+    await manager.startSession(START_FRAME, createSink().sink);
+    expect(await manager.endActiveSession()).toEqual({
+      released: true,
+      sessionId: "session-1",
+    });
+    expect(session.closeReasons).toEqual(["forced_end"]);
+    expect(manager.activeSessionId).toBeNull();
+  });
+});

package/src/live-voice/__tests__/live-voice-session-telemetry.test.ts

@@ -147,9 +147,12 @@ describe("live-voice session telemetry", () => {
 
     await session.close("client_end");
 
+    // These sessions reach `ready` and are closed without ever sending audio,
+    // so they are silent by construction and the reason says which layer
+    // stopped short. See `telemetry/live-voice-funnel.ts`.
     expect(recordLiveVoiceSessionEnded).toHaveBeenCalledWith({
       sessionId: "session-123",
-      screen: "ended_client_end",
+      screen: "ended_client_end:silent_no_audio",
       outcome: "completed",
     });
   });
@@ -164,7 +167,7 @@ describe("live-voice session telemetry", () => {
     // the reason on `screen` is what distinguishes a drop from a hangup.
     expect(recordLiveVoiceSessionEnded).toHaveBeenCalledWith({
       sessionId: "session-123",
-      screen: "ended_websocket_close",
+      screen: "ended_websocket_close:silent_no_audio",
       outcome: "completed",
     });
   });