@vellumai/assistant 0.7.1 → 0.7.2

package/src/daemon/conversation-surfaces.ts

@@ -14,16 +14,20 @@ import {
   getMessages,
   updateMessageContent,
 } from "../memory/conversation-crud.js";
-import { broadcastMessage } from "../runtime/assistant-event-hub.js";
+import {
+  assistantEventHub,
+  broadcastMessage,
+} from "../runtime/assistant-event-hub.js";
 import type {
   InteractiveUiRequest,
   InteractiveUiResult,
-} from "../runtime/interactive-ui.js";
+} from "../runtime/interactive-ui-types.js";
 import type { ToolExecutionResult } from "../tools/types.js";
 import { getLogger } from "../util/logger.js";
 import { isPlainObject } from "../util/object.js";
 import { buildConversationErrorMessage } from "./conversation-error.js";
 import { launchConversation } from "./conversation-launch.js";
+import type { HostAppControlProxy } from "./host-app-control-proxy.js";
 import type { HostCuProxy } from "./host-cu-proxy.js";
 import type {
   CardSurfaceData,
@@ -41,6 +45,7 @@ import type {
 } from "./message-protocol.js";
 import { INTERACTIVE_SURFACE_TYPES } from "./message-protocol.js";
 import type { ConversationTransportMetadata } from "./message-types/conversations.js";
+import type { HostAppControlInput } from "./message-types/host-app-control.js";
 import type { UserMessageAttachment } from "./message-types/shared.js";
 import type { TrustContext } from "./trust-context.js";
 
@@ -320,6 +325,15 @@ export interface SurfaceConversationContext {
   }>;
   /** Optional proxy for delegating computer-use actions to a connected desktop client. */
   hostCuProxy?: HostCuProxy;
+  /** Optional proxy for delegating per-app app-control actions to a connected desktop client. */
+  hostAppControlProxy?: HostAppControlProxy;
+  /**
+   * Setter that lets the resolver detach the conversation's app-control proxy
+   * after `app_control_stop`. Disposes the existing proxy when transitioning
+   * to undefined so subsequent tool calls cleanly fail with "unavailable"
+   * rather than dispatching to a torn-down proxy.
+   */
+  setHostAppControlProxy?(proxy: HostAppControlProxy | undefined): void;
   /** True when no interactive client is connected (headless / channel-only). */
   readonly hasNoClient?: boolean;
   isProcessing(): boolean;
@@ -1206,7 +1220,11 @@ export async function handleSurfaceAction(
 
     const requestId = uuid();
     ctx.surfaceActionRequestIds.add(requestId);
-    const onEvent = (msg: ServerMessage) => broadcastMessage(msg);
+    // Pass conversationId so events without an inline conversationId (e.g.
+    // text_delta) are published with the correct conversation scope and
+    // reach the SSE subscriber filtered to this conversation.
+    const onEvent = (msg: ServerMessage) =>
+      broadcastMessage(msg, ctx.conversationId);
 
     ctx.traceEmitter.emit("request_received", "Surface action received", {
       requestId,
@@ -1440,7 +1458,11 @@ export async function handleSurfaceAction(
 
   const requestId = uuid();
   ctx.surfaceActionRequestIds.add(requestId);
-  const onEvent = (msg: ServerMessage) => broadcastMessage(msg);
+  // Pass conversationId so events without an inline conversationId (e.g.
+  // text_delta) are published with the correct conversation scope and
+  // reach the SSE subscriber filtered to this conversation.
+  const onEvent = (msg: ServerMessage) =>
+    broadcastMessage(msg, ctx.conversationId);
 
   ctx.traceEmitter.emit("request_received", "Surface action received", {
     requestId,
@@ -1761,6 +1783,56 @@ export async function surfaceProxyResolver(
     // Record the action and proxy to the connected desktop client
     const reasoning =
       typeof input.reasoning === "string" ? input.reasoning : undefined;
+    const targetClientId =
+      typeof input.target_client_id === "string" && input.target_client_id !== ""
+        ? input.target_client_id
+        : undefined;
+
+    // Validate targetClientId before recordAction so an invalid ID does not
+    // burn a step or pollute action history. (HostBashProxy / HostFileProxy
+    // both validate at the tool-resolution layer before incrementing any
+    // state; this mirrors that behaviour for CU.)
+    if (targetClientId != null) {
+      const client = assistantEventHub.getClientById(targetClientId);
+      if (!client) {
+        return {
+          content: `No connected client with id '${targetClientId}'. Run \`assistant clients list --capability host_cu\` to see available clients.`,
+          isError: true,
+        };
+      }
+      if (!client.capabilities.includes("host_cu")) {
+        return {
+          content: `Client '${targetClientId}' does not support host_cu. Run \`assistant clients list --capability host_cu\` to see available clients.`,
+          isError: true,
+        };
+      }
+    }
+
+    // Guard: require explicit targeting when multiple 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.
+    //
+    // 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.
+    if (targetClientId == null) {
+      const cuClients = assistantEventHub.listClientsByCapability("host_cu");
+      if (cuClients.length > 1) {
+        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.`,
+          isError: true,
+        };
+      }
+    }
+
     ctx.hostCuProxy.recordAction(toolName, input, reasoning);
     return ctx.hostCuProxy.request(
       toolName,
@@ -1769,6 +1841,55 @@ export async function surfaceProxyResolver(
       ctx.hostCuProxy.stepCount,
       reasoning,
       signal,
+      targetClientId,
+    );
+  }
+
+  // Route app-control proxy tools (all app_control_* tool variants)
+  if (toolName.startsWith("app_control_")) {
+    if (!ctx.hostAppControlProxy || !ctx.hostAppControlProxy.isAvailable()) {
+      return {
+        content:
+          "App control is not available — enable the `app-control` feature flag and connect a macOS client.",
+        isError: true,
+      };
+    }
+
+    // `app_control_stop` resolves immediately: tear down the proxy without
+    // a client round-trip. Mirrors CU's terminal-tool short-circuit
+    // (`computer_use_done` / `computer_use_respond`). Clear the
+    // conversation's reference (setter disposes the existing proxy) so a
+    // later `app_control_observe`/etc. cleanly fails with "unavailable"
+    // instead of dispatching against a torn-down proxy, and so a sibling
+    // conversation can acquire the released singleton lock without the
+    // disposed proxy still being addressable.
+    if (toolName === "app_control_stop") {
+      if (ctx.setHostAppControlProxy) {
+        ctx.setHostAppControlProxy(undefined);
+      } else {
+        ctx.hostAppControlProxy.dispose();
+      }
+      return { content: "App control stopped.", isError: false };
+    }
+
+    // The TS `HostAppControlInput` (and the Swift mirror) is a discriminated
+    // union on `tool` ("start" | "observe" | "press" | …). The agent's raw
+    // tool input only carries the action-specific payload (app, x/y, text,
+    // …) — the discriminator is implied by `toolName` (`app_control_<tool>`).
+    // Inject it here so the proxy's singleton-lock guard (`input.tool ===
+    // "start"`) and the Swift client's discriminated-union decoder both see
+    // the field they require.
+    const tool = toolName.slice("app_control_".length);
+    const inputWithTool = {
+      ...input,
+      tool,
+    } as unknown as HostAppControlInput;
+
+    return ctx.hostAppControlProxy.request(
+      toolName,
+      inputWithTool,
+      ctx.conversationId,
+      signal ?? new AbortController().signal,
     );
   }
 

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

@@ -13,12 +13,12 @@ import {
 } from "../channels/types.js";
 import { isHttpAuthDisabled } from "../config/env.js";
 import { getIsPlatform } from "../config/env-registry.js";
-import type { CesClient } from "../credential-execution/client.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 { coreAppProxyTools } from "../tools/apps/definitions.js";
 import { registerConversationSender } from "../tools/browser/browser-screencast.js";
 import type { ToolExecutor } from "../tools/executor.js";
@@ -43,7 +43,6 @@ import {
   projectSkillTools,
   type SkillProjectionCache,
 } from "./conversation-skill-tools.js";
-import type { SurfaceConversationContext } from "./conversation-surfaces.js";
 import { surfaceProxyResolver } from "./conversation-surfaces.js";
 import {
   isDoordashCommand,
@@ -72,49 +71,8 @@ export function resolveTrustClass(
   return trustContext?.trustClass ?? "unknown";
 }
 
-// ── Context Interface ────────────────────────────────────────────────
-
-/**
- * Subset of Conversation state that the tool executor callback reads at
- * call time (not construction time). These are captured by the
- * returned closure, so they must be live references.
- */
-export interface ToolSetupContext extends SurfaceConversationContext {
-  readonly conversationId: string;
-  assistantId?: string;
-  currentRequestId?: string;
-  workingDir: string;
-  abortController: AbortController | null;
-  /** When set, only tools in this set may execute during the current turn. */
-  allowedToolNames?: Set<string>;
-  /** Conversation memory policy used to propagate scopeId into ToolContext. */
-  memoryPolicy: { scopeId: string };
-  /** True when the conversation has no connected client (HTTP-only path). */
-  hasNoClient?: boolean;
-  /** When true, the conversation is executing a task run and must not become interactive. */
-  headlessLock?: boolean;
-  /** When set, this conversation is executing a task run. Used to retrieve ephemeral permission rules. */
-  taskRunId?: string;
-  /** Guardian runtime context for the conversation — trustClass is propagated into ToolContext for control-plane policy enforcement. */
-  trustContext?: TrustContext;
-  /** Voice/call session ID, if the conversation originates from a call. Propagated into ToolContext for scoped grant consumption. */
-  callSessionId?: string;
-  /** CES RPC client for credential execution operations. Injected when CES tools are enabled and the CES process is available. */
-  cesClient?: CesClient;
-  /** The interface ID of the connected client driving the current turn (e.g. "macos", "chrome-extension"). Propagated into ToolContext for browser backend selection. */
-  readonly transportInterface?: InterfaceId;
-
-  /** Turn-scoped flag: true when any tool call in the current turn received explicit user approval via interactive prompt. Cleared at turn end. */
-  approvedViaPromptThisTurn?: boolean;
-  /**
-   * Per-turn snapshot of the resolved inference-profile override, set by
-   * `runAgentLoopImpl`. Propagated into `ToolContext.overrideProfile` so
-   * tools that spawn nested invocations (e.g. `subagent_spawn`) can forward
-   * the override without round-tripping through a row read that would
-   * return `undefined` for the in-flight (background) subagent.
-   */
-  currentTurnOverrideProfile?: string;
-}
+import type { ToolSetupContext } from "./tool-setup-types.js";
+export type { ToolSetupContext } from "./tool-setup-types.js";
 
 // ── buildToolDefinitions ─────────────────────────────────────────────
 
@@ -258,16 +216,6 @@ export function createToolExecutor(
       // Clone to avoid mutating shared input objects
       const toolInput = { ...rawToolInput };
 
-      // Propagate outer activity when inner input lacks a valid one
-      if (
-        typeof input.activity === "string" &&
-        input.activity &&
-        (typeof toolInput.activity !== "string" ||
-          toolInput.activity.length === 0)
-      ) {
-        toolInput.activity = input.activity;
-      }
-
       if (!toolName) {
         return {
           content:
@@ -437,6 +385,19 @@ export function isToolActiveForContext(
     // Per-capability check is authoritative for structural support: if the
     // transport cannot service this capability, the tool is filtered out.
     if (transport && capability && !supportsHostProxy(transport, capability)) {
+      // Cross-client exception: allow host_bash for non-host-proxy interfaces when
+      // at least one capable client is connected via the event hub.
+      // Only applies to host_bash (not host_file, host_cu, host_browser — Phase 2).
+      // Excludes chrome-extension (security boundary: extension only gets host_browser)
+      // and hasNoClient turns (no interactive approval UI available).
+      if (
+        capability === "host_bash" &&
+        transport !== "chrome-extension" &&
+        !ctx.hasNoClient &&
+        assistantEventHub.listClientsByCapability("host_bash").length > 0
+      ) {
+        return true;
+      }
       return false;
     }
 

package/src/daemon/conversation.ts

@@ -117,6 +117,7 @@ import {
   createToolExecutor,
 } from "./conversation-tool-setup.js";
 import { refreshWorkspaceTopLevelContextIfNeeded as refreshWorkspaceImpl } from "./conversation-workspace.js";
+import type { HostAppControlProxy } from "./host-app-control-proxy.js";
 import { HostCuProxy } from "./host-cu-proxy.js";
 import type {
   ServerMessage,
@@ -204,6 +205,14 @@ export class Conversation {
   /** @internal */ taskRunId?: string;
   /** @internal */ callSessionId?: string;
   /** @internal */ hostCuProxy?: HostCuProxy;
+  /**
+   * Per-conversation host app-control proxy. Set via
+   * `setHostAppControlProxy` and disposed in `dispose()`. The
+   * `/v1/host-app-control-result` route forwards result payloads to the
+   * awaiting promise via this reference.
+   * @internal
+   */
+  hostAppControlProxy?: HostAppControlProxy;
   /** @internal */ cesClient?: CesClient;
   /** @internal */ readonly queue = new MessageQueue();
   /** @internal */ currentActiveSurfaceId?: string;
@@ -755,9 +764,12 @@ export class Conversation {
       clearTimeout(timer);
     }
     this.recentlyCompletedStandaloneSurfaces.clear();
-    // Only dispose the per-conversation CU proxy. Bash/File/Transfer are
-    // singletons — their lifecycle is managed by static disposeInstance().
+    // Only dispose the per-conversation CU and app-control proxies.
+    // Bash/File/Transfer are singletons — their lifecycle is managed by
+    // static disposeInstance().
     this.hostCuProxy?.dispose();
+    this.hostAppControlProxy?.dispose();
+    this.hostAppControlProxy = undefined;
     // CES client is owned by DaemonServer — just drop the reference.
     // Do NOT close it here; the server manages the CES lifecycle.
     this.cesClient = undefined;
@@ -936,6 +948,13 @@ export class Conversation {
     this.hostCuProxy = proxy;
   }
 
+  setHostAppControlProxy(proxy: HostAppControlProxy | undefined): void {
+    if (this.hostAppControlProxy && this.hostAppControlProxy !== proxy) {
+      this.hostAppControlProxy.dispose();
+    }
+    this.hostAppControlProxy = proxy;
+  }
+
   // ── Server-authoritative state signals ─────────────────────────────
 
   emitConfirmationStateChanged(

package/src/daemon/doordash-steps.ts

@@ -6,8 +6,8 @@
  */
 
 import { isPlainObject } from "../util/object.js";
-import type { ToolSetupContext } from "./conversation-tool-setup.js";
 import type { CardSurfaceData } from "./message-protocol.js";
+import type { ToolSetupContext } from "./tool-setup-types.js";
 
 interface DoordashStep {
   label: string;

package/src/daemon/handlers/shared.ts

@@ -52,7 +52,10 @@ export interface HistoryToolCall {
   riskReason?: string;
   /** ID of the trust rule that matched this invocation (if any). */
   matchedTrustRuleId?: string;
-  /** Whether the tool was auto-approved (true) or required explicit user input (false). */
+  /**
+   * @deprecated Use `approvalMode` and `approvalReason` instead.
+   * Kept for backward compatibility during the migration window.
+   */
   autoApproved?: boolean;
   /** How the approval decision was reached: prompted, auto, blocked, or unknown (legacy). */
   approvalMode?: string;

package/src/daemon/host-app-control-proxy.ts

@@ -0,0 +1,293 @@
+/**
+ * Host app-control proxy.
+ *
+ * Proxies app-control actions (start, observe, press, combo, type, click,
+ * drag, stop) to the desktop client. Targets a specific application by
+ * bundle ID or process name — distinct from the system-wide computer-use
+ * proxy ({@link HostCuProxy}).
+ *
+ * Lifecycle (pending map, timeout, abort SSE, dispose, isAvailable) lives
+ * in {@link HostProxyBase}; this class layers app-control-specific state
+ * (PNG-hash loop guard) and the result-payload → ToolExecutionResult
+ * translation on top.
+ *
+ * **Singleton lock.** Only one conversation may hold an active app-control
+ * session at a time. The lock is module-level (`activeAppControlConversationId`)
+ * because a session targets the user's actual desktop application, which
+ * is a host-wide resource. The lock is acquired on a successful
+ * `app_control_start` and released when the owning proxy's `dispose()`
+ * fires. A second conversation that calls `start` while the lock is held
+ * receives an `isError: true` tool result naming the holding conversation.
+ *
+ * **No step cap.** Unlike {@link HostCuProxy} which enforces a per-session
+ * step ceiling via `loadConfig().maxStepsPerSession`, app-control sessions
+ * are not capped. App-control flows are typically narrower (single-app,
+ * shorter horizons) and the loop guard plus user oversight are the
+ * intended safeguards.
+ */
+
+import { createHash } from "node:crypto";
+
+import type { ContentBlock } from "../providers/types.js";
+import type { ToolExecutionResult } from "../tools/types.js";
+import { getLogger } from "../util/logger.js";
+import { HostProxyBase, HostProxyRequestError } from "./host-proxy-base.js";
+import type {
+  HostAppControlInput,
+  HostAppControlResultPayload,
+} from "./message-types/host-app-control.js";
+
+const log = getLogger("host-app-control-proxy");
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const REQUEST_TIMEOUT_MS = 60 * 1000;
+// Threshold of 4 means the warning fires on the 5th identical observation:
+// the first observation establishes the baseline (count = 0), each
+// subsequent identical observation increments the counter, so count = 4 is
+// reached on the 5th total observation.
+const STUCK_REPEAT_THRESHOLD = 4;
+
+// ---------------------------------------------------------------------------
+// Tool name constants
+// ---------------------------------------------------------------------------
+//
+// Kept here (rather than imported from PR 5's tool registrations) so the
+// proxy is independently testable. PR 5 must use these same string values.
+
+const TOOL_START = "app_control_start";
+
+// ---------------------------------------------------------------------------
+// Module-level singleton lock
+// ---------------------------------------------------------------------------
+
+/**
+ * Conversation id that currently owns the active app-control session, or
+ * `undefined` if no session is active. Set on a successful
+ * `app_control_start`; cleared by the owning proxy's `dispose()`.
+ *
+ * Exported for test inspection only. Production code paths must not read
+ * or mutate this directly — use the proxy methods.
+ */
+let activeAppControlConversationId: string | undefined;
+
+/** Test-only helper: read current lock owner. */
+export function _getActiveAppControlConversationId(): string | undefined {
+  return activeAppControlConversationId;
+}
+
+/** Test-only helper: clear lock between test cases. */
+export function _resetActiveAppControlConversationId(): void {
+  activeAppControlConversationId = undefined;
+}
+
+// ---------------------------------------------------------------------------
+// HostAppControlProxy
+// ---------------------------------------------------------------------------
+
+export class HostAppControlProxy extends HostProxyBase<
+  HostAppControlInput,
+  HostAppControlResultPayload
+> {
+  /** Conversation that owns this proxy instance. Used by `dispose()` to release the singleton lock only when this proxy is the holder. */
+  private readonly conversationId: string;
+
+  /** sha256 hex of the most recent observation's `pngBase64`, or undefined. */
+  private lastObservationHash?: string;
+
+  /**
+   * Number of consecutive observations whose PNG hash matched the previous
+   * one. Reset to 0 when a different hash is observed. When this reaches
+   * {@link STUCK_REPEAT_THRESHOLD}, results carry a `"stuck"` warning.
+   */
+  private observationHashRepeatCount = 0;
+
+  constructor(conversationId: string) {
+    super({
+      capabilityName: "host_app_control",
+      requestEventName: "host_app_control_request",
+      cancelEventName: "host_app_control_cancel",
+      resultPendingKind: "host_app_control",
+      timeoutMs: REQUEST_TIMEOUT_MS,
+      disposedMessage: "Host app-control proxy disposed",
+    });
+    this.conversationId = conversationId;
+  }
+
+  // ---------------------------------------------------------------------------
+  // State accessors (testing / external inspection)
+  // ---------------------------------------------------------------------------
+
+  get observationRepeatCount(): number {
+    return this.observationHashRepeatCount;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public request entry point
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Dispatch an app-control tool call to the desktop client. Catches the
+   * base's typed lifecycle errors (timeout/aborted/disposed) and returns
+   * a `ToolExecutionResult` instead of letting them bubble.
+   */
+  async request(
+    toolName: string,
+    input: HostAppControlInput,
+    conversationId: string,
+    signal: AbortSignal,
+  ): Promise<ToolExecutionResult> {
+    if (signal.aborted) {
+      return { content: "Aborted", isError: true };
+    }
+
+    // Singleton-lock guard for `start`. Other tools assume a session
+    // already exists and are not gated here.
+    if (toolName === TOOL_START) {
+      if (
+        activeAppControlConversationId != null &&
+        activeAppControlConversationId !== conversationId
+      ) {
+        return {
+          content:
+            `Another conversation (${activeAppControlConversationId}) currently holds the ` +
+            `app-control session. Wait for it to finish, or call app_control_stop ` +
+            `from that conversation first.`,
+          isError: true,
+        };
+      }
+    }
+
+    try {
+      const payload = await this.dispatchRequest(
+        toolName,
+        input,
+        conversationId,
+        signal,
+      );
+      return this.handleSuccess(toolName, payload);
+    } catch (err) {
+      if (err instanceof HostProxyRequestError) {
+        if (err.reason === "timeout") {
+          log.warn({ toolName }, "Host app-control proxy request timed out");
+          return {
+            content:
+              "Host app-control proxy timed out waiting for client response",
+            isError: true,
+          };
+        }
+        if (err.reason === "aborted") {
+          return { content: "Aborted", isError: true };
+        }
+      }
+      // `disposed` and any other unexpected errors propagate.
+      throw err;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Result handling
+  // ---------------------------------------------------------------------------
+
+  private handleSuccess(
+    toolName: string,
+    payload: HostAppControlResultPayload,
+  ): ToolExecutionResult {
+    // Update PNG-hash loop tracking only for the "running" state — other
+    // states (missing/minimized) intentionally won't carry a
+    // representative window screenshot, so they should not feed the guard.
+    let stuck = false;
+    if (payload.state === "running" && payload.pngBase64) {
+      const hash = createHash("sha256").update(payload.pngBase64).digest("hex");
+      if (hash === this.lastObservationHash) {
+        this.observationHashRepeatCount++;
+      } else {
+        this.observationHashRepeatCount = 0;
+      }
+      this.lastObservationHash = hash;
+      if (this.observationHashRepeatCount >= STUCK_REPEAT_THRESHOLD) {
+        stuck = true;
+      }
+    }
+
+    // Acquire the singleton lock on a successful `start`.
+    if (toolName === TOOL_START && payload.state === "running") {
+      activeAppControlConversationId = this.conversationId;
+    }
+
+    return this.formatResult(payload, stuck);
+  }
+
+  private formatResult(
+    payload: HostAppControlResultPayload,
+    stuck: boolean,
+  ): ToolExecutionResult {
+    const parts: string[] = [];
+
+    if (stuck) {
+      parts.push(
+        `WARNING: ${this.observationHashRepeatCount} consecutive observations ` +
+          `produced an identical screenshot — the app appears stuck. Try a ` +
+          `different action or call app_control_stop and restart.`,
+      );
+      parts.push("");
+    }
+
+    parts.push(`State: ${payload.state}`);
+
+    if (payload.windowBounds) {
+      const { x, y, width, height } = payload.windowBounds;
+      parts.push(`Window bounds: ${width}x${height} at (${x}, ${y})`);
+    }
+
+    if (payload.executionResult) {
+      parts.push("");
+      parts.push(payload.executionResult);
+    }
+
+    const isError = payload.executionError != null;
+    const errorPrefix = isError
+      ? `Action failed: ${payload.executionError}`
+      : null;
+
+    const baseContent = parts.join("\n").trim() || `State: ${payload.state}`;
+    const content = errorPrefix
+      ? `${errorPrefix}\n\n${baseContent}`
+      : baseContent;
+
+    const contentBlocks: ContentBlock[] = [];
+    if (payload.pngBase64) {
+      contentBlocks.push({
+        type: "image",
+        source: {
+          type: "base64",
+          media_type: "image/png",
+          data: payload.pngBase64,
+        },
+      });
+    }
+
+    return {
+      content,
+      isError,
+      ...(contentBlocks.length > 0 ? { contentBlocks } : {}),
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Reject pending requests via the base, then release the singleton lock
+   * if this proxy is the holder. Idempotent: safe to call multiple times.
+   */
+  override dispose(): void {
+    super.dispose();
+    if (activeAppControlConversationId === this.conversationId) {
+      activeAppControlConversationId = undefined;
+    }
+  }
+}