@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/src/daemon/conversation-surfaces.ts

@@ -18,7 +18,11 @@ import {
   assistantEventHub,
   broadcastMessage,
 } from "../runtime/assistant-event-hub.js";
-import { enforceSameActorOrErrorResult } from "../runtime/auth/same-actor.js";
+import {
+  ambiguousSameUserError,
+  enforceSameActorOrErrorResult,
+  pickSameUserAutoResolve,
+} from "../runtime/auth/same-actor.js";
 import type {
   InteractiveUiRequest,
   InteractiveUiResult,
@@ -29,14 +33,18 @@ import { isPlainObject } from "../util/object.js";
 import { buildConversationErrorMessage } from "./conversation-error.js";
 import { launchConversation } from "./conversation-launch.js";
 import type { EnqueueMessageOptions } from "./conversation-messaging.js";
+import type { ProcessMessageOptions } from "./conversation-process.js";
 import type { HostAppControlProxy } from "./host-app-control-proxy.js";
 import type { HostCuProxy } from "./host-cu-proxy.js";
 import type {
   CardSurfaceData,
+  ChoiceSurfaceData,
   ConfirmationSurfaceData,
+  CopyBlockSurfaceData,
   DynamicPageSurfaceData,
   FormSurfaceData,
   ListSurfaceData,
+  OAuthConnectSurfaceData,
   ServerMessage,
   SurfaceData,
   SurfaceType,
@@ -390,6 +398,107 @@ function normalizeTaskProgressCardPatch(
   return normalizedPatch;
 }
 
+function normalizeChoiceShowData(
+  rawData: Record<string, unknown>,
+): ChoiceSurfaceData {
+  const options = Array.isArray(rawData.options)
+    ? rawData.options
+        .filter((option): option is Record<string, unknown> =>
+          isPlainObject(option),
+        )
+        .map((option) => {
+          const id = typeof option.id === "string" ? option.id.trim() : "";
+          const title =
+            typeof option.title === "string"
+              ? option.title.trim()
+              : typeof option.label === "string"
+                ? option.label.trim()
+                : "";
+          if (!id || !title) return null;
+          return {
+            id,
+            title,
+            ...(typeof option.description === "string"
+              ? { description: option.description }
+              : {}),
+            ...(option.recommended === true ? { recommended: true } : {}),
+            ...(isPlainObject(option.data)
+              ? { data: option.data as Record<string, unknown> }
+              : {}),
+          };
+        })
+        .filter(
+          (option): option is NonNullable<typeof option> => option !== null,
+        )
+    : [];
+
+  return {
+    ...(typeof rawData.description === "string"
+      ? { description: rawData.description }
+      : {}),
+    options,
+    selectionMode: rawData.selectionMode === "multiple" ? "multiple" : "single",
+    ...(typeof rawData.submitLabel === "string"
+      ? { submitLabel: rawData.submitLabel }
+      : {}),
+    ...(typeof rawData.commitOnSelect === "boolean"
+      ? { commitOnSelect: rawData.commitOnSelect }
+      : {}),
+  };
+}
+
+function normalizeCopyBlockShowData(
+  rawData: Record<string, unknown>,
+): CopyBlockSurfaceData {
+  return {
+    text: typeof rawData.text === "string" ? rawData.text : "",
+    ...(typeof rawData.label === "string" ? { label: rawData.label } : {}),
+    ...(typeof rawData.language === "string"
+      ? { language: rawData.language }
+      : {}),
+  };
+}
+
+function normalizeOAuthConnectShowData(
+  rawData: Record<string, unknown>,
+): OAuthConnectSurfaceData {
+  return {
+    providerKey:
+      typeof rawData.providerKey === "string" ? rawData.providerKey.trim() : "",
+    ...(typeof rawData.displayName === "string"
+      ? { displayName: rawData.displayName }
+      : {}),
+    ...(typeof rawData.description === "string"
+      ? { description: rawData.description }
+      : {}),
+    ...(typeof rawData.logoUrl === "string" || rawData.logoUrl === null
+      ? { logoUrl: rawData.logoUrl }
+      : {}),
+  };
+}
+
+function buildChoiceActions(data: ChoiceSurfaceData): Array<{
+  id: string;
+  label: string;
+  style?: string;
+  data?: Record<string, unknown>;
+}> {
+  return data.options.map((option) => ({
+    id: option.id,
+    label: option.title,
+    style: option.recommended ? "primary" : "secondary",
+    data: {
+      choiceId: option.id,
+      choiceTitle: option.title,
+      selectedIds: [option.id],
+      selectedTitles: [option.title],
+      ...(option.description ? { choiceDescription: option.description } : {}),
+      ...(option.recommended ? { recommended: true } : {}),
+      ...(option.data ?? {}),
+    },
+  }));
+}
+
 function isTaskProgressCardData(data: SurfaceData | Record<string, unknown>) {
   return (data as Record<string, unknown>).template === "task_progress";
 }
@@ -503,6 +612,7 @@ export interface SurfaceConversationContext {
     }>;
     display?: string;
     persistent?: boolean;
+    toolCallId?: string;
   }>;
   /** Optional proxy for delegating computer-use actions to a connected desktop client. */
   hostCuProxy?: HostCuProxy;
@@ -524,16 +634,7 @@ export interface SurfaceConversationContext {
     rejected?: boolean;
   };
   getQueueDepth(): number;
-  processMessage(
-    content: string,
-    attachments: UserMessageAttachment[],
-    onEvent?: (msg: ServerMessage) => void,
-    requestId?: string,
-    activeSurfaceId?: string,
-    currentPage?: string,
-    options?: { isInteractive?: boolean },
-    displayContent?: string,
-  ): Promise<string>;
+  processMessage(options: ProcessMessageOptions): Promise<string>;
   /** Serialize operations on a given surface to prevent read-modify-write races. */
   withSurface<T>(surfaceId: string, fn: () => T | Promise<T>): Promise<T>;
 }
@@ -1492,16 +1593,14 @@ export async function handleSurfaceAction(
       "Processing surface action immediately (history-restored) with attachments",
     );
     ctx
-      .processMessage(
+      .processMessage({
         content,
         attachments,
         onEvent,
         requestId,
-        surfaceId,
-        undefined,
-        undefined,
+        activeSurfaceId: surfaceId,
         displayContent,
-      )
+      })
       .catch((err) => {
         const message = err instanceof Error ? err.message : String(err);
         log.error(
@@ -1704,6 +1803,8 @@ export async function handleSurfaceAction(
   // been accepted. Deferred until after rejection check so the surface stays
   // active and retryable if the queue was full.
   const ONE_SHOT_SURFACE_TYPES = [
+    "choice",
+    "oauth_connect",
     "form",
     "confirmation",
     "file_upload",
@@ -1779,16 +1880,14 @@ export async function handleSurfaceAction(
     "Processing surface action as follow-up with attachments",
   );
   ctx
-    .processMessage(
+    .processMessage({
       content,
-      pendingAttachments,
+      attachments: pendingAttachments,
       onEvent,
       requestId,
-      surfaceId,
-      undefined,
-      undefined,
+      activeSurfaceId: surfaceId,
       displayContent,
-    )
+    })
     .catch((err) => {
       const message = err instanceof Error ? err.message : String(err);
       log.error(
@@ -1867,6 +1966,12 @@ export function buildCompletionSummary(
   data?: Record<string, unknown>,
   surfaceData?: Record<string, unknown>,
 ): string {
+  const selectedTitles = Array.isArray(data?.selectedTitles)
+    ? data.selectedTitles.filter(
+        (title): title is string => typeof title === "string",
+      )
+    : [];
+
   if (surfaceType === "confirmation") {
     if (actionId === "cancel") {
       const cancelLabel =
@@ -1899,6 +2004,43 @@ export function buildCompletionSummary(
   if (surfaceType === "form") {
     return "Submitted";
   }
+  if (surfaceType === "choice" && data) {
+    const choiceTitle =
+      typeof data.choiceTitle === "string" ? data.choiceTitle : undefined;
+    if (choiceTitle) return `User chose: "${choiceTitle}"`;
+    if (selectedTitles.length === 1)
+      return `User chose: "${selectedTitles[0]}"`;
+    if (selectedTitles.length > 1) {
+      return `User chose ${selectedTitles.length} options: ${selectedTitles
+        .map((title) => `"${title}"`)
+        .join(", ")}`;
+    }
+    return `User chose: ${actionId}`;
+  }
+  if (surfaceType === "oauth_connect") {
+    const providerLabel =
+      typeof data?.providerLabel === "string"
+        ? data.providerLabel
+        : typeof data?.displayName === "string"
+          ? data.displayName
+          : typeof data?.providerKey === "string"
+            ? data.providerKey
+            : "OAuth";
+    const accountLabel =
+      typeof data?.accountLabel === "string" ? data.accountLabel : undefined;
+    if (actionId === "connect" || data?.status === "connected") {
+      return accountLabel
+        ? `Connected ${providerLabel}: ${accountLabel}`
+        : `Connected ${providerLabel}`;
+    }
+    if (actionId === "cancel" || data?.status === "cancelled") {
+      return `Cancelled ${providerLabel} connection`;
+    }
+    if (data?.status === "error") {
+      return `${providerLabel} connection failed`;
+    }
+    return `${providerLabel} connection ${actionId}`;
+  }
   if (surfaceType === "list" && data) {
     const selectedIds = data.selectedIds as string[] | undefined;
     const actionSuffix = actionId ? ` (action: ${actionId})` : "";
@@ -1929,6 +2071,11 @@ function buildUserFacingLabel(
   surfaceData?: Record<string, unknown>,
 ): string {
   const count = (data?.selectedIds as string[] | undefined)?.length;
+  const selectedTitles = Array.isArray(data?.selectedTitles)
+    ? data.selectedTitles.filter(
+        (title): title is string => typeof title === "string",
+      )
+    : [];
 
   if (surfaceType === "confirmation") {
     if (actionId === "cancel") {
@@ -1955,6 +2102,39 @@ function buildUserFacingLabel(
     return `Selected: ${actionId}`;
   }
   if (surfaceType === "form") return "Submitted";
+  if (surfaceType === "choice") {
+    const choiceTitle =
+      typeof data?.choiceTitle === "string" ? data.choiceTitle : undefined;
+    if (choiceTitle) return choiceTitle;
+    if (selectedTitles.length === 1) return selectedTitles[0];
+    if (selectedTitles.length > 1)
+      return `Selected ${selectedTitles.length} options`;
+    return "Selected";
+  }
+  if (surfaceType === "oauth_connect") {
+    const providerLabel =
+      typeof data?.providerLabel === "string"
+        ? data.providerLabel
+        : typeof data?.displayName === "string"
+          ? data.displayName
+          : typeof data?.providerKey === "string"
+            ? data.providerKey
+            : "OAuth";
+    const accountLabel =
+      typeof data?.accountLabel === "string" ? data.accountLabel : undefined;
+    if (actionId === "connect" || data?.status === "connected") {
+      return accountLabel
+        ? `Connected ${providerLabel}: ${accountLabel}`
+        : `Connected ${providerLabel}`;
+    }
+    if (actionId === "cancel" || data?.status === "cancelled") {
+      return "Cancelled";
+    }
+    if (data?.status === "error") {
+      return `${providerLabel} connection failed`;
+    }
+    return `Selected: ${actionId}`;
+  }
 
   // Table / list selection actions
   if (count) {
@@ -1978,6 +2158,7 @@ export async function surfaceProxyResolver(
   toolName: string,
   input: Record<string, unknown>,
   signal?: AbortSignal,
+  toolUseId?: string,
 ): Promise<ToolExecutionResult> {
   // Route CU proxy tools (all computer_use_* action tools)
   if (toolName.startsWith("computer_use_")) {
@@ -2042,44 +2223,29 @@ export async function surfaceProxyResolver(
       if (rejection) return rejection;
     }
 
-    // Guard: require explicit targeting when multiple same-user CU-capable
-    // clients are connected. The tool schemas document target_client_id as
-    // "required when multiple clients support host_cu" but nothing enforced
-    // it at runtime until now. Without this guard, the request would
-    // broadcast to all capable clients simultaneously, causing the same CU
-    // action to execute on multiple machines. The filter mirrors
-    // HostFileProxy's auto-resolve: only same-user clients participate, so
-    // a cross-user client connected to the same daemon does not falsely
-    // trigger this ambiguity error.
-    //
-    // Asymmetry with host_bash / host_file (host-shell.ts): the bash/file
-    // guard additionally checks `transportInterface != null &&
-    // !supportsHostProxy(transportInterface)` and so only fires for non-host-
-    // proxy transports (web, Slack). For CU that check would be a no-op:
-    // every host_cu-capable client is host-proxy-capable by definition
-    // (host_cu only ships on macOS and the Chrome extension), so there is no
-    // host_cu-capable transport for which auto-routing-to-self would be
-    // appropriate. We therefore fire whenever there is genuine ambiguity.
+    // Untargeted CU must resolve to exactly one same-user capable client
+    // before dispatch. Otherwise the proxy would broadcast without a target
+    // actor binding, which is unsafe in shared runtimes.
     if (targetClientId == null) {
-      const allCuClients = assistantEventHub.listClientsByCapability("host_cu");
-      const sameUserCuClients = allCuClients.filter(
-        (c) => c.actorPrincipalId === sourceActorPrincipalId,
-      );
-      if (sameUserCuClients.length > 1) {
+      const resolved = pickSameUserAutoResolve({
+        hub: assistantEventHub,
+        capability: "host_cu",
+        sourceActorPrincipalId,
+      });
+      if (resolved.kind === "ambiguous") {
+        return ambiguousSameUserError("host_cu");
+      }
+      if (resolved.kind === "match") {
+        targetClientId = resolved.clientId;
+      } else if (
+        assistantEventHub.listClientsByCapability("host_cu").length > 0
+      ) {
         return {
-          content: `Error: multiple clients support host_cu. Specify which client to target with \`target_client_id\`. Run \`assistant clients list --capability host_cu\` to see client IDs and labels.`,
+          content:
+            "Computer use is not available for the current actor. Connect a host_cu-capable client as the same user.",
           isError: true,
         };
       }
-      // When cross-user host_cu clients are connected, we MUST auto-resolve
-      // to the unique same-user client (or fail explicitly) — otherwise the
-      // proxy would broadcast untargeted and the CU action would reach the
-      // cross-user client too. Setting targetClientId here forces the proxy
-      // to deliver only to that client, with the same-user check below as
-      // belt-and-suspenders.
-      if (sameUserCuClients.length === 1 && allCuClients.length > 1) {
-        targetClientId = sameUserCuClients[0].clientId;
-      }
     }
 
     ctx.hostCuProxy.recordAction(toolName, input, reasoning);
@@ -2164,24 +2330,25 @@ export async function surfaceProxyResolver(
     }
 
     if (targetClientId == null) {
-      const allAcClients =
-        assistantEventHub.listClientsByCapability("host_app_control");
-      const sameUserAcClients = allAcClients.filter(
-        (c) => c.actorPrincipalId === sourceActorPrincipalId,
-      );
-      if (sameUserAcClients.length > 1) {
+      const resolved = pickSameUserAutoResolve({
+        hub: assistantEventHub,
+        capability: "host_app_control",
+        sourceActorPrincipalId,
+      });
+      if (resolved.kind === "ambiguous") {
+        return ambiguousSameUserError("host_app_control");
+      }
+      if (resolved.kind === "match") {
+        targetClientId = resolved.clientId;
+      } else if (
+        assistantEventHub.listClientsByCapability("host_app_control").length > 0
+      ) {
         return {
-          content: `Error: multiple clients support host_app_control. Specify which client to target with \`target_client_id\`. Run \`assistant clients list --capability host_app_control\` to see client IDs and labels.`,
+          content:
+            "App control is not available for the current actor. Connect a host_app_control-capable client as the same user.",
           isError: true,
         };
       }
-      // When cross-user host_app_control clients are connected, auto-
-      // resolve to the unique same-user client. Otherwise the proxy would
-      // dispatch untargeted and the action could reach a cross-user
-      // client. Belt-and-suspenders: the proxy re-checks same-user.
-      if (sameUserAcClients.length === 1 && allAcClients.length > 1) {
-        targetClientId = sameUserAcClients[0].clientId;
-      }
     }
 
     // The TS `HostAppControlInput` (and the Swift mirror) is a discriminated
@@ -2233,11 +2400,17 @@ export async function surfaceProxyResolver(
     const data = (
       surfaceType === "card"
         ? normalizeCardShowData(input, rawData)
-        : surfaceType === "dynamic_page"
-          ? normalizeDynamicPageShowData(input, rawData)
-          : rawData
+        : surfaceType === "choice"
+          ? normalizeChoiceShowData(rawData)
+          : surfaceType === "copy_block"
+            ? normalizeCopyBlockShowData(rawData)
+            : surfaceType === "oauth_connect"
+              ? normalizeOAuthConnectShowData(rawData)
+              : surfaceType === "dynamic_page"
+                ? normalizeDynamicPageShowData(input, rawData)
+                : rawData
     ) as SurfaceData;
-    const actions = input.actions as
+    const inputActions = input.actions as
       | Array<{
           id: string;
           label: string;
@@ -2245,8 +2418,33 @@ export async function surfaceProxyResolver(
           data?: Record<string, unknown>;
         }>
       | undefined;
+    const actions =
+      surfaceType === "choice"
+        ? buildChoiceActions(data as ChoiceSurfaceData)
+        : inputActions;
     // Interactive surfaces default to awaiting user action.
     const hasActions = Array.isArray(actions) && actions.length > 0;
+    if (surfaceType === "choice" && !hasActions) {
+      return {
+        content:
+          "choice surfaces require at least one option with both id and title.",
+        isError: true,
+      };
+    }
+    const oauthProviderKey =
+      surfaceType === "oauth_connect"
+        ? (data as unknown as Record<string, unknown>).providerKey
+        : undefined;
+    if (
+      surfaceType === "oauth_connect" &&
+      (typeof oauthProviderKey !== "string" ||
+        oauthProviderKey.trim().length === 0)
+    ) {
+      return {
+        content: "oauth_connect surfaces require data.providerKey.",
+        isError: true,
+      };
+    }
     const isInteractive =
       surfaceType === "card"
         ? hasActions
@@ -2323,6 +2521,7 @@ export async function surfaceProxyResolver(
       actions: mappedActions,
       display,
       ...(persistent ? { persistent: true } : {}),
+      ...(toolUseId ? { toolCallId: toolUseId } : {}),
     } as unknown as UiSurfaceShow);
 
     // Track surface for persistence with the message
@@ -2334,6 +2533,7 @@ export async function surfaceProxyResolver(
       actions: mappedActions,
       display,
       ...(persistent ? { persistent: true } : {}),
+      ...(toolUseId ? { toolCallId: toolUseId } : {}),
     });
 
     if (awaitAction) {
@@ -2507,6 +2707,7 @@ export async function surfaceProxyResolver(
         title: app.name,
         data: surfaceData,
         display: "inline",
+        ...(toolUseId ? { toolCallId: toolUseId } : {}),
       } as UiSurfaceShow);
 
       // Track for message persistence so the inline card survives history reload.
@@ -2516,6 +2717,7 @@ export async function surfaceProxyResolver(
         title: app.name,
         data: surfaceData,
         display: "inline",
+        ...(toolUseId ? { toolCallId: toolUseId } : {}),
       });
 
       return { content: JSON.stringify({ surfaceId, appId }), isError: false };
@@ -2534,6 +2736,7 @@ export async function surfaceProxyResolver(
       surfaceType: "dynamic_page",
       title: app.name,
       data: surfaceData,
+      ...(toolUseId ? { toolCallId: toolUseId } : {}),
     } as UiSurfaceShow);
 
     // Track surface for persistence
@@ -2542,6 +2745,7 @@ export async function surfaceProxyResolver(
       surfaceType: "dynamic_page",
       title: app.name,
       data: surfaceData,
+      ...(toolUseId ? { toolCallId: toolUseId } : {}),
     });
 
     ctx.pendingSurfaceActions.set(surfaceId, { surfaceType: "dynamic_page" });

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

@@ -11,14 +11,12 @@ import {
   type InterfaceId,
   supportsHostProxy,
 } from "../channels/types.js";
-import { isHttpAuthDisabled } from "../config/env.js";
 import { getIsPlatform } from "../config/env-registry.js";
 import { getConfig } from "../config/loader.js";
 import { getBindingByConversation } from "../memory/external-conversation-store.js";
 import type { PermissionPrompter } from "../permissions/prompter.js";
 import type { SecretPrompter } from "../permissions/secret-prompter.js";
 import type { Message, ToolDefinition } from "../providers/types.js";
-import type { TrustClass } from "../runtime/actor-trust-resolver.js";
 import { assistantEventHub } from "../runtime/assistant-event-hub.js";
 import { registerConversationSender } from "../tools/browser/browser-screencast.js";
 import type { ToolExecutor } from "../tools/executor.js";
@@ -48,27 +46,10 @@ import {
 } from "./doordash-steps.js";
 import type { ServerMessage, UiSurfaceShow } from "./message-protocol.js";
 import { runPostExecutionSideEffects } from "./tool-side-effects.js";
-import type { TrustContext } from "./trust-context.js";
+import { resolveTrustClass } from "./trust-context.js";
 
 const log = getLogger("conversation-tool-setup");
 
-/**
- * Resolve the effective trust class for tool execution.
- *
- * When HTTP auth is disabled (dev bypass), always returns `'guardian'`
- * so that control-plane gates don't block local development.
- *
- * When no trust context is available (e.g. desktop-only conversations that
- * don't go through channel trust resolution), defaults to `'unknown'`
- * to fail-closed.
- */
-export function resolveTrustClass(
-  trustContext: TrustContext | undefined,
-): TrustClass {
-  if (isHttpAuthDisabled()) return "guardian";
-  return trustContext?.trustClass ?? "unknown";
-}
-
 import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
 import { AUTO_PROFILE_KEY } from "../config/seed-inference-profiles.js";
 import {
@@ -97,7 +78,6 @@ export function createToolExecutor(
   input: Record<string, unknown>,
   onOutput?: (chunk: string) => void,
   toolUseId?: string,
-  turnContext?: import("../plugins/types.js").TurnContext,
 ) => Promise<ToolExecutionResult> {
   // Register the conversation's sendToClient for browser screencast surface messages
   registerConversationSender(ctx.conversationId, (msg) =>
@@ -109,7 +89,6 @@ export function createToolExecutor(
     input: Record<string, unknown>,
     onOutput?: (chunk: string) => void,
     toolUseId?: string,
-    turnContext?: import("../plugins/types.js").TurnContext,
   ) => {
     const { name: executionName, input: executionInput } =
       resolveToolInvocationAlias(name, input, ctx.allowedToolNames);
@@ -159,6 +138,7 @@ export function createToolExecutor(
         ctx.sendToClient(msg as ServerMessage);
         if (msg.type === "ui_surface_show") {
           const s = msg as unknown as UiSurfaceShow;
+          const surfaceToolCallId = s.toolCallId ?? toolUseId;
           ctx.currentTurnSurfaces.push({
             surfaceId: s.surfaceId,
             surfaceType: s.surfaceType,
@@ -167,6 +147,7 @@ export function createToolExecutor(
             actions: s.actions,
             display: s.display,
             ...(s.persistent ? { persistent: true } : {}),
+            ...(surfaceToolCallId ? { toolCallId: surfaceToolCallId } : {}),
           });
         }
       },
@@ -180,6 +161,7 @@ export function createToolExecutor(
           toolName,
           proxyInput,
           ctx.abortController?.signal,
+          toolUseId,
         ),
       proxyApprovalCallback: createProxyApprovalCallback(prompter, ctx),
       requestSecret: async (params) => {
@@ -254,12 +236,7 @@ export function createToolExecutor(
         };
       }
 
-      const result = await executor.execute(
-        toolName,
-        toolInput,
-        toolContext,
-        turnContext,
-      );
+      const result = await executor.execute(toolName, toolInput, toolContext);
       if (toolContext.approvedViaPrompt) {
         ctx.approvedViaPromptThisTurn = true;
       }
@@ -273,7 +250,6 @@ export function createToolExecutor(
       executionName,
       executionInput,
       toolContext,
-      turnContext,
     );
     if (toolContext.approvedViaPrompt) {
       ctx.approvedViaPromptThisTurn = true;

package/src/daemon/conversation-workspace.ts

@@ -4,6 +4,7 @@ import { getConversation } from "../memory/conversation-crud.js";
 import { resolveConversationDirectoryPaths } from "../memory/conversation-directories.js";
 import { renderWorkspaceTopLevelContext } from "../workspace/top-level-renderer.js";
 import { scanTopLevelDirectories } from "../workspace/top-level-scanner.js";
+import { findConversationOrSubagent } from "./conversation-registry.js";
 
 /**
  * Subset of Conversation state that workspace context helpers need.
@@ -25,6 +26,22 @@ export interface WorkspaceConversationContext {
   hostUsername?: string;
 }
 
+/**
+ * Resolve the live workspace top-level block for a conversation, refreshing
+ * the dirty-guarded cache first so a workspace-mutating tool's
+ * `markWorkspaceTopLevelDirty` from the prior turn is picked up. Returns `null`
+ * when no live conversation is found (no active conversation, or a context with
+ * no conversation id) or when the rendered context is empty.
+ */
+export function resolveWorkspaceTopLevelContext(
+  conversationId: string | undefined,
+): string | null {
+  const conversation = findConversationOrSubagent(conversationId);
+  if (!conversation) return null;
+  refreshWorkspaceTopLevelContextIfNeeded(conversation);
+  return conversation.workspaceTopLevelContext;
+}
+
 /** Refresh workspace top-level directory context if needed. */
 export function refreshWorkspaceTopLevelContextIfNeeded(
   ctx: WorkspaceConversationContext,