@vellumai/assistant 0.11.4-staging.2 → 0.11.4-staging.4

package/src/providers/__tests__/context-overflow-error.test.ts

@@ -239,6 +239,30 @@ describe("detectOpenAICompatibleContextOverflow", () => {
     expect(detectOpenAICompatibleContextOverflow(err)).toBeNull();
   });
 
+  test("matches OpenAI's per-part 10MiB string_above_max_length 400", () => {
+    const err = buildOpenAIApiError(400, {
+      message:
+        "Invalid 'input[191].content[1].text': string too long. Expected a string with maximum length 10485760, but got a string with length 11436754 instead.",
+      type: "invalid_request_error",
+      code: "string_above_max_length",
+    });
+    const out = detectOpenAICompatibleContextOverflow(err);
+    expect(out).not.toBeNull();
+    // Byte lengths in this message must not be misread as token counts.
+    expect(out?.actualTokens).toBeUndefined();
+    expect(out?.maxTokens).toBeUndefined();
+  });
+
+  test("returns null for string_above_max_length on a non-content field", () => {
+    const err = buildOpenAIApiError(400, {
+      message:
+        "Invalid 'tools[0].function.description': string too long. Expected a string with maximum length 1048576, but got a string with length 2000000 instead.",
+      type: "invalid_request_error",
+      code: "string_above_max_length",
+    });
+    expect(detectOpenAICompatibleContextOverflow(err)).toBeNull();
+  });
+
   test("matches 'too many input tokens' variant emitted by some OpenAI-compatible providers", () => {
     const err = buildOpenAIApiError(400, {
       message: "too many input tokens: 250000",

package/src/providers/__tests__/retry-callsite.test.ts

@@ -370,6 +370,26 @@ describe("RetryProvider — callSite resolution", () => {
     }
   });
 
+  test("memory-v3 selection does not inherit high effort", async () => {
+    setLlmConfig({ defaultProvider: { provider: "anthropic" } });
+
+    let seen: SendMessageOptions | undefined;
+    const wrapped = new RetryProvider(
+      makeProvider("anthropic", (options) => {
+        seen = options;
+      }),
+    );
+
+    await wrapped.sendMessage(DUMMY_MESSAGES, {
+      config: { callSite: "memoryV3SelectL2" },
+    });
+
+    const config = seen?.config as Record<string, unknown>;
+    expect(config.effort).toBe("low");
+    expect(config.thinking).toEqual({ type: "disabled" });
+    expect(config.temperature).toBe(0);
+  });
+
   test("propagates resolved effort/speed/temperature; omits server-side fields", async () => {
     setLlmConfig({
       callSites: {

package/src/providers/openai/chat-completions-provider.ts

@@ -85,7 +85,17 @@ export function detectOpenAICompatibleContextOverflow(
     /context.?length.?exceeded|context.?window.?exceeded|prompt.?is.?too.?long|prompt_too_long|input.?too.?long|too.?many.?(?:input.?)?tokens|maximum.?context/i.test(
       message,
     );
-  if (!codeMatches && !messageMatches) {
+  // string_above_max_length is OpenAI's generic oversized-string validation
+  // code, so only treat it as overflow when the error points at a message
+  // content part (e.g. "Invalid 'input[191].content[1].text': string too
+  // long" — OpenAI's per-part 10 MiB cap). The overflow ladder can shrink
+  // message content (media stubbing collapses a file's extracted_text to a
+  // preview) but cannot fix other oversized fields like tool definitions.
+  const oversizedContentPart =
+    /string.?too.?long|string_above_max_length/i.test(
+      `${code ?? ""} ${message}`,
+    ) && /\b(?:input|messages)\[\d+\]\.content/i.test(message);
+  if (!codeMatches && !messageMatches && !oversizedContentPart) {
     return null;
   }
   // OpenAI-compatible providers rarely report usable token counts; best-effort extract.

package/src/providers/speech-to-text/__tests__/deepgram-flux-realtime.test.ts

@@ -185,7 +185,6 @@ describe("DeepgramFluxRealtimeTranscriber", () => {
     const transcriber = new DeepgramFluxRealtimeTranscriber(TEST_API_KEY, {
       // Long enough that no watchdog fires mid-test.
       inactivityTimeoutMs: 60_000,
-      keepaliveIntervalMs: 0,
       ...options,
     });
     const events: SttStreamServerEvent[] = [];
@@ -571,16 +570,22 @@ describe("DeepgramFluxRealtimeTranscriber", () => {
       expect(events).toEqual([{ type: "closed" }]);
     });
 
-    test("keepalive frames go out on the configured interval", async () => {
-      const { transcriber } = await startSession({ keepaliveIntervalMs: 10 });
+    test("no KeepAlive is ever sent: Flux rejects it and closes", async () => {
+      const { transcriber } = await startSession();
 
+      // Flux accepts only CloseStream and Configure. A KeepAlive earns an
+      // UNPARSABLE_CLIENT_MESSAGE error frame and a server close, which on a
+      // stream held across turns kills it every keepalive interval.
       await Bun.sleep(35);
       transcriber.stop();
 
-      const keepalives = mockWs.sentData.filter(
-        (data) => data === JSON.stringify({ type: "KeepAlive" }),
+      const controlFrames = mockWs.sentData.filter(
+        (data) => typeof data === "string",
+      );
+      expect(controlFrames).not.toContain(
+        JSON.stringify({ type: "KeepAlive" }),
       );
-      expect(keepalives.length).toBeGreaterThanOrEqual(2);
+      expect(controlFrames).toContain(JSON.stringify({ type: "CloseStream" }));
     });
 
     test("finalizeUtterance is absent, Flux has no mid-stream flush", async () => {

package/src/providers/speech-to-text/deepgram-flux-realtime.ts

@@ -3,7 +3,7 @@
  *
  * Flux is Deepgram's conversational speech API: the model itself decides where
  * a turn ends, so this adapter carries no endpointing heuristics of its own.
- * It owns the socket lifecycle (connect, keepalive, teardown) and delegates
+ * It owns the socket lifecycle (connect, teardown) and delegates
  * every inbound transcript frame to {@link parseFluxFrame}, the pure protocol
  * module, which maps Flux's wire shapes onto the daemon's
  * {@link SttStreamServerEvent} contract.
@@ -24,6 +24,14 @@
  * a caller-side boundary, so the optional method is left off and callers
  * feature-detect it and fall back to {@link stop}.
  *
+ * There is also **no keepalive**. Flux accepts exactly two control messages,
+ * `CloseStream` and `Configure`; the v1 streaming `KeepAlive` is not one of
+ * them, and sending it earns an `UNPARSABLE_CLIENT_MESSAGE` error frame
+ * followed by a server close. Audio is the only thing that holds a Flux stream
+ * open, so a stream that has to survive a long silence must carry silent
+ * frames rather than a control message.
+ * See https://developers.deepgram.com/docs/flux/close-stream
+ *
  * Error handling mirrors `deepgram-realtime.ts`: socket closes and errors map
  * onto {@link SttErrorCategory} values (`auth`, `rate-limit`, `timeout`,
  * `provider-error`), in-session failures surface as `error` events, and
@@ -69,13 +77,6 @@ const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
  */
 const DEFAULT_INACTIVITY_TIMEOUT_MS = 30_000;
 
-/**
- * Interval (ms) between `KeepAlive` control frames. Deepgram closes a socket
- * that carries no audio for ~10s, and raw silence does not reset that timer.
- * Only the explicit control message does.
- */
-const DEFAULT_KEEPALIVE_INTERVAL_MS = 5_000;
-
 /** Outbound buffer ceiling (bytes) before {@link sendAudio} drops frames. */
 const MAX_BUFFERED_AMOUNT = 1024 * 1024; // 1 MiB
 
@@ -114,11 +115,6 @@ export interface DeepgramFluxRealtimeOptions {
   connectTimeoutMs?: number;
   /** Inactivity timeout in milliseconds. Default: 30_000. */
   inactivityTimeoutMs?: number;
-  /**
-   * Interval (ms) between `KeepAlive` control frames. Default: 5_000. Set to
-   * 0 to disable (tests only, because Deepgram closes silent sockets after ~10s).
-   */
-  keepaliveIntervalMs?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -169,7 +165,6 @@ export class DeepgramFluxRealtimeTranscriber implements StreamingTranscriber {
   private readonly sampleRate: number;
   private readonly connectTimeoutMs: number;
   private readonly inactivityTimeoutMs: number;
-  private readonly keepaliveIntervalMs: number;
 
   /** The live WebSocket connection, set during start(). */
   private ws: WsLike | null = null;
@@ -208,9 +203,6 @@ export class DeepgramFluxRealtimeTranscriber implements StreamingTranscriber {
   /** Close grace timer handle. */
   private closeGraceTimer: ReturnType<typeof setTimeout> | null = null;
 
-  /** Periodic `KeepAlive` timer. */
-  private keepaliveTimer: ReturnType<typeof setInterval> | null = null;
-
   constructor(apiKey: string, options: DeepgramFluxRealtimeOptions = {}) {
     this.apiKey = apiKey;
     this.flux = getConfig().liveVoice.flux;
@@ -219,8 +211,6 @@ export class DeepgramFluxRealtimeTranscriber implements StreamingTranscriber {
       options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
     this.inactivityTimeoutMs =
       options.inactivityTimeoutMs ?? DEFAULT_INACTIVITY_TIMEOUT_MS;
-    this.keepaliveIntervalMs =
-      options.keepaliveIntervalMs ?? DEFAULT_KEEPALIVE_INTERVAL_MS;
   }
 
   // ── StreamingTranscriber interface ──────────────────────────────────
@@ -300,7 +290,6 @@ export class DeepgramFluxRealtimeTranscriber implements StreamingTranscriber {
     // Socket is open. Attach the handlers for the active session lifetime.
     this.attachSessionHandlers(ws);
     this.resetInactivityTimer();
-    this.startKeepaliveTimer();
 
     log.info({ model: this.flux.model }, "Deepgram Flux session opened");
   }
@@ -586,35 +575,6 @@ export class DeepgramFluxRealtimeTranscriber implements StreamingTranscriber {
       clearTimeout(this.closeGraceTimer);
       this.closeGraceTimer = null;
     }
-    if (this.keepaliveTimer !== null) {
-      clearInterval(this.keepaliveTimer);
-      this.keepaliveTimer = null;
-    }
-  }
-
-  /**
-   * Start the periodic keepalive. A `KeepAlive` control frame is the only
-   * thing that resets Deepgram's server-side inactivity timer while the
-   * stream carries silence. Raw silent PCM does not count.
-   */
-  private startKeepaliveTimer(): void {
-    if (this.closed || this.stopping || this.keepaliveIntervalMs <= 0) {
-      return;
-    }
-    this.keepaliveTimer = setInterval(() => {
-      if (this.closed || this.stopping) {
-        return;
-      }
-      const ws = this.ws;
-      if (!ws || ws.readyState !== WS_OPEN) {
-        return;
-      }
-      try {
-        ws.send(JSON.stringify({ type: "KeepAlive" }));
-      } catch (err) {
-        log.warn({ err }, "Deepgram Flux KeepAlive send failed");
-      }
-    }, this.keepaliveIntervalMs);
   }
 
   /**

package/src/routes/control.ts

@@ -68,6 +68,7 @@ export async function spawnRouteHostWorkerProcess(
     return await spawnWorkerProcess({
       pidPath: routeHostPidPath(),
       entry: new URL("./worker.ts", import.meta.url),
+      packagedEntry: "routes",
       workerLabel: "Route host",
       options: opts,
     });

package/src/routes/route-host-client.ts

@@ -149,6 +149,7 @@ export class RouteHostClient {
       ({ pid } = await spawnWorkerProcess({
         pidPath: this.pidPath,
         entry: this.workerEntryUrl,
+        packagedEntry: "routes",
         workerLabel: "Route host",
         // Owned by the daemon (appears in its process tree, torn down with it);
         // kill it if it hangs during startup so a failed spawn leaves nothing.

package/src/runtime/AGENTS.md

@@ -93,39 +93,38 @@ Host app-control allows the assistant to proxy app-control actions (target a spe
   - `POST /v1/host-app-control-result` — `{ requestId, state, pngBase64?, windowBounds?, executionResult?, executionError? }`. `state` is one of `"running" | "missing" | "minimized"`.
 - **Tracking**: Uses the same `pending-interactions` tracker as the other host proxy types, with `kind: "host_app_control"`. The route handler is in `host-app-control-routes.ts` and forwards the payload to the owning conversation's `hostAppControlProxy.resolve()`. Late delivery is tolerated — the route returns 200 even when no pending interaction matches (e.g. the conversation was disposed before the client reported back).
 
-### `chrome-extension` interface (Phase 2)
+### `chrome-extension` interface
 
 The `chrome-extension` interface in `INTERFACE_IDS` is a non-interactive transport that supports only the `host_browser` capability — it does NOT support `host_bash`, `host_file`, or `host_cu`. This is encoded in `supportsHostProxy(id, capability)`: passing a capability argument returns `true` for `chrome-extension` only when the capability is `host_browser`; the no-arg form returns `false` for `chrome-extension` (so legacy desktop-only call sites that assume full-desktop proxy availability continue to gate correctly).
 
-For **self-hosted** deployments, `host_browser_request` frames are routed through the `ChromeExtensionRegistry` singleton (`runtime/chrome-extension-registry.ts`), which tracks active chrome-extension WebSocket connections keyed by `(guardianId, clientInstanceId)`. The registry is populated on WebSocket `open` and drained on `close` inside `http-server.ts`'s `/v1/browser-relay` handlers — see the `wsType === "browser-relay"` branches. For **cloud/platform-hosted** deployments, the chrome extension connects via SSE (`GET /v1/events` with `X-Vellum-Interface-Id: chrome-extension`) and `host_browser_request` frames travel through `assistantEventHub` to the SSE stream. The extension POSTs results back to `POST /v1/host-browser-result`. Transport selection is handled by `HostBrowserProxy`, which publishes events to the `assistantEventHub` with `targetCapability: "host_browser"` — the hub delivers to whichever subscriber (chrome-extension or macOS client) has the `host_browser` capability. For macOS, `host_browser_request` frames travel through `assistantEventHub` (SSE) by default; when the guardian also has an active extension connection, the registry-routed WebSocket sender takes precedence.
+The extension reaches the daemon over the same two doors every client uses. Self-hosted, it pairs once through the gateway's `POST /v1/pair` (`gateway/src/http/routes/pair.ts`: loopback-only, rate-limited, mints an `actor_client_v1` JWT for the `X-Vellum-Interface-Id: chrome-extension` caller); cloud deployments issue the guardian-bound JWT through the gateway's WorkOS-backed flow. It then subscribes to `GET /v1/events` with `X-Vellum-Interface-Id: chrome-extension`, which registers it on `assistantEventHub` with the single `host_browser` capability, and it answers work by POSTing to `POST /v1/host-browser-result`.
 
-A single guardian may have multiple parallel extension installs connected at once (two Chrome profiles, two desktops sharing a sync identity). Each install generates a stable `clientInstanceId` on first run, persists it in `chrome.storage.local`, and sends it on every WebSocket handshake as a query param (`clientInstanceId=...`) or header (`x-client-instance-id`). The registry keys inner entries by that id so sibling installs don't evict each other on register/unregister. The default `send(guardianId, msg)` path routes to whichever instance has the most recent activity (`lastActiveAt`); `sendToInstance(guardianId, clientInstanceId, msg)` pins a specific install. Older extension builds that omit the id get a connection-scoped `legacy:<connectionId>` fallback key so they degrade gracefully to single-instance semantics.
+`HostBrowserProxy` (`daemon/host-browser-proxy.ts`, a lazily-created singleton) is the only sender: it publishes `host_browser_request` frames to the hub with `targetCapability: "host_browser"` and an explicit target client, choosing that client at send time from the hub's live roster (`resolveTargetClient`). Both the extension and the macOS desktop bridge register `host_browser`, so ordering is method-aware rather than pure recency: `Vellum.*` pseudo-methods (tabs, attach, detach) go only to a chrome-extension client, the only transport that implements them; raw CDP methods prefer a chrome-extension client over the macOS bridge, most recently active first within each group; an explicit `targetClientId` pins one client; and when a `sourceActorPrincipalId` is supplied only that actor's clients are eligible. Several extension installs for one guardian are simply several `host_browser` clients on the roster. A dispatch that lands during a brief MV3 service-worker reconnect waits up to `EXTENSION_RECONNECT_GRACE_MS` before failing.
 
-`Conversation.hostBrowserSenderOverride` is the integration point between the turn layer and the proxy. When any turn enters the routes layer and the guardian has an active extension connection in the `ChromeExtensionRegistry`, `conversation-routes.ts` resolves the registry entry and sets the override to a sender that writes to that WebSocket. This applies to chrome-extension turns (where the registry is the only transport) and macOS turns (where the extension connection lets browser tools route through the user's real Chrome session instead of cdp-inspect/local). `Conversation.restoreBrowserProxyAvailability()` re-threads the override on queue drain — without this, the drain path would clobber the registry-routed sender with the default `sendToClient` (pointed at the SSE hub) and `host_browser_request` frames would stop reaching the extension mid-queue.
+Nothing in the turn layer wires the proxy: it reads the roster on every send, and the conversation's own event sink is fixed for its life (see `assistant/AGENTS.md`, "Conversation event delivery and turn presence"), so a queued or drained turn reaches the extension exactly like a live one.
 
-Capability token bootstrap for self-hosted deployments is handled by the gateway (`gateway/src/http/routes/browser-extension-pair.ts`) which mints a guardian-bound HMAC capability token. The daemon delegates token verification to the gateway via IPC (`verify_capability_token`) — it must never read secrets from `GATEWAY_SECURITY_DIR` or any other gateway-owned directory. Cloud deployments issue guardian-bound JWTs via the gateway's WorkOS-backed flow.
-
-See `docs/browser-use-architecture-phase2.md` for the full wire diagram and component inventory.
+See `docs/browser-use-architecture-phase2.md` for the backend scenarios and the manual QA checklist.
 
 ### Canonical browser backend precedence (macOS)
 
 On macOS-originated turns, the CDP factory (`tools/browser/cdp-client/factory.ts`) evaluates three browser backends in strict priority order. Each candidate is tried lazily; if the first command fails with a transport-level error, the factory falls over to the next candidate. CDP protocol errors (the browser understood the command but rejected it) do NOT trigger failover.
 
-| Priority | Backend                    | Condition                                                                                                                                                                                           | Transport                                                                                                                                      |
-| -------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1        | **Extension / host proxy** | `hostBrowserProxy` present AND `isAvailable()` returns `true`. On macOS, the proxy is always provisioned. On other interfaces, requires an active hub subscriber with `host_browser` capability     | WS via `ChromeExtensionRegistry` (self-hosted), SSE via `assistantEventHub` with `targetCapability: "host_browser"` (cloud extension or macOS) |
-| 2        | **cdp-inspect**            | (a) `hostBrowser.cdpInspect.enabled` is `true` in config, OR (b) `transportInterface === "macos"` AND `desktopAuto.enabled` is `true` (default) AND the cooldown from a prior failure is not active | Direct CDP WebSocket to `localhost:9222`                                                                                                       |
-| 3        | **Local**                  | Always present as the final fallback                                                                                                                                                                | In-process Playwright CDP via `browserManager`                                                                                                 |
+| Priority | Backend                    | Condition                                                                                                                                                                                                                                                                                                                      | Transport                                                                                 |
+| -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| 1        | **Extension / host proxy** | Two candidates from the always-present `HostBrowserProxy` singleton: `extension` when `hasExtensionClient(actor)` finds a chrome-extension client on the hub; otherwise `host-bridge` when `isAvailable(actor)` finds any `host_browser` client (the macOS desktop bridge) and that actor's host-bridge cooldown is not active | SSE via `assistantEventHub` with `targetCapability: "host_browser"`, to the chosen client |
+| 2        | **cdp-inspect**            | (a) `hostBrowser.cdpInspect.enabled` is `true` in config, OR (b) `transportInterface === "macos"` AND `desktopAuto.enabled` is `true` (default) AND the cooldown from a prior failure is not active                                                                                                                            | Direct CDP WebSocket to `localhost:9222`                                                  |
+| 3        | **Local**                  | Always present as the final fallback                                                                                                                                                                                                                                                                                           | In-process Playwright CDP via `browserManager`                                            |
 
 **Transport selection for the extension/host-proxy backend:**
 
-The "extension" backend label is a misnomer inherited from the original Phase 2 design where only the Chrome Extension provided host-browser access. In the current architecture, two transports can power this backend:
+The "extension" backend label predates the macOS bridge; two SSE transports power it, both through the same `HostBrowserProxy` → `ExtensionCdpClient` pipeline:
+
+- **Chrome extension**: `HostBrowserProxy.send()` publishes to `assistantEventHub` with `targetCapability: "host_browser"`, targeting the chrome-extension client `resolveTargetClient` chose (see the interface section above); the extension executes the CDP command via `chrome.debugger` and POSTs the result to `/v1/host-browser-result`.
+- **macOS SSE bridge**: when no chrome-extension client is eligible, the same publish targets the macOS subscriber (which registers every host-proxy capability); the desktop client executes the command against the local Chrome and POSTs the result the same way.
 
-- **Extension WebSocket** (self-hosted): When the `ChromeExtensionRegistry` has an active entry for the guardian, the registry-routed sender delivers frames over the `/v1/browser-relay` WebSocket to the Chrome extension, which executes CDP commands via `chrome.debugger`.
-- **Extension SSE** (cloud/platform): When no WebSocket entry exists, `HostBrowserProxy.send()` publishes to `assistantEventHub` with `targetCapability: "host_browser"`. The hub delivers the event to the chrome-extension subscriber (which registered with that capability via SSE). The extension POSTs results back to `/v1/host-browser-result`. This path is used for any `canServiceSseBrowser()` interface (`web`, `chrome-extension`, `macos`).
-- **macOS SSE bridge**: When the macOS desktop client is connected but no extension is present, the same hub publish with `targetCapability: "host_browser"` delivers to the macOS subscriber (which has all host-proxy capabilities). The desktop client executes CDP commands against the local Chrome and POSTs results back to `/v1/host-browser-result`.
+In the CDP factory the bridge is the internal `"host-bridge"` candidate kind (`InternalBrowserMode`, never a caller-pinnable `browser_mode`). `browser_status` labels the extension path `details.transport: "extension-ws"`; the label predates the SSE transport and is kept as-is.
 
-All three transports use the same `HostBrowserProxy` → `ExtensionCdpClient` pipeline. The `browser_status` output distinguishes the transport via the `details.transport` field: `"extension-ws"` or `"macos-sse"`.
+**Host-bridge cooldown:** a `host-bridge` transport failure records a per-actor cooldown (`recordHostBridgeCooldown`, keyed by `sourceActorPrincipalId`, `__default__` when unresolved) for the same `desktopAuto.cooldownMs` window; while it is active the factory skips the bridge candidate (log `CDP factory: host-bridge skipped (cooldown active)`) and the turn drops straight to cdp-inspect/local. Per-actor because on a multi-actor cloud daemon the bridge reaches a different desktop per actor, so one actor's missing debug port must not suppress another's only route to their Chrome. Never applies to the `extension` candidate.
 
 **Fallback criteria for cdp-inspect (desktop-auto):**
 

package/src/runtime/agent-wake.ts

@@ -360,7 +360,7 @@ export interface WakeOptions {
    * the conversation belongs to. Used by fork-based memory retrospectives to
    * render the SOURCE conversation's persona sections — both for review
    * quality and for byte-parity with the source's cached system-prompt
-   * prefix. May also pin `hasNoClient` for the prompt build (see
+   * prefix. May also pin presence for the prompt build (see
    * {@link SystemPromptPersonaOverride}). Prompt-build selection only; trust
    * class and approval semantics are governed solely by `trustContext`.
    */
@@ -400,14 +400,14 @@ export interface WakeOptions {
    */
   cronRunId?: string;
   /**
-   * Run the woken turn clientless: pin `hasNoClient = true` for the duration of
-   * the agent-loop run (restored after). Wakes bypass the orchestrator's
-   * turn-start interactivity setup, so a wake on a conversation with no client
-   * attached otherwise derives `isInteractive: true` (the default
-   * `hasNoClient = false`). Pinning it makes `conversation-tool-setup` derive
-   * `isInteractive: false`, which `policy-context` maps to `background`
-   * (guardian) / `headless` (unknown) — so a side-effecting tool that would
-   * prompt is denied instead of stalling on a client that isn't there.
+   * Run the woken turn clientless: pin the per-turn presence
+   * (`currentTurnIsNonInteractive = true`, which `hasNoClient` reads) for the
+   * duration of the agent-loop run (restored after). Wakes bypass the
+   * orchestrator's turn-start interactivity setup, so the pin is what makes
+   * `conversation-tool-setup` derive `isInteractive: false`, which
+   * `policy-context` maps to `background` (guardian) / `headless` (unknown),
+   * so a side-effecting tool that would prompt is denied instead of stalling
+   * on a client that isn't there.
    */
   clientless?: boolean;
 }
@@ -1454,7 +1454,8 @@ export async function wakeAgentForOpportunity(
       const priorCallSite = conversation.currentCallSite;
       const priorTurnOverrideProfile = conversation.currentTurnOverrideProfile;
       const priorTurnCronRunId = conversation.currentTurnCronRunId;
-      const priorHasNoClient = conversation.hasNoClient;
+      const priorTurnIsNonInteractive =
+        conversation.currentTurnIsNonInteractive;
       const priorTurnTrust = conversation.currentTurnTrustContext;
       conversation.currentCallSite = callSite;
       conversation.currentTurnOverrideProfile = overrideProfile;
@@ -1462,7 +1463,9 @@ export async function wakeAgentForOpportunity(
       // delegates work to subagents whose usage must attribute to that firing.
       conversation.currentTurnCronRunId = opts.cronRunId ?? null;
       if (opts.clientless) {
-        conversation.hasNoClient = true;
+        // Presence is per-turn state; a clientless wake declares no human is
+        // present for the duration of its dispatch.
+        conversation.currentTurnIsNonInteractive = true;
       }
       // Per-turn guardian elevation for the wake's tools, set after the pre-run
       // reads so a pre-run failure can't leak it; restored in the finally.
@@ -1550,7 +1553,7 @@ export async function wakeAgentForOpportunity(
         conversation.currentCallSite = priorCallSite;
         conversation.currentTurnOverrideProfile = priorTurnOverrideProfile;
         conversation.currentTurnCronRunId = priorTurnCronRunId;
-        conversation.hasNoClient = priorHasNoClient;
+        conversation.currentTurnIsNonInteractive = priorTurnIsNonInteractive;
         conversation.currentTurnTrustContext = priorTurnTrust;
       }
 

package/src/runtime/routes/__tests__/conversation-list-routes.test.ts

@@ -32,7 +32,7 @@ import {
   conversations,
 } from "../../../persistence/schema/index.js";
 import { ROUTES as CONVERSATION_LIST_ROUTES } from "../conversation-list-routes.js";
-import { BadRequestError } from "../errors.js";
+import { BadRequestError, NotFoundError } from "../errors.js";
 import type { RouteDefinition } from "../types.js";
 
 // ---------------------------------------------------------------------------
@@ -246,6 +246,42 @@ describe("GET /v1/conversations — conversationType", () => {
   });
 });
 
+describe("GET /v1/conversations/:id", () => {
+  const getHandler = findHandler(CONVERSATION_LIST_ROUTES, "getConversation");
+
+  beforeEach(() => {
+    clearConversations();
+  });
+
+  test("serves a listed conversation", () => {
+    const conv = createConversation({ title: "listed" });
+
+    const detail = getHandler({ pathParams: { id: conv.id } }) as {
+      conversation: { id: string; conversationType: string };
+    };
+
+    expect(detail.conversation.id).toBe(conv.id);
+    expect(detail.conversation.conversationType).toBe("standard");
+  });
+
+  test("does not serve a legacy private row the listing hides", () => {
+    // "private" is not a creatable type (legacy rows only); every listing
+    // hides it by type and the wire type collapses it to "standard", so a
+    // client holding only a stale id must get the same answer the listing
+    // gives: not there.
+    const conv = createConversation({ title: "hidden" });
+    rawRun(
+      "test:makePrivate",
+      "UPDATE conversations SET conversation_type = 'private' WHERE id = ?",
+      conv.id,
+    );
+
+    expect(() => getHandler({ pathParams: { id: conv.id } })).toThrow(
+      NotFoundError,
+    );
+  });
+});
+
 describe("GET /v1/conversations with groupId", () => {
   function seedInGroup(title: string, groupId: string): string {
     const conv = createConversation(title);
@@ -514,6 +550,139 @@ describe("GET /v1/conversations with groupId", () => {
   });
 });
 
+describe("GET /v1/conversations with needsAttention", () => {
+  function seedUnseen(conversationId: string): void {
+    projectAssistantMessage({
+      conversationId,
+      messageId: `msg-${conversationId}`,
+      messageAt: Date.now(),
+    });
+  }
+
+  function markSeen(conversationId: string): void {
+    recordConversationSeenSignal({
+      conversationId,
+      sourceChannel: "vellum",
+      signalType: "macos_conversation_opened",
+      confidence: "explicit",
+      source: "test",
+    });
+  }
+
+  beforeEach(() => {
+    getDb().delete(conversationAttentionEvents).run();
+    getDb().delete(conversationAssistantAttentionState).run();
+    clearConversations();
+  });
+
+  test("returns only conversations with an unseen latest assistant message", async () => {
+    const unseen = createConversation("needs-attention");
+    seedUnseen(unseen.id);
+    const seen = createConversation("already-seen");
+    seedUnseen(seen.id);
+    markSeen(seen.id);
+    // No attention projection at all: not unseen, so not returned. The
+    // filter's inner join is what excludes it; a left join would leak it.
+    createConversation("never-projected");
+
+    const result = await invoke({ needsAttention: "true" });
+
+    expect(result.conversations.map((c) => c.title)).toEqual([
+      "needs-attention",
+    ]);
+  });
+
+  test("omitting the filter leaves every list unchanged, join and all", async () => {
+    /* The sensitivity check for the conditional join: with the filter off,
+       rows with no attention row must still be listed. If the join were
+       applied unconditionally, "never-projected" would vanish from the
+       plain list, which is every list the app has today. */
+    const unseen = createConversation("has-attention-row");
+    seedUnseen(unseen.id);
+    createConversation("never-projected");
+
+    const result = await invoke();
+
+    expect(result.conversations.map((c) => c.title).sort()).toEqual([
+      "has-attention-row",
+      "never-projected",
+    ]);
+  });
+
+  test("hasMore and the total describe the filtered set, not the whole table", async () => {
+    /* countConversations reads through the same where AND the same join;
+       a page and its total have to agree or the client's hasMore lies. */
+    for (let i = 0; i < 3; i++) {
+      const c = createConversation(`unseen-${i}`);
+      seedUnseen(c.id);
+    }
+    for (let i = 0; i < 5; i++) {
+      createConversation(`quiet-${i}`);
+    }
+
+    const page = await invoke({ needsAttention: "true", limit: "2" });
+
+    expect(page.conversations).toHaveLength(2);
+    expect(page.hasMore).toBe(true);
+    const rest = await invoke({
+      needsAttention: "true",
+      limit: "2",
+      offset: "2",
+    });
+    expect(rest.conversations).toHaveLength(1);
+    expect(rest.hasMore).toBe(false);
+  });
+
+  test("an attention-scoped first page has no pinned rows appended to it", async () => {
+    /* Same rule as the group-scoped page: the pinned injection exists for
+       a client reading Pinned out of the unfiltered list, and a caller
+       that asked for the unseen subset is not that client. A seen pinned
+       row appended here would be a row outside the filter, on a page whose
+       hasMore was computed from the filtered count. */
+    const unseen = createConversation("unseen-only");
+    seedUnseen(unseen.id);
+    const pinnedSeen = createConversation("pinned-and-seen");
+    rawRun(
+      "test:pinConversation",
+      "UPDATE conversations SET is_pinned = 1, group_id = 'system:pinned' WHERE id = ?",
+      pinnedSeen.id,
+    );
+
+    const result = await invoke({ needsAttention: "true" });
+
+    expect(result.conversations.map((c) => c.title)).toEqual(["unseen-only"]);
+  });
+
+  test("composes with the other filters", async () => {
+    const group = createGroup("Work");
+    const inGroupUnseen = createConversation("in-group-unseen");
+    seedUnseen(inGroupUnseen.id);
+    rawRun(
+      "test:fileInGroup",
+      "UPDATE conversations SET group_id = ? WHERE id = ?",
+      group.id,
+      inGroupUnseen.id,
+    );
+    const outOfGroupUnseen = createConversation("out-of-group-unseen");
+    seedUnseen(outOfGroupUnseen.id);
+
+    const result = await invoke({ needsAttention: "true", groupId: group.id });
+
+    expect(result.conversations.map((c) => c.title)).toEqual([
+      "in-group-unseen",
+    ]);
+  });
+
+  test('any value other than "true" is rejected with a 400', () => {
+    /* Same posture as conversationType: silently reading a typo or a newer
+       client's value as "no filter" would hand back the full list where a
+       subset was asked for, and that skew is invisible to the client. */
+    for (const bad of ["false", "1", "yes", "TRUE"]) {
+      expect(() => invoke({ needsAttention: bad })).toThrow(BadRequestError);
+    }
+  });
+});
+
 describe("GET /v1/conversations/unread-count", () => {
   const unreadCountHandler = findHandler(
     CONVERSATION_LIST_ROUTES,