@vellumai/assistant 0.9.1-staging.1 → 0.10.0-staging.2

package/src/daemon/conversation-surfaces.ts

@@ -291,6 +291,32 @@ export function markSurfaceCompleted(
   }
 }
 
+/**
+ * Complete a `ui_surface` card and notify live clients, addressed only by
+ * conversation + surface id.
+ *
+ * Unlike {@link completeSurfaceFromAction}, this needs no live `Conversation`
+ * instance, so it can run from flows that don't own one — projecting a
+ * terminal guardian-request status onto its in-app approval card when the
+ * request was resolved on another surface (or by the expiry sweep). Persists
+ * the completion (reload-safe) and broadcasts `ui_surface_complete` so every
+ * connected client of this guardian converges. No-ops when the surface block
+ * isn't found in the conversation.
+ */
+export function completeSurfaceAndNotify(
+  conversationId: string,
+  surfaceId: string,
+  summary: string,
+): void {
+  markSurfaceCompleted({ conversationId }, surfaceId, summary);
+  broadcastMessage({
+    type: "ui_surface_complete",
+    conversationId,
+    surfaceId,
+    summary,
+  });
+}
+
 /**
  * Remove a `ui_surface` content block from history so a passively dismissed
  * surface does not survive a reload. The live client drops a dismissed surface

package/src/daemon/conversation-tool-setup.ts

@@ -55,7 +55,7 @@ import {
 } from "./doordash-steps.js";
 import type { ServerMessage, UiSurfaceShow } from "./message-protocol.js";
 import { runPostExecutionSideEffects } from "./tool-side-effects.js";
-import { resolveTrustClass } from "./trust-context.js";
+import { FALLBACK_TURN_TRUST, resolveTrustClass } from "./trust-context.js";
 
 const log = getLogger("conversation-tool-setup");
 
@@ -181,28 +181,32 @@ export function createToolExecutor(
       markDoordashStepInProgress(ctx, executionInput);
     }
 
-    // Build the context object shared by both the skill_execute interception
-    // path and the regular executor path.
+    // Per-turn trust snapshot: prefer the snapshot captured at turn start so
+    // a concurrent owner meta command (/status, /clean) that mutates the live
+    // trustContext cannot elevate the in-flight turn to guardian.
+    const turnTrust =
+      ctx.currentTurnTrustContext ?? ctx.trustContext ?? FALLBACK_TURN_TRUST;
+
     const toolContext: ToolContext = {
       workingDir: ctx.workingDir,
       conversationId: ctx.conversationId,
       assistantId: ctx.assistantId,
       requestId: ctx.currentRequestId,
       taskRunId: ctx.taskRunId,
-      trustClass: resolveTrustClass(ctx.trustContext),
-      executionChannel: ctx.trustContext?.sourceChannel,
-      sourceActorPrincipalId: ctx.trustContext?.guardianPrincipalId,
+      trustClass: resolveTrustClass(turnTrust),
+      executionChannel: turnTrust.sourceChannel,
+      sourceActorPrincipalId: turnTrust.guardianPrincipalId,
       callSessionId: ctx.callSessionId,
       triggeredBySurfaceAction:
         ctx.surfaceActionRequestIds?.has(ctx.currentRequestId ?? "") ?? false,
       approvedViaPrompt: ctx.approvedViaPromptThisTurn || undefined,
       batchAuthorizedByTask: false,
-      requesterExternalUserId: ctx.trustContext?.requesterExternalUserId,
-      requesterChatId: ctx.trustContext?.requesterChatId,
-      requesterIdentifier: ctx.trustContext?.requesterIdentifier,
-      requesterDisplayName: ctx.trustContext?.requesterDisplayName,
+      requesterExternalUserId: turnTrust.requesterExternalUserId,
+      requesterChatId: turnTrust.requesterChatId,
+      requesterIdentifier: turnTrust.requesterIdentifier,
+      requesterDisplayName: turnTrust.requesterDisplayName,
       channelPermissionChannelId:
-        ctx.trustContext?.sourceChannel === "slack"
+        turnTrust.sourceChannel === "slack"
           ? getBindingByConversation(ctx.conversationId)?.externalChatId
           : undefined,
       onOutput,
@@ -214,6 +218,7 @@ export function createToolExecutor(
       isPlatformHosted: getIsPlatform(),
       transportInterface: ctx.transportInterface,
       overrideProfile: ctx.currentTurnOverrideProfile,
+      invokingCallSite: ctx.currentCallSite ?? "mainAgent",
       attribution: resolveConversationAttribution(ctx),
       onToolLifecycleEvent: handleToolLifecycleEvent,
       sendToClient: (msg) => {

package/src/daemon/conversation.ts

@@ -80,12 +80,10 @@ import {
 } from "../prompts/system-prompt.js";
 import type { ContentBlock, Message } from "../providers/types.js";
 import type { Provider } from "../providers/types.js";
-import {
-  isUntrustedTrustClass,
-  type TrustClass,
-} from "../runtime/actor-trust-resolver.js";
+import { type TrustClass } from "../runtime/actor-trust-resolver.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import type { AuthContext } from "../runtime/auth/types.js";
+import { resolveCapabilities } from "../runtime/capabilities.js";
 import type { InteractiveUiResult } from "../runtime/interactive-ui.js";
 import { publishSyncInvalidation } from "../runtime/sync/sync-publisher.js";
 import {
@@ -107,7 +105,7 @@ import {
   runAgentLoopImpl,
 } from "./conversation-agent-loop.js";
 import type { HistoryConversationContext } from "./conversation-history.js";
-import { undo as undoImpl } from "./conversation-history.js";
+import { isToolResultBlock, undo as undoImpl } from "./conversation-history.js";
 import {
   abortConversation,
   disposeConversation,
@@ -175,6 +173,36 @@ import { TraceEmitter } from "./trace-emitter.js";
 
 const log = getLogger("conversation");
 
+/**
+ * Whether a persisted message starts a new conversation turn. A turn is
+ * delimited by a "real" user message; a user message whose content is entirely
+ * tool_result blocks is a continuation within the current turn, and assistant
+ * messages never start one. Mirrors the turn-boundary definition used by
+ * `getAssistantMessageIdsInTurn`/`getTurnTimeBounds` and the agent loop's
+ * per-turn `turnCount++`, so counting these reconstructs `turnCount` on load.
+ */
+function startsNewTurn(role: string, content: string): boolean {
+  if (role !== "user") return false;
+  try {
+    const parsed = JSON.parse(content);
+    if (
+      Array.isArray(parsed) &&
+      parsed.length > 0 &&
+      parsed.every(
+        (block: unknown) =>
+          block != null &&
+          typeof block === "object" &&
+          isToolResultBlock(block as Record<string, unknown>),
+      )
+    ) {
+      return false;
+    }
+  } catch {
+    // Non-JSON content is a plain user message — a turn boundary.
+  }
+  return true;
+}
+
 export interface CleanResult {
   previousEstimatedInputTokens: number;
   estimatedInputTokens: number;
@@ -366,6 +394,13 @@ export class Conversation {
     workspaceDir: string,
   ) => Pick<WorkspaceGitService, "ensureInitialized">;
   /** @internal */ commitTurnChanges?: typeof commitTurnChanges;
+  /**
+   * Abort-watchdog timeout (ms) for the agent loop's bounded-unwind backstop.
+   * Overridable in tests to fire the watchdog quickly; defaults to the
+   * production constant in the agent loop when unset.
+   * @internal
+   */
+  abortWatchdogMs?: number;
   /**
    * The conversation's immutable creation type (`interactive`, `background`,
    * `scheduled`, …) as stored on the DB row. Cached on load (and set directly
@@ -824,10 +859,25 @@ export class Conversation {
 
   async loadFromDb(): Promise<void> {
     const trustClass = this.trustContext?.trustClass;
+    const canAccessMemory = resolveCapabilities(trustClass).canAccessMemory;
     const allDbMessages = getMessages(this.conversationId);
-    const dbMessages = isUntrustedTrustClass(trustClass)
-      ? filterMessagesForUntrustedActor(allDbMessages)
-      : allDbMessages;
+    const dbMessages = canAccessMemory
+      ? allDbMessages
+      : filterMessagesForUntrustedActor(allDbMessages);
+
+    // Rehydrate the in-memory turn counter from persisted history. `turnCount`
+    // is otherwise a fresh-zero field, so a reloaded conversation (eviction,
+    // restart, fork) would restart its turn numbering at 0 and the next turn
+    // would reuse `turnIndex` 0 — colliding with the conversation's first turn.
+    // The memory-v3 selector memoizes per (conversationId, turnIndex) for the
+    // life of the daemon process, so a collided turnIndex serves a stale
+    // selection and skips retrieval. One turn per real (turn-starting) user
+    // message, matching the agent loop's per-turn `turnCount++`. Counted from
+    // the full unsliced history so it survives compaction and is independent of
+    // the viewer's trust class.
+    this.turnCount = allDbMessages.filter((m) =>
+      startsNewTurn(m.role, m.content),
+    ).length;
 
     const conv = getConversation(this.conversationId);
     this.conversationType = conv?.conversationType ?? undefined;
@@ -855,12 +905,12 @@ export class Conversation {
     // than exist. Slack chronological context is a separate consumer that
     // applies its own trust filtering downstream, so it reads the raw
     // mirrored count rather than this in-context boundary.
-    const inContextCompactedCount = isUntrustedTrustClass(trustClass)
-      ? 0
-      : Math.min(this.contextCompactedMessageCount, dbMessages.length);
-    const contextSummaryForHistory = isUntrustedTrustClass(trustClass)
-      ? null
-      : this.contextSummary?.trim() || null;
+    const inContextCompactedCount = canAccessMemory
+      ? Math.min(this.contextCompactedMessageCount, dbMessages.length)
+      : 0;
+    const contextSummaryForHistory = canAccessMemory
+      ? this.contextSummary?.trim() || null
+      : null;
 
     // Every injection-strip event (`/clean` or compaction) updates
     // `historyStrippedAt`. Messages older than this should skip metadata

package/src/daemon/disk-pressure-policy.ts

@@ -1,5 +1,6 @@
 import type { InterfaceId } from "../channels/types.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
+import { resolveCapabilities } from "../runtime/capabilities.js";
 import type { DiskPressureStatus } from "./disk-pressure-guard.js";
 import type { ConversationType } from "./message-types/shared.js";
 import type { TrustContext } from "./trust-context.js";
@@ -74,11 +75,11 @@ export function classifyDiskPressureTurnPolicy(
   }
 
   const trustClass = metadata.trustContext?.trustClass;
-  if (trustClass === "guardian") {
+  if (resolveCapabilities(trustClass).canActUnderDiskPressureCleanup) {
     return { action: "allow-cleanup-mode", reason: "guardian" };
   }
 
-  if (trustClass === "trusted_contact") {
+  if (trustClass === "trusted_contact" || trustClass === "unverified_contact") {
     return { action: "block", reason: "trusted-contact" };
   }
 
@@ -156,6 +157,7 @@ function isExplicitLocalOwnerCleanupTurn(
   }
   return (
     metadata.trustContext == null ||
-    metadata.trustContext.trustClass === "guardian"
+    resolveCapabilities(metadata.trustContext.trustClass)
+      .canActUnderDiskPressureCleanup
   );
 }

package/src/daemon/handlers/__tests__/config-a2a-complete.test.ts

@@ -121,7 +121,6 @@ describe("completeA2AInvite", () => {
     const invite = findById(created.inviteId!);
     const contact = getContact(invite!.contactId);
     expect(contact!.channels[0]!.address).toBe("upper-case-id-123");
-    expect(contact!.channels[0]!.externalUserId).toBe("UPPER-Case-ID-123");
   });
 
   test("assistantContactMetadata has correct assistantId and gatewayUrl", () => {

package/src/daemon/handlers/__tests__/config-a2a-redeem.test.ts

@@ -120,7 +120,6 @@ describe("redeemA2AInvite", () => {
 
     const contact = getContact(result.contactId!);
     expect(contact!.channels[0]!.address).toBe("upper-case-sender-id");
-    expect(contact!.channels[0]!.externalUserId).toBe("UPPER-Case-SENDER-ID");
   });
 
   test("does not make outbound fetch calls", () => {

package/src/daemon/handlers/config-a2a.ts

@@ -221,7 +221,6 @@ export function completeA2AInvite(params: {
       {
         type: "a2a",
         address: params.acceptor.assistantId.toLowerCase(),
-        externalUserId: params.acceptor.assistantId,
         status: "active",
         policy: "allow",
       },
@@ -289,7 +288,6 @@ export function redeemA2AInvite(params: {
       {
         type: "a2a",
         address: params.sender.assistantId.toLowerCase(),
-        externalUserId: params.sender.assistantId,
         status: "active",
         policy: "allow",
       },

package/src/daemon/handlers/config-channels.ts

@@ -332,11 +332,9 @@ export async function verifyTrustedContact(
         channel: verificationChannel,
         expectedChatId: channel.externalChatId,
         expectedExternalUserId:
-          channel.externalUserId ??
-          (channel.address !== channel.externalChatId
+          channel.address !== channel.externalChatId
             ? channel.address
-            : undefined) ??
-          undefined,
+            : undefined,
         identityBindingStatus: "bound",
         destinationAddress: effectiveDestination,
         verificationPurpose: "trusted_contact",
@@ -409,17 +407,14 @@ export async function verifyTrustedContact(
 
   // --- Slack verification ---
   if (verificationChannel === "slack") {
-    const slackUserId =
-      channel.externalUserId ?? channel.address ?? destination;
+    const slackUserId = channel.address;
 
     const sessionResult = createOutboundSession({
       channel: verificationChannel,
       expectedExternalUserId:
-        channel.externalUserId ??
-        (channel.address !== channel.externalChatId
+        channel.address !== channel.externalChatId
           ? channel.address
-          : undefined) ??
-        undefined,
+          : undefined,
       expectedChatId: channel.externalChatId ?? undefined,
       identityBindingStatus: "bound",
       destinationAddress: slackUserId,

package/src/daemon/handlers/config-slack-channel.ts

@@ -28,6 +28,9 @@ import { log as _log } from "./shared.js";
 
 // -- Result type --
 
+export const SlackThreadMode = z.enum(["mention_only", "mention_then_thread"]);
+export type SlackThreadMode = z.infer<typeof SlackThreadMode>;
+
 export const SlackChannelConfigResultSchema = z.object({
   success: z.boolean(),
   hasBotToken: z.boolean(),
@@ -39,6 +42,7 @@ export const SlackChannelConfigResultSchema = z.object({
   teamUrl: z.string().optional(),
   botUserId: z.string().optional(),
   botUsername: z.string().optional(),
+  threadMode: SlackThreadMode,
   error: z.string().optional(),
   warning: z.string().optional(),
 });
@@ -129,6 +133,8 @@ export async function getSlackChannelConfig(): Promise<SlackChannelConfigResult>
     ensureUserTokenInjectionTemplates();
   }
 
+  const { threadMode } = getConfig().slack;
+
   return {
     success: true,
     hasBotToken,
@@ -140,6 +146,7 @@ export async function getSlackChannelConfig(): Promise<SlackChannelConfigResult>
     ...(teamUrl ? { teamUrl } : {}),
     ...(botUserId ? { botUserId } : {}),
     ...(botUsername ? { botUsername } : {}),
+    threadMode,
   };
 }
 
@@ -166,6 +173,7 @@ async function currentErrorSnapshot(
       !!(errConn && errConn.status === "active") &&
       errHasBotToken &&
       errHasAppToken,
+    threadMode: getConfig().slack.threadMode,
     error,
   };
 }
@@ -429,6 +437,7 @@ export async function setSlackChannelConfig(
     hasUserToken,
     connected: hasBotToken && hasAppToken,
     ...metadata,
+    threadMode: getConfig().slack.threadMode,
     ...(warning ? { warning } : {}),
   };
 }
@@ -466,6 +475,7 @@ export async function clearSlackUserToken(): Promise<SlackChannelConfigResult> {
       hasUserToken,
       connected:
         !!(conn && conn.status === "active") && hasBotToken && hasAppToken,
+      threadMode: getConfig().slack.threadMode,
       error:
         result === "not-found"
           ? "Slack user token not found in secure storage"
@@ -497,6 +507,7 @@ export async function clearSlackUserToken(): Promise<SlackChannelConfigResult> {
     ...(teamUrl ? { teamUrl } : {}),
     ...(botUserId ? { botUserId } : {}),
     ...(botUsername ? { botUsername } : {}),
+    threadMode: getConfig().slack.threadMode,
   };
 }
 
@@ -530,6 +541,7 @@ export async function clearSlackChannelConfig(): Promise<SlackChannelConfigResul
       hasUserToken,
       connected:
         !!(conn && conn.status === "active") && hasBotToken && hasAppToken,
+      threadMode: getConfig().slack.threadMode,
       error: "Failed to delete Slack channel credentials from secure storage",
     };
   }
@@ -556,5 +568,13 @@ export async function clearSlackChannelConfig(): Promise<SlackChannelConfigResul
     hasAppToken: false,
     hasUserToken: false,
     connected: false,
+    threadMode: "mention_only",
   };
 }
+
+export function patchSlackChannelConfig(threadMode: SlackThreadMode): void {
+  const raw = loadRawConfig();
+  setNestedValue(raw, "slack.threadMode", threadMode);
+  saveRawConfig(raw);
+  invalidateConfigCache();
+}

package/src/daemon/handlers/conversations.ts

@@ -3,14 +3,21 @@ import { v4 as uuid } from "uuid";
 import { clearAll, getConversation } from "../../memory/conversation-crud.js";
 import { resolveConversationId } from "../../memory/conversation-key-store.js";
 import { broadcastMessage } from "../../runtime/assistant-event-hub.js";
+import { resolveCapabilities } from "../../runtime/capabilities.js";
 import { getSubagentManager } from "../../subagent/index.js";
 import { createAbortReason } from "../../util/abort-reasons.js";
+import { UserError } from "../../util/errors.js";
 import { truncate } from "../../util/truncate.js";
 import { regenerate } from "../conversation-history.js";
+import {
+  buildSlashContext,
+  formatCleanResult,
+} from "../conversation-process.js";
 import {
   conversationEntries,
   findConversation,
 } from "../conversation-registry.js";
+import { resolveSlash } from "../conversation-slash.js";
 import {
   clearAllActiveConversations,
   getOrCreateConversation,
@@ -18,6 +25,7 @@ import {
 } from "../conversation-store.js";
 import type { ConfirmationResponse } from "../message-protocol.js";
 import { normalizeConversationType } from "../message-protocol.js";
+import { INTERNAL_GUARDIAN_TRUST_CONTEXT } from "../trust-context.js";
 import { log } from "./shared.js";
 
 export function handleConfirmationResponse(msg: ConfirmationResponse): void {
@@ -98,6 +106,12 @@ export function cancelGeneration(conversationId: string): boolean {
   // being cancelled, so enqueuing synthetic messages would trigger
   // unwanted model activity after the user pressed stop.
   getSubagentManager().abortAllForParent(conversationId);
+  // The processing flag is cleared by the in-flight turn's `finally`, not here.
+  // Abort propagates into the provider call and tool execution (and is backed
+  // by the agent loop's abort watchdog), so the turn reaches its `finally`
+  // within a bounded time and tears down its own state there — which publishes
+  // the metadata sync invalidation that drives clients to the authoritative
+  // idle state.
   return true;
 }
 
@@ -118,6 +132,99 @@ export async function undoLastMessage(
   const removedCount = conversation.undo();
   return { removedCount };
 }
+
+export interface MetaSlashCommandResult {
+  kind: "clean" | "info";
+  /** User-facing text to render (clean stats card or info listing). */
+  text: string;
+  /** Present for `/clean`: the post-strip context-window usage. */
+  contextUsage?: {
+    tokens: number;
+    maxTokens: number | null;
+    fillRatio: number | null;
+  };
+}
+
+/**
+ * Resolve a local meta slash command (`/clean`, `/status`, `/commands`,
+ * `/models`) for a conversation without running a turn: no user/assistant
+ * messages are persisted and no streaming/turn events are emitted. `/clean`
+ * additionally strips runtime injections via `forceClean`.
+ *
+ * Returns null if the conversation cannot be resolved. Throws `UserError` for
+ * commands that are not local meta commands (`/compact`, passthrough) — those
+ * must be sent as a normal message so they run a real turn.
+ */
+export async function resolveMetaSlashCommand(
+  conversationId: string,
+  command: string,
+): Promise<MetaSlashCommandResult | null> {
+  const resolvedId = resolveConversationId(conversationId);
+  if (!resolvedId) {
+    return null;
+  }
+  const conversation = await getOrCreateConversation(resolvedId);
+  touchConversation(resolvedId);
+
+  // Meta commands reload (and, for `/clean`, strip) the in-memory history
+  // array. Running that against an in-flight turn would corrupt the messages
+  // the active agent loop is iterating over, and mutating trustContext would
+  // elevate that turn's actor trust to guardian for subsequent tool calls.
+  if (conversation.isProcessing()) {
+    throw new UserError(
+      `\`${command.trim()}\` cannot run while the assistant is responding.`,
+    );
+  }
+
+  // Owner self-maintenance operates on the full (guardian) history. Without a
+  // trusted context, `loadFromDb` filters to non-guardian provenance — so a
+  // guardian-authored conversation would report 0 preserved / 0 messages.
+  // Temporarily apply the guardian context for hydration and restore it
+  // afterward so the elevated class never leaks into a later turn's snapshot.
+  const priorTrustContext = conversation.trustContext;
+  if (!resolveCapabilities(priorTrustContext?.trustClass).canAccessMemory) {
+    conversation.setTrustContext(INTERNAL_GUARDIAN_TRUST_CONTEXT);
+  }
+  try {
+    await conversation.ensureActorScopedHistory();
+
+    const slashResult = await resolveSlash(
+      command,
+      buildSlashContext(command, conversation),
+    );
+
+    if (slashResult.kind === "clean") {
+      const result = await conversation.forceClean();
+      return {
+        kind: "clean",
+        text: formatCleanResult(result),
+        contextUsage: {
+          tokens: result.estimatedInputTokens,
+          maxTokens: result.maxInputTokens,
+          fillRatio:
+            result.maxInputTokens > 0
+              ? result.estimatedInputTokens / result.maxInputTokens
+              : null,
+        },
+      };
+    }
+
+    if (slashResult.kind === "unknown") {
+      return { kind: "info", text: slashResult.message };
+    }
+
+    // `compact` / `passthrough` are real turns, not local meta commands.
+    throw new UserError(`\`${command.trim()}\` is not a local meta command.`);
+  } finally {
+    // Only undo the temporary guardian context this handler installed. If a
+    // new turn started at an `await` boundary and legitimately updated
+    // trustContext, the reference will differ and we leave it alone.
+    if (conversation.trustContext === INTERNAL_GUARDIAN_TRUST_CONTEXT) {
+      conversation.setTrustContext(priorTrustContext ?? null);
+    }
+  }
+}
+
 /**
  * Regenerate the last assistant response for a conversation. The caller provides
  * a `sendEvent` callback for delivering streaming events via HTTP/SSE.

package/src/daemon/host-browser-proxy.ts

@@ -9,6 +9,7 @@ import * as pendingInteractions from "../runtime/pending-interactions.js";
 import type { ToolExecutionResult } from "../tools/types.js";
 import { AssistantError, ErrorCode } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
+import { sleep } from "../util/retry.js";
 import type { HostBrowserRequest } from "./message-types/host-browser.js";
 
 /** Distributive omit that preserves union variant fields. */
@@ -24,6 +25,16 @@ export type HostBrowserInput = DistributiveOmit<
 
 const log = getLogger("host-browser-proxy");
 
+/**
+ * Grace window for a flapping extension SSE connection. The Chrome
+ * extension's stream can briefly drop and reconnect (MV3 service-worker
+ * churn); without a short wait, a dispatch landing in a "down" blip
+ * hard-fails even though the extension is effectively connected. Well
+ * under the request-layer timeout (default 30s).
+ */
+const EXTENSION_RECONNECT_GRACE_MS = 3_000;
+const EXTENSION_RECONNECT_POLL_MS = 250;
+
 /**
  * Extension-only pseudo-CDP methods (Vellum.listTabs, Vellum.selectTab,
  * Vellum.closeTab, Vellum.createTab, Vellum.findTab, Vellum.attach,
@@ -196,6 +207,36 @@ export class HostBrowserProxy {
     );
   }
 
+  /**
+   * Poll until the extension client that dispatch will route to is
+   * connected, or `timeoutMs` elapses. Absorbs brief SSE reconnect blips
+   * so extension-pinned dispatch doesn't hard-fail on a momentary gap.
+   *
+   * When `targetClientId` is supplied, waits for that *exact* client —
+   * `request()` resolves the target by id, so waiting for any sibling
+   * extension (multi-install setups) would return early and still fail.
+   * Otherwise waits for any extension owned by the actor, matching the
+   * auto-resolution preference. Returns the final availability; callers
+   * proceed to dispatch regardless (which still surfaces the typed "no
+   * Chrome Extension connected" error if absent).
+   */
+  async waitForExtensionClient(
+    sourceActorPrincipalId?: string,
+    targetClientId?: string,
+    timeoutMs = EXTENSION_RECONNECT_GRACE_MS,
+  ): Promise<boolean> {
+    const connected = () =>
+      targetClientId != null
+        ? assistantEventHub.getClientById(targetClientId) !== undefined
+        : this.hasExtensionClient(sourceActorPrincipalId);
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      if (connected()) return true;
+      if (Date.now() >= deadline) return false;
+      await sleep(EXTENSION_RECONNECT_POLL_MS);
+    }
+  }
+
   /**
    * Send a host_browser request to the connected extension/macOS bridge.
    *